Admin API reference

All /admin/* routes require an operator identity: Authorization: Bearer $MASTER_KEY, or — when DASH_ENABLED — an operator session cookie whose role carries the permission that route needs (the master key carries all of them). See Security → Roles. Success responses use { "data": ... }; paginated lists use { "data": [...], "pagination": { limit, offset, total, nextOffset } }.

Any POST /admin/* accepts an optional Idempotency-Key header — see Idempotent creates. This page is a map of what exists; for exact request/response bodies, see apps/gateway/openapi.yaml or the interactive spec (see API guide).

Typed clients

Every management response carries a schema in apps/gateway/openapi.yaml, so a fully typed client is generated rather than hand-written:

bunx openapi-typescript apps/gateway/openapi.yaml -o src/api/schema.d.ts

Pair it with a typed fetch wrapper (openapi-fetch or equivalent) and paths, query parameters, request bodies and response shapes are all checked at compile time.

The spec is generated from the same Zod schemas the API validates with, and two tests fail the build if it drifts: one when the committed YAML is stale, and one when a management response is documented without a schema. There is no second, private protocol for our own UI to use — the documented API is the API.

Deployments

Virtual keys

Router and fallbacks

Cache

Logs and usage

Audit trail

Both tables are read and interleaved, so offset + limit is capped at 5000 entries: older ones are reached with a date range or a narrower filter rather than a deeper page. Configuration entries are kept for ADMIN_AUDIT_RETENTION_DAYS (365 by default) and payload-read entries for as long as the operation metadata they point at.

Reads are not audited — they are the overwhelming majority of dashboard traffic and would bury the entries that matter. The deliberate exception is GET /admin/logs/:id/payload: it is a read, but it reveals real prompts and completions, so it lands here as a payload_access entry. The trail is append-only; there is no write or delete route for it.

Idempotent creates

Send Idempotency-Key: <opaque string> with a POST and the gateway remembers what that key produced. Retrying with the same key returns the original response — same status, same body, plus Idempotent-Replay: true — instead of creating a second resource. It is opt-in: a request without the header behaves exactly as it always has.

• Keys are scoped to the caller and expire after 24 hours.
• Reusing a key with a different body is 409 idempotency_key_reuse, because that is a client bug rather than a retry.
• A retry that arrives while the first request is still running is 409 idempotency_key_in_progress.
• Only successful responses are remembered. A rejected or failed call releases the key, so the corrected request can reuse it.

Operators and sessions

Present only when DASH_ENABLED. /auth/* is deliberately mounted outside /admin: every /admin route requires an already-resolved operator identity, so the route that creates one cannot live under it.

There is no per-session revoke: disabling the account, changing its role, or setting a new password revokes every session it has.

The root operator (DASH_ROOT_USER) never appears in GET /admin/users and cannot be edited through the API: it is an environment identity, not a row. See Security → Dashboard authentication.

Extensions

Full walkthrough, hook semantics, and failure behavior: Runtime extensions.

Next steps

• API overview — auth and error shape shared with /v1/*.
• Creating deployments, Virtual keys, Fallbacks, Extensions — the guides behind each section above.