Admin API reference

Documentation / Reference / Admin API

Use this reference to automate dashboard operations. For an illustrated introduction, start with the dashboard tour; for model requests from your application, use the separate application API.

Endpoints below describe request shapes, authorization and refusal conditions. Field lists use ? for optional values. Errors use the envelope {"error": {"message", "type", "param", "code"}}.

Authentication, once#

POST /admin/auth/login sets an HttpOnly JSESSIONID and an XSRF-TOKEN cookie. The CSRF gate applies when a session cookie accompanies the request; a stale cookie can therefore make a Basic-auth mutation fail with 403 forbidden_error.

Coarse /admin/** access requires a control-plane role (ADMIN, TENANT_ADMIN or VIEWER). Each endpoint then enforces its own permissions. Operator-only endpoints refuse TENANT_ADMIN with 403; scoped cross-tenant reads use 404 to avoid confirming existence. See policy authorization for scopes and grants.

Two wire conventions worth reading before copying anything#

Pricing fields spell per-1k without an underscore before the digit: input_per1k, output_per1k, cache_read_per1k, cache_write_per1k - Jackson's SNAKE_CASE does not split before digits, while the database columns underneath are _per_1k. Copy the wire spelling, not the column. One surface disagrees: GET /v1/models exposes cost_per_1k (explicitly annotated), so the public listing and the admin registry spell the same unit two ways.

Replacement semantics#

PUT is usually a full replace. Registry provider and model PUTs refuse a partial body outright (run: {"enabled": false} alone answers 400: openai_compatible providers need a base_url). The org/app/user/key limits PUTs replace all five fields - an omitted field becomes null, and null means uncapped, so a partial limits PUT silently removes caps. The exceptions are stated per entry below: guardrail settings PUT is a patch, key policy PUT treats null as clear-to-global, and scope policy has no PUT at all (delete, then create).

Sessions#

Organizations, keys, and their limits#

Workspaces (apps), members, users#

Limit rules#

One rule shape everywhere - {applies_when, count_by, amount, budget, window, action, action_duration_seconds?, degrade_to?} - documented with its vocabularies in gateway-controls.md. Unknown words in any closed vocabulary are refused at the door naming the legal set. Responses add id and inherited.

Budget trust (the budget fence)#

Budget trust belongs to a tenant slot (tag) and generation. Counter-store restart, data loss or rollback can fence the slot; budgeted traffic then receives 503 budget_recovering until recovery establishes a trusted generation. These endpoints are operator-only (root ADMIN). Follow the recovery procedure, not a counter reset.

Trust and activation states#

Fence a known-invalid balance#

Request body: {expected_generation, evidence_ref, reason}.

1. Match the reviewed generation; a stale value returns 409.
2. Fence PostgreSQL state first, then that generation's Redis epoch, then this instance's cache. The Redis epoch closes admission across replicas.
3. Let already-admitted requests settle normally. Repeating the operation on an already fenced slot changes nothing.

The operation audits budget.fence. Invalid input returns 400; an unknown slot returns 404.

Attest reviewed balances#

Request body: {expected_generation, evidence_ref, balances: {counter_key: micros}}.

Each named counter begins at its attested balance. An unnamed counter whose period began before the attestation stays refused; a new period begins at zero. The audit action is budget.attest.

Evidence completeness: a known lower bound is not proof that all spend is known. With an open recovery boundary, backup_gap identifies spend after the backup that the gateway cannot observe. Establish the balance from the required independent evidence.

Read counter evidence#

GET /admin/budget/trust/{tag}/evidence is read-only and returns 404 for an unknown slot.

Held evidence includes archived records whose inclusion was lost in a restore.

Unresolved reservations#

unresolvedReservations lists rows marked reserve_unresolved:* in the slot's current or a later generation. It corresponds to pointsman_budget_reservation_unresolved and returns total, limit (100) and the oldest items.

Each item includes {requestId, counterKey, generation, state, reservedMicros, reason, createdAt, dispatches, dispatchOutcomes}.

• A crash-orphaned row is ADMITTED, with interrupted_dispatched or interrupted_no_dispatch_record. Boot recovery records 503 accounting_interrupted for it.
• Its reservation remains in outstanding, so the floor retains the hold.
• reservedMicros is the counter hold, not a maximum provider bill.
• Zero recorded dispatches is missing evidence, not proof that nothing was sent.

Preserve held settlement records#

GET /admin/budget/held returns event ID, slot, generation, cost in micros, SHA256, counters, includedFor, archivable and archived.

Archive with POST /admin/budget/held/{event_id}/archive, body {evidence_ref}. It moves the record intact to a/<event>.<sha256>.held.json, ending retries/replay without deleting the evidence.

• 409 until every named counter includes the record through attestation.
• 404 if the event is not held.
• ALREADY_ARCHIVED for a repeat.
• Audit action: budget.held.archive.

Scopes, grants, and policy (the tree)#

The registry: providers, models, credentials#

Model fields and activation#

Model rows use {provider_name, model_id, aliases?, input_per1k?, output_per1k?, cache_read_per1k?, cache_write_per1k?, context_window?, max_output?, capabilities?, fallback_model?, tags?, lifecycle?, accepted_response_models?, enabled, ...}.

Accepted response identities#

accepted_response_models declares additional exact native model IDs that a deployment accepts as its serving identity. Its own model_id is always accepted.

Model write refusals#

Reasoning effort#

capabilities.reasoning_effort accepts none, minimal, low, medium or high only on an openai_compatible row. The value is sent verbatim; Pointsman does not translate vendors' reasoning levels. Unsupported adapters or values are refused on write and stripped/countable on load (capability=reasoning_effort). The upstream model must support the value or can return its typed 400.

The setting participates in the quality registry digest and response-cache identity. It is fixed by the operator's model row, not an arbitrary caller body override.

Admission snapshots and cache activation#

1. Admission pins a registry snapshot. Routing, quality decisions and serialized attempts use that snapshot.
2. If a row changes before an attempt sends, the attempt is refused as configuration_changed: no send, retry, breaker fault or arm penalty. The fallback ladder may move within the decision's constraints.
3. Cache lookup, coalescing and publication use the generation identity computed at admission: a registry-wide digest of declared generation settings.
4. Changing any model's generation settings invalidates reusable work across routes, including fallback answers. Non-generation edits such as prices or aliases do not.
5. A response is published, or accepted by a coalesced waiter, only when the serving model belongs to the route (or nothing involved declares a setting). Otherwise the waiter executes its own call.

This provider-state snapshot binding applies to openai_compatible rows. Code-backed adapters retain their own provider resolution.

Cache namespace and rollback: generation identity uses gen/v3. Deploying that namespace starts routes cold; older entries are unreachable. An older binary can read its own earlier namespace after rollback. Invalidate the cache with DELETE /internal/cache if generation settings or accepted-response-ID policy changed in the meantime.

Paged registry browsing#

The dashboard uses these ADMIN-only additions. The existing unpaged endpoints above keep their array responses.

Page responses are { "items": [...], "total": 123, "page": 0, "size": 25, "modelCounts": {} }. total counts all matching rows. Provider pages include per-provider registered-model counts keyed by the returned provider names; model pages leave that map empty. Page must be 0..100000, size 1..100, search at most 200 characters; invalid bounds return 400. Out-of-range pages return an empty items array with the matching total.

Ordering is provider name/UUID for providers and provider name/model ID/UUID for models. Each response is read in one repeatable-read transaction. Offset positions can shift when the registry changes between requests; this API is live browsing, not a snapshot export. Use the configuration export endpoint for a complete configuration document. Model page responses preserve the existing successor-narrowing warnings. These routes are control-plane reads and do not dispatch provider calls.

Paged browsing is a control-plane capability; its availability does not expand the qualified runtime scope.

Operator-fixed thinking mode#

An openai_compatible model row may declare capabilities.thinking_mode as enabled or disabled. Pointsman sends the corresponding native thinking: {"type":"enabled"} or thinking: {"type":"disabled"} on both sync and stream requests. An absent setting preserves the provider default. Kimi K2.6 defaults to thinking enabled, so use disabled to select its non-thinking profile. This is an operator model-row control, not a caller-controlled chat field or a generic body-injection map.

The admin API refuses other values, a non-openai_compatible adapter, and a row that declares both thinking_mode and reasoning_effort. A hand-edited invalid row fails registry reload and leaves the prior good snapshot in service. A supported setting participates in the quality registry digest, the registry-wide cache and in-flight generation identity (including fallback routes), and the served-generation response header. A change does not alter requests already admitted under their pinned snapshot. See the Kimi setup example.

Guardrails and control#

Observe, ops, and the bandit#

Quality-guarded routing (experimental)#

Authorization is decided in each handler: operator endpoints need root ADMIN (gate admin.quality); organization endpoints need that organization's ADMIN (legacy TENANT_ADMIN) or root ADMIN (gate admin.org.quality). Every write is audited; writes return 503 quality_disabled while pointsman.quality.enabled is false. How-to.

Internal and actuator#

Correlated provider dispatch history#

GET /admin/observe/requests/{id}/dispatches?page=0&size=25 returns physical provider sends for an authorized ledger record. {id} is the numeric ledger ID, not a caller-supplied request header. Authorization and foreign/missing-ID behavior match the ledger detail endpoint. The query uses the stored internal request UUID and organization together.

The response carries request_id, correlation_available, items, page, and has_next. Page size is bounded to 1–100. Each item includes dispatch UUID, sequence/rung/attempt, provider/model, recorded outcome, optional HTTP status/error class/cost, usage provenance, dispatch/finish timestamps, and reported_model (V68: the identity the provider reported for that send, sanitized; null when it named none). model is the dispatched deployment - the identity the tariff belongs to. Credential IDs and secrets are not returned. Unknown usage is not zero. A legacy row without the internal UUID returns correlation_available: false; a currently empty list can also reflect journal-delivery lag and must not be treated as proof that no provider send occurred. Ledger list/detail entries additionally expose nullable request_id for this correlation.

Account update safety#

PATCH /admin/users/{userId} retains its existing root-owner authorization. Disabling the signed-in account or the final enabled global administrator returns 409. Competing global administrator deactivations serialize on ordered row locks before checking remaining access. Password replacements must contain at least 12 characters and at most 72 UTF-8 bytes; invalid replacements return 400. Password values are never written into the audit detail. These rules affect account updates, not the separate account-creation contract.

Paged keys, accounts and quality history#

These additive browse endpoints preserve the authorization of their corresponding legacy list APIs. Legacy endpoints and their response shapes remain available.

All accept page (zero-based, 0..100000), size (1..100, default 25), and search (up to 200 characters, trimmed). Invalid bounds return 400. % and _ are literal text. Search, totals and paging execute in the database. Key browsing also accepts unclassified=true and returns {items,total,page,size,unclassified_total}. The unclassified total covers the entire authorized organization regardless of the search or kind filter. It is not a count of just the visible page. Responses expose prefixes, never raw keys or key hashes.

Account and quality pages use {items,total_items,total_pages,page,size}. Account responses omit password hashes. Quality history queries select summary metadata without loading sealed policy documents, epoch specs or adjudication results. Full details remain available through the exact-ID endpoints. GET /admin/quality/policy/versions/{version} now resolves that version directly, including versions older than the latest 200.

Counts and rows share a repeatable-read transaction in each inventory read. Pages are live offset views, not multi-request snapshots or export/completeness proofs. Concurrent changes can shift later pages. The dashboard resets its page when the scope or filter changes, keeps mutations tied to explicit selected IDs, and refreshes totals after mutations. No access grants, key-kind semantics, promotion checks, rollback checks or quality verdicts are changed by browsing.

These routes are included in the matching gateway/dashboard candidate accepted on 28 October (e71e5da8); see launch status for combined source, package and endurance evidence. Use the matched release artifacts rather than assuming an older gateway implements these APIs. Bounded output is not evidence of constant-time substring search or a throughput benchmark.

See Dashboard configuration ownership for conditional registry edits, Jev partial deployment drafts, operational observations and intentional API/deployment-only scope.