> For the complete documentation index, see [llms.txt](https://help.rankability.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.rankability.com/api/api-knowledge-base.md).

# Knowledge Base API endpoint

Retrieve the canonical Rankability Help Center through the Agent API in structured JSON or combined Markdown, with stable caching headers.

The endpoint is generated from the same Markdown files that publish to `help.rankability.com`. It does not scrape GitBook at request time and it no longer reads the legacy in-app knowledge-base records for article content. This keeps GitBook and programmatic retrieval aligned while avoiding a runtime dependency on GitBook availability.

Use the public [Rankability Help Center](/rankability-help-center.md) for the human-facing support experience. Use this endpoint when an authorized integration, agent, or internal system needs a versioned snapshot of that same documentation.

## Prerequisites

* An active Rankability organization and an Agent API key stored on a trusted server.
* The `kb:read` scope on that key.
* A client that can preserve the response `Content-Type`, `ETag`, and `Last-Modified` headers.

Create or rotate keys under **Settings → API keys**. Never expose a live key in browser code, screenshots, a public repository, or an AI prompt.

## Endpoint

```
GET /api/agent/v1/kb/articles
Authorization: Bearer rk_live_...
```

**Scope required:** `kb:read`

## JSON response

JSON is returned by default. Each published Help Center article appears once in the same navigation order used by GitBook.

```
curl https://app.rankability.com/api/agent/v1/kb/articles \
  -H "Authorization: Bearer rk_live_YOUR_KEY_HERE"
```

Example shape:

```json
{
  "articles": [
    {
      "id": "stable-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
  }
}
```

Existing fields remain available for compatibility. The additive `canonical_url` field is the durable destination for user-facing links, and `content_markdown` is the preferred article body for retrieval or agent context. Treat `id` as an opaque stable identifier rather than deriving a URL from it.

`faq_markdown` is a compatibility alias generated from the canonical [Frequently asked questions](/troubleshooting/frequently-asked-questions.md) article. That FAQ also appears in `articles`; do not publish both copies on the same page.

## Bounded search and retrieval

Add any search parameter to request a bounded result instead of the complete snapshot:

| Parameter  | Behavior                                                                         |
| ---------- | -------------------------------------------------------------------------------- |
| `query`    | Relevance-orders matches across article title, summary, category, slug, and body |
| `category` | Filters to one category                                                          |
| `slug`     | Filters to one exact article slug                                                |
| `view`     | `compact` returns metadata; `full` also returns article Markdown and HTML        |
| `limit`    | 1–20 results; default 10                                                         |
| `offset`   | Zero-based result offset                                                         |

```bash
curl "https://app.rankability.com/api/agent/v1/kb/articles?query=Tracker&view=compact&limit=5" \
  -H "Authorization: Bearer rk_live_YOUR_KEY_HERE"
```

Use compact search for discovery, then request the selected slug with `view=full`. This avoids injecting the entire Help Center into an assistant prompt. MCP clients can use `search_help_center` for the same bounded workflow.

## Combined Markdown response

Set `Accept: text/markdown` to receive one combined document containing every canonical article once, grouped in Help Center navigation order:

```
curl https://app.rankability.com/api/agent/v1/kb/articles \
  -H "Authorization: Bearer rk_live_YOUR_KEY_HERE" \
  -H "Accept: text/markdown"
```

Article headings link to their canonical GitBook URLs, and cross-article links are rewritten as absolute Help Center URLs. The response is useful as retrieved reference context, but it is not model training and does not replace preserving source URLs and retrieval timestamps.

## Conditional caching

Every successful response includes `ETag` and `Last-Modified`. Store those headers with the snapshot and send `If-None-Match` on the next poll:

```
curl https://app.rankability.com/api/agent/v1/kb/articles \
  -H "Authorization: Bearer rk_live_YOUR_KEY_HERE" \
  -H 'If-None-Match: "saved-etag"'
```

The server returns `304 Not Modified` with no body when the manifest has not changed. `If-Modified-Since` is also supported, although ETag validation is more precise.

## Source-of-truth behavior

* **Canonical content** — Article titles, summaries, categories, order, HTML, Markdown, URLs, and FAQ content come from `help.rankability.com` source files.
* **Build-time snapshot** — A generated manifest is bundled with the application, so requests do not query legacy KB tables or fetch GitBook live.
* **Published articles only** — The Help Center home page, table of contents, and changelog archive are excluded from the article array; support articles listed in the public navigation are included.
* **Stable change detection** — Unchanged articles retain their timestamps, while a source or navigation change updates the manifest fingerprint.

The application’s historical KB administration records remain a separate legacy system during migration. Changes made only in that system do not change this endpoint or GitBook.

## Expected responses and errors

* `200 OK` returns JSON by default or Markdown when requested.
* `304 Not Modified` returns no body when a conditional request matches.
* `401` means the bearer token is missing or invalid.
* `403` means the key does not have `kb:read` or cannot access the organization.
* `429` means the Agent API rate limit was exceeded; honor the returned rate-limit headers and retry later.

Log the status, request time, response headers, and returned canonical URLs, but never log the bearer token. Validate `meta.source`, `meta.manifest_version`, and `meta.article_count` before replacing a known-good snapshot.

## Recommended agent-grounding workflow

1. Retrieve the Markdown or JSON representation and store its ETag, retrieval time, and canonical URLs.
2. Index article chunks with the article title, category, canonical URL, and manifest version as metadata.
3. Use bounded compact search, then retrieve only the relevant full articles or indexed chunks for the current task instead of injecting all articles into every prompt.
4. Use the documentation to understand product behavior, prerequisites, constraints, and execution order—not merely to recommend that the user read an article.
5. Link evidence to the canonical Help Center URL when an explanation or limitation needs user verification.
6. Refresh on a schedule with `If-None-Match`, retaining the previous snapshot after a failed request or invalid response.

## Related articles

* [Getting started with the API](/api/api-getting-started.md) — End-to-end walkthrough from your first key to your first API call.
* [Authentication and API keys](/api/api-authentication.md) — Bearer token format, scopes, and key management.
* [API usage, rate limits, and errors](/api/api-credits-rate-limits-and-errors.md) — Pooled windows, rate-limit headers, and error codes.
* [Connecting Rankability to AI assistants with MCP](/api/mcp-getting-started.md) — Use scoped Rankability capabilities from compatible assistants.