Knowledge Base API endpoint

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

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

{
  "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 article. That FAQ also appears in articles; do not publish both copies on the same page.

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. Retrieve only the relevant 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 — End-to-end walkthrough from your first key to your first API call.

• Authentication and API keys — Bearer token format, scopes, and key management.

• Credits, rate limits, and errors — Rate-limit headers and error codes.

• Connecting Rankability to AI assistants with MCP — Use scoped Rankability capabilities from compatible assistants.