Skip to content

Router.Africa — Developer API Docs Scope

Backlog item #10. What the customer-facing API documentation must cover, where it lives, and what it depends on. This is the scope of the docs, not the docs themselves. Everything here restates decisions from ../architecture/decisions-log.md; where they disagree, the decisions log wins.

Revised 2026-10-26. The docs are a custom docs app, not Starlight, built to match the features of OpenRouter’s docs, and the API reference renders from our own curated OpenAPI spec. See section 4 and the decisions log, Developer docs site. Build tasks: ../execution/track-d-developer-docs.md.

Audience: a developer who already uses the OpenAI or Anthropic SDK and wants to move over in minutes. The website promises “change one line” (website-copy.md), so the docs have to make that true and be honest about where we differ.

Surface documented: api.router.africa, the external API served by apps/api. Not the dashboard API, not the admin API.


  • One line to switch. The first page a developer sees shows the base URL and key change for the OpenAI SDK, the Anthropic SDK and plain curl. Working example before any explanation.
  • Document differences, not the whole OpenAI spec. Link to the upstream reference for request fields we pass through unchanged. Spend our own pages on what is ours: auth, credits, errors, extensions, models and rates.
  • Credits wording rule applies. Credits are never money in the docs: no “wallet”, “cash”, currency symbols or refund language on balances (build inventory → Wording rule). Currency appears only where the top-up payment is described.
  • Accurate over complete. A behaviour is documented only once it is built and verified. Items still marked “Verify” in openrouter-api-comparison.md (Responses format, finish_reason normalisation) are documented as supported only after they are confirmed.
  • Curated, never auto-exposed. Guides are written by hand. The API reference renders from our own curated OpenAPI spec, which lists only the endpoints and parameters we choose to support (revised 2026-10-26; replaces “no generated reference”). Documented means supported: an endpoint or parameter that isn’t in the spec and has no page is not part of the public contract, even if it works. Adding one to the spec is an explicit decision, not a side effect of building it.
Section Covers Source of truth
Quickstart Sign up, get a key, first request in curl, OpenAI SDK (Python, TypeScript) and Anthropic SDK. Streaming example dashboard-scope.md onboarding flow; the same curl as the dashboard Overview
Authentication Authorization: Bearer is the accepted form on every route (matches OpenAI’s, so SDKs need only a new base_url and key); POST /v1/messages also accepts x-api-key (decided 2026-11-07), so the Anthropic SDK needs only a new base URL and key; key format sk-ra-…, shown once, HTTPS only, never put keys in client-side code. OpenAI-Organization and OpenAI-Project are accepted and ignored. Error bodies follow ../architecture/api-errors.md (OpenRouter’s envelope; Anthropic’s format on /v1/messages). Header forms are our own decision now that apps/api authenticates the key itself (../architecture/auth-security.md) Decisions log → API key security model, Public API authentication; ../architecture/auth-security.md
Endpoints Chat completions (streaming and not), models list, Anthropic Messages, key info (GET /v1/key) and request lookup (GET /v1/generation). Responses is not public at launch unless verified (comparison #2, #9, #10; api-surface.md) Hand-written reference pages, checked against the built route
Models and rates How to list models, what “model” strings look like, that a model needs an enabled key and a published rate, deprecation policy. Deferred: rates and models docs, and any public rates page, come back later pricing-model.md → Model availability; decisions log → v1 model list
Credits and billing What a credit is, how a request is charged (Bifrost-reported tokens × the published rate, locked at hold time), holds and what a customer sees when a hold is placed and released, low-balance behaviour, top-up with fee shown before payment. No refunds or cash language Decisions log → Charge basis, Credit balance & non-refundability, Top-up fee; design-doc.md §5
Errors Full table: status, error code, meaning, whether to retry. Must include insufficient credits, key revoked/expired/over its spend cap, model not allowed or not enabled, 409 for an in-flight duplicate, 429 rate limited, upstream failure and timeout. Error body shape backend-scope.md §3 and §6; comparison 3.4
Rate limits That limits exist per key, the 429 behaviour and Retry-After if we send it, backoff guidance. Limits are set per org in Admin and not shown to customers, so the docs describe behaviour, not numbers Decisions log → Rate limiting; build inventory → Rate limits
Idempotency and retries Automatic short-window duplicate protection, the optional Idempotency-Key header as a Router.Africa extension (with an extra_headers example for the OpenAI SDK), safe retry rules Decisions log → Idempotency key design (names this docs item explicitly)
Streaming SSE format, final usage chunk, what is charged if the client disconnects mid-stream (settled on Bifrost-reported partial usage) Decisions log → Mid-stream client disconnect policy
Spend caps and key scoping Per-key model allowlist, spend cap in credits with reset period, expiry; what error a capped key returns Build inventory → Features
Data and privacy Prompts and responses are not saved by default; saving is a per-workspace opt-in, who can read them, that headers and keys are never stored. Must match the terms and privacy policy wording Decisions log → Audit trail & prompt/response retention; backlog #17
Compatibility notes What differs from OpenAI and Anthropic: unsupported parameters, no batch endpoint, no :free/:nitro-style variants, no model aliases, no session-sticky routing until built Comparison 3.1, 3.2 (Diverge rows); decisions log → Batch/async endpoint
Changelog and status Dated API changes, deprecation notices. Link to the status page (at launch, decided) New

Which endpoints appear is a curated list, kept as its own short table in the docs repo (endpoint, status: public / hidden, notes). The proposed launch list and reasoning are in api-surface.md.

Out of scope for the docs: dashboard usage help (a separate help surface, if any), admin app, internal architecture, Niobi payment mechanics beyond what a customer sees, provider names and per-provider behaviour.

The docs can’t be finished before these are settled. Drafting can start on the parts marked ready.

Needs Status Affects
Backend scope (#4) Done Errors, request flow, streaming, idempotency: ready to draft
OpenRouter comparison (#1) Done Compatibility notes: ready to draft
Pricing model (#11) Done Credits, models and rates: ready to draft
Error catalogue: exact status codes, error codes, body shape Done (P1.08, context #10 and #12): OpenRouter’s envelope, our subset. See ../architecture/api-errors.md Errors page. Treat as a contract
Which extra endpoints are public at launch Decided 2026-11-07: chat completions, Messages, models list, GET /v1/key, GET /v1/generation (new build task P3.12). Responses only if verified (P0.13). See api-surface.md Endpoints section, compatibility notes
Rate-limit response contract Done (../architecture/api-errors.md): Retry-After (seconds) on 429, and on 503 / 529 when known. x-ratelimit-* is not sent; limits are per org and not shown to customers Rate limits page: describe behaviour, not numbers
Schema (#6) Done (../architecture/db-schema.md) Field names in any endpoint that returns ledger or key data
Bifrost verifications in backlog #18 Open: P0.13 runs them against staging. Bifrost’s docs describe /anthropic (Messages) as an Anthropic SDK drop-in Auth header forms, models list, Messages and Responses samples. Streaming, thinking and cache_control on Messages are not documented by Bifrost; check them in P0.13 before documenting

Decided (2026-09-20):

  • Hand-written and curated, hosted at router.africa/docs. No new origin: the four-origin split in the decisions log is unchanged, and the docs are static with no auth and no CORS.
  • Source lives in the website repo (router.africa-website, Astro), not the monorepo. The docs are site content and deploy with the site.
  • Tooling (revised 2026-10-26): a custom docs app, not Starlight. Built in Astro inside the website repo (the site’s existing stack), with its own layouts styled from the Router.Africa design system, served at router.africa/docs. Starlight was dropped: the docs need their own look and features beyond what its theme provides.
  • Features to match OpenRouter’s docs (seen on their site 2026-10-26; the full audit is task D.01):
    • AI-readable: an llms.txt index and an llms-full.txt, a Markdown version of every page (/docs/<page>.md), and a “Copy page” / “Open in ChatGPT” / “Open in Claude” menu on each page.
    • Code: language tabs (curl, Python, TypeScript) with a remembered choice, SDK switch (OpenAI SDK, Anthropic SDK, plain HTTP), package-manager tabs, copy buttons, line numbers, expandable long blocks.
    • Reference: rendered from the curated OpenAPI spec: request and response schemas, an example for every error in the catalogue, streaming examples. The spec is downloadable (YAML and JSON).
    • Request Builder: pick an endpoint, model and options and get ready-to-run code in each language. It generates code only and never sends a request: api.router.africa has no CORS by design, and customers must never paste keys into a web page. The model list is a fixed list maintained in the docs, not fetched from staging (staging may carry test models).
    • Navigation: sidebar, per-page table of contents, ⌘K search (Pagefind), callouts, dark and light theme (following the device, with a toggle), changelog, status page link.
    • Ask AI (nice to have, not launch-blocking): an assistant that answers from the docs. It has running costs, so it needs a cost cap and rate limit.
  • The OpenAPI spec is hand-maintained in the code repo next to apps/api, and a contract test checks that apps/api’s real responses match it. That is the drift control.
  • Things to check when building the app:
    • Path and i18n: /docs routes follow the site’s en / fr / sw i18n (docs launch in English only; fr and sw are added after launch, with the URL pattern following the site’s existing convention).
    • Sitemap: docs pages included once, /internal/ still filtered.
    • Adapter: builds and serves with @astrojs/cloudflare; .md and llms.txt outputs are served with the right content type.
  • Drift between apps/api and the docs: the contract test above (revised 2026-10-26; previously “no process”).
Question Approach
Code samples curl, Python and TypeScript for every documented endpoint. Guide samples are written by hand; reference and Request Builder samples are generated from the spec and reviewed
Versioning The API is /v1. Breaking changes need a new version; the changelog records everything else
Languages The site is en / fr / sw. English at launch; French and Swahili after launch (decided 2026-11-07, section 6)
  • Dashboard: the Overview quickstart curl (screen 8) and the key reveal sample curl (screen 6) should be the same snippet as the docs quickstart. A “Docs” link in the dashboard shell and an API reference link on the Rates screen. Small additions to build-inventory.md.
  • Website: this is website-repo work: building the custom docs app, a nav link, and a link from the “change one line” section once the docs exist. Any claim in website-copy.md about compatibility must be matched by a page here.
  • Backend (apps/api): the error catalogue and rate-limit headers are build work, not just docs work: define them as a contract with the build. Add to the execution plan (#9).
  • CI/CD (#13): nothing new; the docs deploy with the website.
  • Content logging (#17): the Data and privacy page is a fourth place the default-on disclosure must appear, next to signup, terms and privacy.

Decided (2026-10-26): custom docs app; curated OpenAPI spec as the reference source; code-only Request Builder; AI-readable outputs (llms.txt, .md pages); Ask AI as a nice-to-have (decisions log, Developer docs site).

Decided (2026-09-20):

  • The error catalogue and rate-limit response headers are defined before the apps/api build.
  • A status page ships at launch (tooling and location to be chosen).
  • The public rates page and the models/rates docs are deferred; they need more supporting content and come back later.

Decided (2026-11-07):

  • Launch endpoints: chat completions, Messages, models list, GET /v1/key, GET /v1/generation (metadata only; build task P3.12). Responses is documented only once verified (P0.13). The plan is to build everything, then add endpoints, each by an explicit spec decision.

  • Custom docs app stays. Cloudflare’s Nimbus (an Astro docs tool) was considered and not adopted: it is pre-1.0, and its “Try it” button sends requests, which conflicts with the code-only Request Builder.

  • Error format: OpenRouter’s envelope, our subset (decided 2026-10-26, catalogue in P1.08).

  • Rate-limit headers: Retry-After only.

  • Languages: English at launch; French and Swahili later (after launch), matching the site’s three languages. English is the source; the API, the OpenAPI spec, error codes and messages, and all code stay in English in every language.

  • The dashboard’s quickstart curl, key-reveal curl and Docs link follow the plan already in build-inventory.md (screens 6 and 8, API docs links).

Open:

  1. Who reviews fr and sw. The process is accepted (agent drafts from final English, a native reader per language reviews, re-translate on English changes); the translation work and the reviewers are deferred until after launch (D.08).
  2. Status page tool and location. Left open by the operator on 2026-11-07, to be decided in P9.08 (a hosted service on a status. subdomain is the standing proposal).