---
title: "Clients and Knowledge"
description: "Create and manage client workspaces, integration connect links and the Knowledge sources that ground content."
canonical_url: "https://developers.rankability.com/guides/clients"
section: "Guides"
last_updated: 2026-11-14
---

# Clients and Knowledge

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

## Clients — List

`GET /api/agent/v1/clients`

List all clients for your organization.

**Scope required**: `clients:read`

### Query parameters

| Parameter | Type | Description |
|---|---|---|
| `limit` | integer | Max results (default 50, max 100) |
| `offset` | integer | Pagination offset (default 0) |

### Response

```json
{
  "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

`POST /api/agent/v1/clients`

Create a new client.

**Scope required**: `clients:write`

### Request body

```json
{
  "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)

```json
{
  "id": "uuid",
  "name": "Acme Corp",
  "domain": "acme.com",
  "icon": "A",
  "color": "bg-blue-500",
  "created_at": "2025-01-15T10:00:00.000Z"
}
```

### Errors

| HTTP | Code | Description |
|---|---|---|
| 409 | `conflict` | A client with the same domain already exists |

## 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)

```json
{
  "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

`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](https://help.rankability.com/account-and-settings/client-settings-reference) instead of inferring a relationship.

**Scope required**: `clients:read`

### Response

```json
{
  "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

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

Update a client. Only provided fields are updated.

**Scope required**: `clients:write`

### Request body

```json
{
  "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

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

`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

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

## 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:

```json
{
  "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

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

#### Get all KB articles

```
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:**

```json
{
  "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:

```markdown
# 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`
