Management API
The session-authenticated API behind the dashboard, its conventions, and where each area is described.
Everything the dashboard does goes through the management API under /api/v1. It exists for the dashboard: it authenticates with browser sessions only, and API keys can't use it.
Not for scripts yet
There are no machine credentials for the management API, and its routes may change between releases before 1.0. Automating administration (an operator CLI, declarative configuration) is a possible future feature, not something available now.
Conventions
- Sessions: sign-in creates a twelve-hour session in an
HttpOnlycookie. Every request rechecks the person's live role and memberships. - Changes (anything but
GETandHEAD) must send anOriginheader that exactly matches the gateway's public URL and anX-CSRF-Tokenheader equal to theomg_csrfcookie. No CORS is enabled. - Errors:
{"error": {"code": "<HTTP status>", "message": "…", "reason": "…"}}, wherereasonis a stable machine code for selected cases, such askey_lifetime_exceeds_maximum,setting_locked_by_environmentorexceeds_parent_budget. - Lists:
{data: [...]},limit1 to 200 (default 100) andoffset. Financial lists addhas_more. - Money: integer micro-dollar amounts as strings, such as
"1250000"for $1.25. Unknown values arenull, never 0. - Dates: UTC. Reports take
start_dateandend_dateasYYYY-MM-DD, end excluded, 1 to 93 days. - Privacy: no response ever contains a credential, a secret reference, a plaintext key, a prompt or a response.
Areas
| Area | Routes (under /api/v1) | Described in |
|---|---|---|
| Sign-in | /auth/config, /auth/login, /auth/callback, /auth/logout | Identity setup |
| You | /me, /me/summary, /me/keys, /me/notifications | Quick tour |
| People | /platform/users, /platform/oidc/group-mappings | People and roles, SSO groups |
| Workspaces | /platform/workspaces, /workspaces/{ws}, …/members, …/invitations, …/service-accounts, /invitations/accept | Teams and Projects, Workspace settings |
| Keys | /workspaces/{ws}/keys, …/keys/{key}/rotate, …/stats, …/access, …/key-safety, /platform/key-safety | API keys, Key safety |
| Models | /platform/providers, /platform/models, /platform/deployments, /platform/model-setup, …/routing, …/prices, …/price-suggestion | Connections, Models and routes, Pricing |
| Catalogs | /platform/catalogs, /platform/catalog-defaults, /platform/workspaces/{ws}/catalogs, /workspaces/{ws}/models, …/catalog | Catalogs |
| Limits | /platform/installation/policy, /platform/workspace-types/{kind}/policy, /platform/workspaces/{ws}/policy, /workspaces/{ws}/policy, …/keys/{key}/policy | Limits and budgets |
| Activity | /workspaces/{ws}/requests, …/generations, …/sessions, …/logs/metrics, /platform/logs/… | Logs |
| Costs | …/cost-report, …/costs, …/usage-export, …/usage/overview, …/usage/explore, …/usage/storage, /platform/cost-centers | Usage and costs |
| Reconciliation | POST /workspaces/{ws}/costs/{execution}/reconcile | Pricing |
| Files and batches | /workspaces/{ws}/files, /workspaces/{ws}/batches, /platform/batches | Files, Batches |
| Alerts | /platform/alerts/…, /workspaces/{ws}/alerts/… | Alerts |
| Settings | /platform/settings/general, …/privacy, …/email, …/storage, …/sign-in | Settings |
| Audit | /platform/audit, /workspaces/{ws}/audit | Audit log |
The complete route list, with bodies and responses, is in the repository's docs/management-api.md and docs/governance-api.md.
SCIM
SCIM 2.0 is a separate API at /scim/v2, authenticated with its own bearer token, for identity providers. See SCIM provisioning.