Skip to content
RankabilityRankability Help Center

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

Section titled “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

Section titled “Endpoint”
GET /api/agent/v1/kb/articles
Authorization: Bearer rk_live_...

Scope required: kb:read

JSON response

Section titled “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.

Bounded search and retrieval

Section titled “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
Terminal window
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

Section titled “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

Section titled “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

Section titled “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

Section titled “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.

Section titled “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.
Section titled “Related articles”