Clients and Knowledge
Create and manage client workspaces, integration connect links and the Knowledge sources that ground content.
Clients — List
Section titled “Clients — List”GET /api/agent/v1/clients
List all clients for your organization.
Scope required: clients:read
Query parameters
Section titled “Query parameters”| Parameter | Type | Description |
|---|---|---|
limit |
integer | Max results (default 50, max 100) |
offset |
integer | Pagination offset (default 0) |
Response
Section titled “Response”{ "clients": [ { "id": "uuid", "name": "Acme Corp", "domain": "acme.com", "icon": "A", "color": "bg-blue-500", "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z" } ], "pagination": { "limit": 50, "offset": 0, "count": 1, "total": 1 }}Clients — Create
Section titled “Clients — Create”POST /api/agent/v1/clients
Create a new client.
Scope required: clients:write
Request body
Section titled “Request body”{ "name": "Acme Corp", "domain": "acme.com"}| Field | Type | Required | Description |
|---|---|---|---|
name |
string | Yes | Client name |
domain |
string | No | Client website domain |
icon |
string | No | Icon character (default: C) |
color |
string | No | Color class (default: bg-blue-500) |
knowledge_base |
object | No | Knowledge base data (writing style, brand context, reference docs) |
Idempotency: Include an Idempotency-Key header to safely retry requests. If the same key is reused within 24 hours, the cached response is returned without creating a duplicate client.
Response (201)
Section titled “Response (201)”{ "id": "uuid", "name": "Acme Corp", "domain": "acme.com", "icon": "A", "color": "bg-blue-500", "created_at": "2025-01-15T10:00:00.000Z"}Errors
Section titled “Errors”| HTTP | Code | Description |
|---|---|---|
| 409 | conflict |
A client with the same domain already exists |
Clients — Create Integration Connect Link
Section titled “Clients — Create Integration Connect Link”POST /api/agent/v1/clients/:id/connect-link
Create a secure browser handoff for Google authorization and GSC/GA4 property selection. The link expires after seven days. Creating a new link revokes any older active connect link for the client.
Google consent cannot be completed headlessly: return the URL to the user and ask them to open it in a browser. Treat the URL as a secret while it is active.
Scope required: clients:write
Response (201)
Section titled “Response (201)”{ "client": { "id": "uuid", "name": "Acme Corp", "domain": "acme.com" }, "url": "https://app.rankability.com/connect/one-time-token", "expires_at": "2025-01-22T10:00:00.000Z", "previous_link_revoked": false, "next_action": "Open the URL in a browser to authorize Google and select the GSC and GA4 properties."}After the user completes the browser flow, call GET /clients/:id to verify
the selected integrations.
Clients — Get Detail
Section titled “Clients — Get Detail”GET /api/agent/v1/clients/:id
Get lightweight identity, integration, settings, and content-grounding details for a specific client. content_profile.brand_name is the effective brand Copywriter uses; brand_name_source identifies whether it came from the knowledge base or fell back to the workspace name. content_controls exposes the configured do_not_use, blocked_keywords, and excluded_topics arrays. tracker_identity.identity_classification separates reviewed primary aliases from distinct related entities and marks undecided or invalid settings explicitly. Its basis is current workspace settings, not scan-time evidence; the compatibility brand_aliases list alone does not prove identity equivalence. tracker_identity.gbp_location_name is the connected primary GBP name when available; update a report’s explicit location identity through the Tracker project endpoint rather than editing the connection mirror.
Use tracker_identity.identity_classification to distinguish genuine aliases of the primary brand from separate related entities. It reads the canonical client profile and includes stable entity IDs, names, roles, aliases, profile version, and review time. state is reviewed when all approved names are assigned, review_required when names still need classification, or unavailable when the stored profile is invalid. A partially reviewed profile retains its valid assignments and lists undecided names in unclassified_names. Legacy profiles expose undecided names without inventing relationships. Suggested and rejected names do not become tracked entities.
The basis is always current_workspace_settings, not scan-time evidence. Do not use this response to rewrite saved report scores or claim that an entity was mentioned in an answer. Use the report’s own recorded identity and answer evidence for historical attribution. tracker_identity.brand_aliases remains the legacy approval list for compatibility; that flat list is not proof that every name identifies the primary brand. Review ambiguous names in Client settings instead of inferring a relationship.
Scope required: clients:read
Response
Section titled “Response”{ "id": "uuid", "name": "Acme Corp", "domain": "acme.com", "icon": "A", "color": "bg-blue-500", "content_profile": { "brand_name": "Acme", "brand_name_source": "knowledge_base", "tagline": "Make operations simple", "target_audience": "Operations leaders", "industry": "Software", "tone": "professional", "voice_summary": "Direct and practical", "unique_selling_propositions": [], "competitors": [] }, "content_controls": { "do_not_use": ["guaranteed"], "blocked_keywords": ["coupon"], "excluded_topics": ["politics"] }, "tracker_identity": { "brand_aliases": ["Acme Corporation", "Acme Software"], "identity_classification": { "basis": "current_workspace_settings", "state": "reviewed", "profile_version": 2, "reviewed_at": "2026-10-01T12:00:00Z", "entities": [ {"id": "primary", "name": "Acme", "aliases": ["Acme Corporation"], "role": "primary"}, {"id": "product-acme-software", "name": "Acme Software", "aliases": [], "role": "related"} ], "unclassified_names": [] }, "gbp_location_name": "Acme Downtown", "gbp_location_name_source": "connected_gbp" }, "created_at": "2025-01-15T10:00:00.000Z", "updated_at": "2025-01-15T10:00:00.000Z"}Clients — Update
Section titled “Clients — Update”PATCH /api/agent/v1/clients/:id
Update a client. Only provided fields are updated.
Scope required: clients:write
Request body
Section titled “Request body”{ "name": "Acme Corp Updated", "domain": "newdomain.com", "brand_aliases": ["Acme Corporation", "Acme Software"]}| Field | Type | Description |
|---|---|---|
name |
string | Client name |
domain |
string | null | Client domain |
icon |
string | Icon character |
color |
string | Color class |
knowledge_base |
object | Knowledge base data |
knowledge_base_patch |
object | Merge selected Knowledge fields without clearing omitted sections |
brand_aliases |
string[] | null | Approved workspace Tracker aliases; null clears the workspace default. This does not re-score stored history. |
Response
Section titled “Response”Returns the updated client object. When aliases are supplied, tracker_identity.existing_tracker_history_rescored is false; use fresh report measurements until a separate stored-result re-score is available.
Clients — Delete
Section titled “Clients — Delete”DELETE /api/agent/v1/clients/:id
Delete a client and cascade-delete all associated data (rank tracker projects, results, runs, copywriter projects).
Scope required: clients:write
Response
Section titled “Response”{ "id": "uuid", "deleted": true}Client Knowledge sources
Section titled “Client Knowledge sources”Knowledge source writes require clients:write and an Idempotency-Key. Pasted content is bounded at 250,000 characters; Rankability preserves it as one logical source and handles retrieval chunks internally.
POST /api/agent/v1/clients/:id/sources accepts:
{ "name": "September entity research", "content": "# Research\n...", "role": "strategy_notes", "usage": "reference_only", "upsert_by_name": true}When upsert_by_name is true, the endpoint updates one case-insensitive, whitespace-normalized exact-name match or creates a source when none exists. It returns 409 ambiguous_source_name instead of guessing when duplicate names already exist. Omitting role preserves the role on an existing source; sending null clears it. usage accepts generation or reference_only; the latter remains readable through Knowledge tools but is excluded from automatic Copywriter prompt selection even when selected or priority. Existing sources default to generation, and omitting usage during an upsert preserves the current value.
Responses include operation (created, updated, or unchanged) plus compact source state with usage, embedding_status, and chunk_count. A create or content-changing update also returns a durable contradiction_check receipt. The initial status is scheduled; poll the returned result_path with GET /api/agent/v1/clients/:id/sources/:source_id/contradictions until it becomes complete, skipped, or failed. A completed check explicitly returns either findings or a measured zero. An unchanged upsert or metadata-only update returns not_scheduled with a reason. Indexing and contradiction checks remain asynchronous.
Knowledge Base
Section titled “Knowledge Base”These endpoints use Bearer token authentication with the kb:read scope.
Get all KB articles
Section titled “Get all KB articles”GET /api/agent/v1/kb/articlesAuthorization: Bearer rk_live_...Returns the canonical Help Center snapshot generated from the same Markdown source that publishes to help.rankability.com. The endpoint does not query legacy in-app KB records or scrape GitBook at request time. It supports two response formats via the Accept header.
Headers:
| Header | Value | Description |
|---|---|---|
Accept |
application/json (default) |
Structured JSON with articles array and FAQ markdown |
Accept |
text/markdown |
Single combined Markdown document for retrieval and agent context |
If-None-Match |
"<etag>" |
Conditional request — returns 304 if content unchanged |
If-Modified-Since |
HTTP date | Conditional request — returns 304 if not modified since |
Response headers:
| Header | Description |
|---|---|
ETag |
Content fingerprint for conditional requests |
Last-Modified |
Timestamp of the most recently updated article |
Response (200) — JSON format:
{ "articles": [ { "id": "uuid", "slug": "what-is-rankability", "title": "What is Rankability?", "summary": "Learn how Rankability organizes SEO and AI search work...", "category": "Getting Started", "canonical_url": "https://help.rankability.com/getting-started/what-is-rankability", "content_html": "<p>Rankability is a search visibility platform...</p>", "content_markdown": "Rankability is a search visibility platform...", "sort_order": 1, "created_at": "2026-08-03T12:00:00.000Z", "updated_at": "2026-08-03T12:00:00.000Z" } ], "faq_markdown": "# Frequently asked questions\n\n...", "meta": { "article_count": 89, "last_updated": "2026-08-03T12:00:00.000Z", "has_faq": true, "source": "canonical_help_center", "canonical_base_url": "https://help.rankability.com", "manifest_version": 1 }}| Field | Type | Description |
|---|---|---|
articles |
array | All canonical support articles in Help Center navigation order |
articles[].canonical_url |
string | Public GitBook URL for user-facing links and provenance |
articles[].content_html |
string | Full article content as HTML |
articles[].content_markdown |
string | Full article content as Markdown for retrieval and agent context |
faq_markdown |
string | Compatibility alias generated from the canonical FAQ article |
meta.article_count |
number | Total number of published articles |
meta.last_updated |
ISO 8601 | Most recent article update timestamp |
meta.has_faq |
boolean | Whether the FAQ content was included |
meta.source |
string | canonical_help_center for this manifest-backed contract |
meta.manifest_version |
number | Schema version for the generated snapshot |
Response (200) — Markdown format:
Request with Accept: text/markdown to receive a single combined Markdown document. Articles are grouped in Help Center navigation order, article headings link to their canonical URLs, and relative cross-links are rewritten as absolute Help Center URLs. The canonical FAQ appears once as an article; faq_markdown remains a JSON compatibility field.
GET /api/agent/v1/kb/articlesAuthorization: Bearer rk_live_...Accept: text/markdownReturns a text/markdown response body:
# Rankability Help Center
*Canonical source: https://help.rankability.com/**Last updated: 2026-08-03T12:00:00.000Z**Articles: 89*
---
## Getting Started
### [What is Rankability?](https://help.rankability.com/getting-started/what-is-rankability)
*Rankability is an AI-powered SEO platform...*
...canonical article content in Markdown...Conditional requests (304):
Use ETag or Last-Modified headers from a previous response to skip re-downloading unchanged content:
GET /api/agent/v1/kb/articlesAuthorization: Bearer rk_live_...If-None-Match: "a1b2c3d4e5f6..."Returns 304 Not Modified with no body if content has not changed.
Scopes required: kb:read
