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.
1. Principles
Section titled “1. Principles”- 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_reasonnormalisation) 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.
2. Content scope
Section titled “2. Content scope”| 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.
3. Dependencies
Section titled “3. Dependencies”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 |
4. Home and approach
Section titled “4. Home and approach”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.txtindex and anllms-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.africahas 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.
- AI-readable: an
- The OpenAPI spec is hand-maintained in the code repo next to
apps/api, and a contract test checks thatapps/api’s real responses match it. That is the drift control. - Things to check when building the app:
- Path and i18n:
/docsroutes 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;.mdandllms.txtoutputs are served with the right content type.
- Path and i18n:
- Drift between
apps/apiand 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) |
5. Where this touches other docs and work
Section titled “5. Where this touches other docs and work”- 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.mdabout 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.
6. Decisions and open items
Section titled “6. Decisions and open items”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/apibuild. - 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-Afteronly. -
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:
- 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).
- 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).