kumiko api-docs

kumiko api-docs [--out <dir>] [--locales en,de] [--check]

Reads kumiko.config.ts in the current directory, builds the registry of the app and writes the documentation for its HTTP API. Only handlers that a personal access token scope reaches appear, so the app must mount personal-access-tokens. Handlers with access.roles: ["system"] stay out even when a scope pattern matches them.

Output

File	Content
openapi.json	OpenAPI 3.1 with the handlers the scopes reach, plus a webhooks section when a scope lists public events
<locale>/overview.md	Endpoints, envelopes, error codes with HTTP status, lists, batches, safe retries
<locale>/tokens.md	How to create a token, scope table, expiry, rate limit, revoke
<locale>/reference/<scope>.md	One page per scope: each handler with its grant, fields, a curl example and a recorded response
<locale>/events.md	Webhook events, only when a scope lists events
index.json	Page order, source versions and stable anchor ids

The pages are plain Markdown with title and description frontmatter. The same input gives byte-identical output. Exclude the output directory from Biome, otherwise the formatter rewrites the files and --check reports them as changed.

Options

Option	Effect
--out <dir>	Output directory. Default: apiDocs.outDir, else api-docs. It must lie inside the working directory
--locales en,de	Locales to generate, unique values out of en, de, es, fr, it. Default: apiDocs.locales, else en
--check	Write nothing; print every problem and every [missing], [changed] or [extra] file

A run without --check refuses an output directory that holds files but no index.json, because those files did not come from this command. Files the previous run listed in index.json and the current run no longer produces are removed.

Configuration

The apiDocs block of defineAppConfig takes:

Key	Meaning
baseUrl	Required. Used in the curl examples and in openapi.json
appName	Default: the name in the app’s package.json
locales, outDir	Defaults for the options above
planNote	One paragraph per locale, appended to the tokens page
webhookDelivery	One paragraph per locale for the delivery section of events.md; required once a scope lists events
uiOnlyWrites	Writes that screens trigger but no scope grants, each with a reason
texts	Paragraph overrides per locale and key; the page structure stays fixed
examplesDir	Recorded examples, default api-examples; webhook payloads in its webhooks/ subdirectory

Record request and response pairs in an integration test with recordApiExample and webhook payloads with recordWebhookExample, both from @cosmicdrift/kumiko-testing/api-examples, while KUMIKO_RECORD_API_EXAMPLES=1 is set.

What --check reports

• a handler in a scope without a description or without a description translation
• a write that a screen triggers, that lies in no scope and is not listed in uiOnlyWrites
• a uiOnlyWrites entry that matches nothing
• any difference between the generated files and the committed ones

The screen write check only looks at features with at least one handler in a scope, so a feature that no scope touches is not reported.

Exit code

Code	When
0	Files written, or --check found nothing
1	--check found a problem or a difference; a missing token feature; baseUrl missing; an invalid example file; kumiko.config.ts not found
2	Invalid options, unsupported locales, or an output directory outside the working directory

Without --check, other problems are printed as warnings and the files are still written.

See also

• API docs recipe, the whole loop with a committed golden
• App skeleton, the kumiko.config.ts reference