The HTTP API

Report server API, version 0.9.0. Every route reportd serves, grouped by what it is for. The machine-readable description is api/openapi.yaml in the repository.

Design RFML reports (docs/spec/rfml.md) and render them. reportd stores, versions and permits; the RFML engine (renderd, api/engine-contract) does everything that needs the language: validation, edit operations, locks, layout and rendering.

People and API keys send Authorization: Bearer. A render names the commit that was used in the X-Template-Commit response header. JSON request bodies larger than limits.maxBodyBytes are refused with 413.

Errors are JSON with an error kind and a message. Engine errors keep the engine's status and body (api/engine-contract/README.md, "Errors"), including diagnostics.

A state-changing request that a browser sends from another site is refused with 403 cross-origin: its Sec-Fetch-Site says cross-site, or its Origin is neither this host nor in security.trustedOrigins. Clients that send neither header are not affected.

A user who must change their password (a seeded administrator, or a password an administrator set) gets 403 password-change-required from everything but GET /v1/me, GET /v1/info, GET /v1/roles, POST /v1/me/password and POST /v1/logout. Then a user who signed in with a password, must have MFA (auth.mfa) and has none gets 403 mfa-enrolment-required from everything but GET /v1/me, GET /v1/info, GET /v1/roles, POST /v1/logout and /v1/me/mfa.

Every request but the probes and the studio's and viewer's files counts against the rate limit of its class (docs/operations/rate-limits.md): signin (the sign-in routes, per client address), public (anything else without a valid token, per address), read (GET and HEAD), write, render and assistant (per user, or per API key). Past it, the answer is 429 TooManyRequests with Retry-After. Every response a class limits carries RateLimit-Policy and RateLimit.

Until reportd is set up (no user exists and admin.password is unset), every /v1 request but /v1/setup, the MCP endpoint and report links get 503 setup-required (docs/operations/setup.md). Once the administrator exists, the /v1/setup routes answer 404 for good.

Every reply carries X-Request-Id: the client's own when it sent a short, plain one ([A-Za-z0-9._-], at most 64), else a new one. reportd logs it with the request and passes it to the engine.

The routes

• Server and setup: Health and readiness, what the server is and runs, its events, first-run setup, settings, the licence and the branding.
• Signing in: Signing in with a password and a second factor, through OIDC or SAML, and signing out.
• Your account: The signed-in person: their password, second factors, sessions and linked identities.
• Users, roles and keys: Users, roles and their mappings, API keys and everyone's sessions.
• Audit and usage: The audit log and the usage records.
• The assistant: The designer's assistant: requests, conversations and proposals.
• Data sources: Data sources and connections, and the data and parameters a template reads.
• Templates: The catalog, folders, drafts and their edits, publishing, promoting, tests and approvals.
• Examples and template sources: Templates to copy from, and where they come from.
• Rendering: Rendering reports, jobs and their results, report links and the viewer's sessions.
• Fonts: Font sources, and the font families a library declares.
• Libraries: Libraries, their drafts and releases, and the components they export.
• The trash: What was deleted, restoring it and deleting it for good.
• Schemas: the objects the routes share.