Motir

Repo: motir-core. One PR. The two documents the reference cannot replace, written into the docs shell 11.4.7 establishes. A reference tells a developer what each endpoint does; it never tells them how to make their first call, or what happens to their integration when Motir changes.

Audience: an external developer or self-hoster who has an account and has never called the API. Write for someone who will paste commands into a terminal, not for someone who already knows the conventions.

1. Getting started

A single linear read, each step ending in something the reader can see happen:

1. Mint a token — the shipped surface at app/(authed)/settings/account/api-tokens/, including which scopes to pick and why the token is shown once. Link to it; do not describe a surface you have not opened.
2. The first authenticated call — a complete curl with the Authorization: Bearer motir_pat_… header against a real read endpoint, and the response it returns.
3. Paginate — pass a limit, read the cursor out of the envelope, ask for the next page. Say that the cursor is opaque and must not be parsed, and note that one kind of collection reports a total count and the other deliberately does not (ADR Amendment 3 Q2) — that asymmetry surprises people.
4. Read an error — the { code, error } envelope, what the status means, and that the code is the stable part.
5. Read the rate-limit headers — the X-RateLimit-* set the wrapper puts on every response, what to do at a 429, and where Retry-After comes from.

Every command and every response in this guide must be true of the shipped API. A guide that documents an endpoint slightly wrong burns a developer's first ten minutes, which is the whole budget of goodwill a new API gets.

2. The v1 stability + deprecation policy

The public form of ADR §8 (docs/decisions/public-api-conventions.md:324-343) and whatever 11.4.1's Amendment 4 pinned for it: what v1 guarantees; the additive list (new endpoint, new optional parameter, new response field, new enum value on an open-ended field, a raised limit); the forbidden list (removing or renaming a field, changing a type or nullability, re-purposing an error code, changing an existing status, tightening a limit, making an optional parameter required); the client's obligation to tolerate unknown fields, which is the other half of the promise; how a deprecation is announced and how long the old behaviour keeps working; and how a v2 would arrive alongside v1 rather than replacing it.

The policy page and ADR §8 are one promise in two places. Cross-link them and say which is which — the ADR is the internal record, the page is the published commitment — so a future edit to one cannot leave the other saying something different.

Language: the surrounding chrome is localized like the rest of the surface; the long-form documentation prose follows what Amendment 4 pinned for documentation text. Read the amendment rather than deciding here.

Scope BOUNDARY

Ends at these two documents and their mounting. It builds no shell, no navigation and no reference rendering — those are 11.4.7's, and this content mounts into them. It does not restate the operation catalogue in prose: the reference is generated, and a hand-written second description of an endpoint is exactly the drift this story exists to prevent. It changes no endpoint, schema or operation declaration, and it does not amend ADR §8 — if the policy page and §8 disagree, that is a finding for 11.4.1's amendment, not an edit here.

Acceptance criteria

• The getting-started page walks all five steps in order, each with a complete, copy-pasteable command and the response it produces.
• Every endpoint, parameter, status and header the guide names is asserted against the shipped API by a test — so the guide cannot document a route, a query parameter or a header that does not exist.
• The token-minting step links to the shipped settings surface and describes the scopes it actually offers.
• The pagination step states that the cursor is opaque, and explains which collections carry a total count and which do not.
• The stability page states the v1 guarantee, both lists in full, the unknown-field obligation, the deprecation window and announcement, and the v2 path.
• The stability page and ADR §8 cross-link each other, and a test asserts the page names every item in §8's additive and forbidden lists — so the two cannot silently diverge.
• Both pages render inside the docs shell and are reachable from its navigation.
• Any new UI string added for these pages has an en.json key and its zh.json twin.
• New files join the per-file coverage thresholds in vitest.config.ts where the project's convention requires it.

Context refs

• docs/decisions/public-api-conventions.md — §4 errors, §5 pagination, §6 rate limits, §8 stability, Amendment 3 Q2 (totalCount), Amendment 4 (the policy's published shape).
• app/(authed)/settings/account/api-tokens/page.tsx — the token-minting surface step 1 sends the reader to.
• lib/api/v1/rateLimit.ts — the X-RateLimit-* headers and Retry-After behaviour step 5 documents.
• lib/api/v1/errors.ts — the { code, error } envelope and the code vocabulary step 4 documents.
• lib/api/v1/pagination.ts — the cursor, the limits, and the two envelopes step 3 documents.
• design/api-docs/ — the drawn rhythm of these pages (11.4.2).
• Blocker: 11.4.7. Parent story: 11.4.