Base URL
/api prefix on this host: the endpoint is
https://api.scaling.cloud/health, not /api/health.
Authentication
Everything else requires signing in with OAuth.
TODO: replace before launch — the OAuth flow is not settled. Document the
authorization and token endpoints, the grant type, the scopes and the token
lifetime here, then add the row to the table above.
The organisation a request operates in comes from the verified credential, never
from the request. There is no parameter for it.
Errors
One shape, every endpoint:code is one of unauthenticated, forbidden, not_found,
invalid_request, conflict, internal, retry_later, mapping to 401, 403,
404, 400, 409, 500 and 503 respectively. Narrow on code; treat message as
display text.
retry_later is the only one worth retrying unchanged. It means the request was
well formed and nothing is wrong — something it depends on has not finished
arriving — so the same request sent again shortly is expected to succeed. Every
other code describes a state that repeating the request will not change. Treat a
code you do not recognise the way you treat internal.
requestId identifies the single failure in our logs. Include it in reports —
without it, an intermittent 500 is unfindable.
Endpoints shipped with the template
TODO: replace before launch — this list stops being maintainable the moment the
product has more than a handful of endpoints. Generate it instead.
Generating this reference
The API is built with@hono/zod-openapi and serves its own spec at
/api/openapi.json, so this reference should be generated rather than written
by hand. Mintlify reads an OpenAPI document through the api.openapi key in
docs.json and creates the endpoint pages from it.
That key is deliberately not set yet: it points at a spec file or URL, and
pointing it at something that does not resolve fails the Mintlify build. Wire it
up once this product’s spec is committed or publicly reachable, and check the
current Mintlify OpenAPI documentation
for the exact shape rather than copying an older example.