Skip to content

Clients and Knowledge

Create and manage client workspaces, integration connect links and the Knowledge sources that ground content.

GET /api/agent/v1/clients

List all clients for your organization.

Scope required: clients:read

Parameter Type Description
limit integer Max results (default 50, max 100)
offset integer Pagination offset (default 0)
{
"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 }
}

POST /api/agent/v1/clients

Create a new client.

Scope required: clients:write

{
"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.

{
"id": "uuid",
"name": "Acme Corp",
"domain": "acme.com",
"icon": "A",
"color": "bg-blue-500",
"created_at": "2025-01-15T10:00:00.000Z"
}
HTTP Code Description
409 conflict A client with the same domain already exists
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

{
"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.

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

{
"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"
}

PATCH /api/agent/v1/clients/:id

Update a client. Only provided fields are updated.

Scope required: clients:write

{
"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.

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.

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

{
"id": "uuid",
"deleted": true
}

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.


These endpoints use Bearer token authentication with the kb:read scope.

GET /api/agent/v1/kb/articles
Authorization: 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/articles
Authorization: Bearer rk_live_...
Accept: text/markdown

Returns 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/articles
Authorization: Bearer rk_live_...
If-None-Match: "a1b2c3d4e5f6..."

Returns 304 Not Modified with no body if content has not changed.

Scopes required: kb:read