# API reference

Every route an application, an agent or an identity provider calls: how it authenticates, the scope a key needs, the fields it takes and the answers it gives.

## The OpenAPI file

The same reference as an OpenAPI 3.1 file, for code generators and contract tests. It is built from the contract that Azoth’s own tests hold to the routes in both directions: a route missing from it, or one it names that does not exist, fails them.

[openapi.yaml](https://www.azothos.ai/openapi.yaml)

> Route summaries and field names are written in English, here and in the file.

## Authentication

- `Authorization` — `Bearer <key>`: a workspace API key from **Settings › Access** — `az_live_…`, or `az_test_…` on the Free plan. A scoped key reaches only the routes its scopes cover.
- `X-Azoth-API-Key` — `<key>`: the same key in its own header. Every route that takes a key accepts both.

The dashboard’s own reads — `/api/v1/me` and the GreenOps reads — take a signed-in session, never a key. The SCIM routes take the workspace’s SCIM token ([SCIM provisioning](https://www.azothos.ai/docs/admin#scim)).

## Answers and errors

An error answer carries `error`, a sentence, a stable `code` and a `doc_url` that leads to the code’s entry in [Error codes](https://www.azothos.ai/docs/errors); a `400` also names the `field` that failed. A rate limit answers `429` with `retryAfterMs` in the body and `Retry-After` in the headers. A route whose module the deployment does not run says so. A gateway call that is not streamed (`/api/v1/chat/completions`, `/api/v1/chat`) can be retried safely with an `Idempotency-Key` header: within the hour, a retry of an answered call gets its first answer back — never a second model call, seal or spend — when the workspace’s data policy lets Azoth keep that answer; otherwise the retry is told so (`idempotency_replay_unavailable`), with the first call’s trace.

## Routes

One page per part of the API, with each of its routes in full: how it authenticates, the scope a key needs, its parameters and body fields, its answers and their codes. Below, each part with its routes, one line each, linked to the full entry. The file holds each field’s type and limits, and the body of each answer.

## Gateway calls

Call a model through the governed gateway — and around a call: whether it needs a model, the model a first call can use, resuming a held call, asking for an exception, grounding checks and your own vault’s receipts.

[Every route of this part, in full](https://www.azothos.ai/docs/api/gateway)

### `/api/v1/chat`

- [`POST /api/v1/chat/completions`](https://www.azothos.ai/docs/api/gateway#post-api-v1-chat-completions) — The governed gateway, OpenAI-compatible
- [`POST /api/v1/chat`](https://www.azothos.ai/docs/api/gateway#post-api-v1-chat) — The governed gateway with an explicit provider, fallbacks and streaming

### `/api/v1/infer`

- [`POST /api/v1/infer/resume`](https://www.azothos.ai/docs/api/gateway#post-api-v1-infer-resume) — Run a held call once a reviewer approved it
- [`POST /api/v1/infer/preflight`](https://www.azothos.ai/docs/api/gateway#post-api-v1-infer-preflight) — Score whether a request needs a model call at all

### `/api/v1/models`

- [`GET /api/v1/models/defaults`](https://www.azothos.ai/docs/api/gateway#get-api-v1-models-defaults) — Which model a first call can use, per provider

### `/api/v1/exceptions`

- [`POST /api/v1/exceptions`](https://www.azothos.ai/docs/api/gateway#post-api-v1-exceptions) — Ask the rule's owner for a time-limited exception to a refusal
- [`GET /api/v1/exceptions/{id}`](https://www.azothos.ai/docs/api/gateway#get-api-v1-exceptions-id) — Where an exception this key asked for stands

### `/api/v1/grounding`

- [`POST /api/v1/grounding/release`](https://www.azothos.ai/docs/api/gateway#post-api-v1-grounding-release) — Fetch a high-stakes answer the grounding check held, once approved
- [`POST /api/v1/grounding/receipts`](https://www.azothos.ai/docs/api/gateway#post-api-v1-grounding-receipts) — Seal the receipt of a grounding check run on your side

### `/api/v1/vault`

- [`POST /api/v1/vault/receipts`](https://www.azothos.ai/docs/api/gateway#post-api-v1-vault-receipts) — Seal the receipt of a call kept in your own vault

## Telemetry and optimisation

Report the calls made outside the gateway, pick a model for a request, look up and store cached answers, check an agent for a loop, compress long content and query the provider marketplace.

[Every route of this part, in full](https://www.azothos.ai/docs/api/optimisation)

### `/api/ingest`

- [`POST /api/ingest`](https://www.azothos.ai/docs/api/optimisation#post-api-ingest) — Ingest AI usage events

### `/api/arbiter`

- [`POST /api/arbiter/route`](https://www.azothos.ai/docs/api/optimisation#post-api-arbiter-route) — Select optimal model for a request

### `/api/cache`

- [`POST /api/cache/lookup`](https://www.azothos.ai/docs/api/optimisation#post-api-cache-lookup) — Look up a cached answer for a prompt
- [`POST /api/cache/store`](https://www.azothos.ai/docs/api/optimisation#post-api-cache-store) — Store a prompt and its answer in the cache

### `/api/loops`

- [`POST /api/loops/check`](https://www.azothos.ai/docs/api/optimisation#post-api-loops-check) — Check an agent for a loop, reset its counters, or read its state

### `/api/v1/compress`

- [`POST /api/v1/compress`](https://www.azothos.ai/docs/api/optimisation#post-api-v1-compress) — Compress long reasoning content (levels L1 to L3)

### `/api/v1/reconstruct`

- [`POST /api/v1/reconstruct`](https://www.azothos.ai/docs/api/optimisation#post-api-v1-reconstruct) — Reconstruct compressed content from its id

### `/api/v1/marketplace`

- [`GET /api/v1/marketplace`](https://www.azothos.ai/docs/api/optimisation#get-api-v1-marketplace) — The best-fit model of the provider marketplace for your constraints

## Proof

Read the sealed decisions, export the audit dossier or one decision’s dossier, fetch the public keys that verify receipts, and read Azoth Guard’s evidence and the workspace’s incidents.

[Every route of this part, in full](https://www.azothos.ai/docs/api/proof)

### `/api/v1/journal`

- [`GET /api/v1/journal`](https://www.azothos.ai/docs/api/proof#get-api-v1-journal) — The sealed decisions of the workspace
- [`GET /api/v1/journal/export`](https://www.azothos.ai/docs/api/proof#get-api-v1-journal-export) — The evidence pack, or the signed audit dossier as a ZIP

### `/api/v1/decisions`

- [`POST /api/v1/decisions/export`](https://www.azothos.ai/docs/api/proof#post-api-v1-decisions-export) — The decision dossier of one business decision, as a ZIP

### `/api/proof`

- [`GET /api/proof/keys/{workspaceId}`](https://www.azothos.ai/docs/api/proof#get-api-proof-keys-workspaceid) — A workspace's public receipt keys (JWKS)

### `/api/v1/guard`

- [`GET /api/v1/guard/evidence`](https://www.azothos.ai/docs/api/proof#get-api-v1-guard-evidence) — Azoth Guard's evidence pack, by obligation

### `/api/v1/incidents`

- [`GET /api/v1/incidents`](https://www.azothos.ai/docs/api/proof#get-api-v1-incidents) — The workspace's incidents
- [`POST /api/v1/incidents/{id}/match`](https://www.azothos.ai/docs/api/proof#post-api-v1-incidents-id-match) — Which of your business references an incident touched

## Systems and policies

Declare your systems (use cases) and read them, with the calls that ran outside what one was approved for; read the regulatory policy packs and the data policy the SDK applies.

[Every route of this part, in full](https://www.azothos.ai/docs/api/governance)

### `/api/v1/usecases`

- [`GET /api/v1/usecases`](https://www.azothos.ai/docs/api/governance#get-api-v1-usecases) — The workspace's declared systems (use cases) and their flags
- [`POST /api/v1/usecases`](https://www.azothos.ai/docs/api/governance#post-api-v1-usecases) — Declare a system (use case)
- [`GET /api/v1/usecases/{id}`](https://www.azothos.ai/docs/api/governance#get-api-v1-usecases-id) — One declared system (use case)
- [`PATCH /api/v1/usecases/{id}`](https://www.azothos.ai/docs/api/governance#patch-api-v1-usecases-id) — Always refused — a person reviews a use case, from the dashboard
- [`GET /api/v1/usecases/{id}/divergences`](https://www.azothos.ai/docs/api/governance#get-api-v1-usecases-id-divergences) — The sealed calls that ran outside what a use case was approved for

### `/api/v1/policy`

- [`GET /api/v1/policy/packs`](https://www.azothos.ai/docs/api/governance#get-api-v1-policy-packs) — The regulatory policy packs, or one pack in full

### `/api/v1/governance`

- [`GET /api/v1/governance/config`](https://www.azothos.ai/docs/api/governance#get-api-v1-governance-config) — The workspace's data policy, as the SDK applies it in your process

## Tests and model changes

Manage regression suites and run them, or compare models on one; read the reference-set runs waiting for your system when a model changes, and post their results.

[Every route of this part, in full](https://www.azothos.ai/docs/api/testing)

### `/api/v1/regression`

- [`GET /api/v1/regression/suites`](https://www.azothos.ai/docs/api/testing#get-api-v1-regression-suites) — The workspace's regression suites
- [`POST /api/v1/regression/suites`](https://www.azothos.ai/docs/api/testing#post-api-v1-regression-suites) — Create a regression suite
- [`PATCH /api/v1/regression/suites`](https://www.azothos.ai/docs/api/testing#patch-api-v1-regression-suites) — Change a suite's name, description, provider or model
- [`DELETE /api/v1/regression/suites`](https://www.azothos.ai/docs/api/testing#delete-api-v1-regression-suites) — Delete a suite and its runs
- [`GET /api/v1/regression/runs`](https://www.azothos.ai/docs/api/testing#get-api-v1-regression-runs) — The latest regression runs, newest first
- [`POST /api/v1/regression/runs`](https://www.azothos.ai/docs/api/testing#post-api-v1-regression-runs) — Run a suite, or compare 2 to 5 models on it
- [`GET /api/v1/regression/runs/{id}`](https://www.azothos.ai/docs/api/testing#get-api-v1-regression-runs-id) — One run, with each case's result

### `/api/v1/reference-sets`

- [`GET /api/v1/reference-sets/pending`](https://www.azothos.ai/docs/api/testing#get-api-v1-reference-sets-pending) — The reference-set runs waiting for your system (model change control)
- [`POST /api/v1/reference-sets/receipts`](https://www.azothos.ai/docs/api/testing#post-api-v1-reference-sets-receipts) — Post the results of a reference-set run your system ran

## Agents and MCP

Read spend and savings per agent, call tools through the governed MCP gateway, and run the assistant’s read tools.

[Every route of this part, in full](https://www.azothos.ai/docs/api/agents)

### `/api/v1/agents`

- [`GET /api/v1/agents`](https://www.azothos.ai/docs/api/agents#get-api-v1-agents) — Spend and savings per agent

### `/api/v1/mcp`

- [`GET /api/v1/mcp`](https://www.azothos.ai/docs/api/agents#get-api-v1-mcp) — Not used — the MCP gateway opens no stream (405)
- [`POST /api/v1/mcp`](https://www.azothos.ai/docs/api/agents#post-api-v1-mcp) — The governed MCP gateway (Streamable HTTP, tools only)
- [`DELETE /api/v1/mcp`](https://www.azothos.ai/docs/api/agents#delete-api-v1-mcp) — Not used — the MCP gateway keeps no session (405)

### `/api/v1/insights`

- [`POST /api/v1/insights/{tool}`](https://www.azothos.ai/docs/api/agents#post-api-v1-insights-tool) — Run one of the assistant's read tools

## Usage, spend and footprint

Read the usage traces, the spend and savings report, the budgets and their use, and the estimated energy and carbon footprint.

[Every route of this part, in full](https://www.azothos.ai/docs/api/usage)

### `/api/v1/usage`

- [`GET /api/v1/usage`](https://www.azothos.ai/docs/api/usage#get-api-v1-usage) — The workspace's usage traces, newest first (paginated)

### `/api/v1/report`

- [`GET /api/v1/report`](https://www.azothos.ai/docs/api/usage#get-api-v1-report) — The spend and savings report of the workspace

### `/api/v1/budgets`

- [`GET /api/v1/budgets`](https://www.azothos.ai/docs/api/usage#get-api-v1-budgets) — The workspace's budgets and their use

### `/api/v1/greenops`

- [`GET /api/v1/greenops/footprint`](https://www.azothos.ai/docs/api/usage#get-api-v1-greenops-footprint) — The workspace's estimated energy and carbon footprint, over an API key
- [`GET /api/v1/greenops/energy`](https://www.azothos.ai/docs/api/usage#get-api-v1-greenops-energy) — Energy per day and per strategy, and the workspace's energy budget
- [`GET /api/v1/greenops/summary`](https://www.azothos.ai/docs/api/usage#get-api-v1-greenops-summary) — GreenOps key figures (the dashboard's read)
- [`GET /api/v1/greenops/carbon`](https://www.azothos.ai/docs/api/usage#get-api-v1-greenops-carbon) — Estimated carbon totals and their monthly trend (the dashboard's read)
- [`GET /api/v1/greenops/provider-efficiency`](https://www.azothos.ai/docs/api/usage#get-api-v1-greenops-provider-efficiency) — Energy per 1,000 tokens, per provider and model (the dashboard's read)
- [`GET /api/v1/greenops/replay-savings`](https://www.azothos.ai/docs/api/usage#get-api-v1-greenops-replay-savings) — Energy saved by reusing answers (the dashboard's read)
- [`GET /api/v1/greenops/abatement`](https://www.azothos.ai/docs/api/usage#get-api-v1-greenops-abatement) — Avoided CO₂ with its traceability (the dashboard's read)
- [`GET /api/v1/greenops`](https://www.azothos.ai/docs/api/usage#get-api-v1-greenops) — Deprecated — Deprecated: use /api/v1/greenops/summary

## Service and account

Check that the service is up, see which modules are production-grade, export the workspace’s data, and read or erase your own account.

[Every route of this part, in full](https://www.azothos.ai/docs/api/account)

### `/api/health`

- [`GET /api/health`](https://www.azothos.ai/docs/api/account#get-api-health) — Health check, for uptime monitors

### `/api/v1/system`

- [`GET /api/v1/system/modules`](https://www.azothos.ai/docs/api/account#get-api-v1-system-modules) — Which modules are production-grade, beta or experimental

### `/api/v1/export`

- [`GET /api/v1/export`](https://www.azothos.ai/docs/api/account#get-api-v1-export) — The workspace's data, for portability (GDPR art. 20)

### `/api/v1/me`

- [`GET /api/v1/me`](https://www.azothos.ai/docs/api/account#get-api-v1-me) — Your personal data (GDPR art. 15) — signed in, never an API key
- [`DELETE /api/v1/me`](https://www.azothos.ai/docs/api/account#delete-api-v1-me) — Erase your account (GDPR art. 17) — signed in, never an API key

## SCIM provisioning

Create, update and remove users and groups from your identity provider, with the workspace’s SCIM token.

[Every route of this part, in full](https://www.azothos.ai/docs/api/scim)

### `/api/scim/v2`

- [`GET /api/scim/v2/Users`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-users) — SCIM: list users (filter, paginate)
- [`POST /api/scim/v2/Users`](https://www.azothos.ai/docs/api/scim#post-api-scim-v2-users) — SCIM: create + provision a user
- [`GET /api/scim/v2/Users/{id}`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-users-id) — SCIM: get a user
- [`PUT /api/scim/v2/Users/{id}`](https://www.azothos.ai/docs/api/scim#put-api-scim-v2-users-id) — SCIM: replace a user
- [`PATCH /api/scim/v2/Users/{id}`](https://www.azothos.ai/docs/api/scim#patch-api-scim-v2-users-id) — SCIM: patch a user (e.g. deactivate via active=false)
- [`DELETE /api/scim/v2/Users/{id}`](https://www.azothos.ai/docs/api/scim#delete-api-scim-v2-users-id) — SCIM: delete (deprovision) a user
- [`GET /api/scim/v2/Groups`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-groups) — SCIM: list groups
- [`POST /api/scim/v2/Groups`](https://www.azothos.ai/docs/api/scim#post-api-scim-v2-groups) — SCIM: create a group
- [`GET /api/scim/v2/Groups/{id}`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-groups-id) — SCIM: get a group
- [`PATCH /api/scim/v2/Groups/{id}`](https://www.azothos.ai/docs/api/scim#patch-api-scim-v2-groups-id) — SCIM: patch a group (membership changes)
- [`DELETE /api/scim/v2/Groups/{id}`](https://www.azothos.ai/docs/api/scim#delete-api-scim-v2-groups-id) — SCIM: delete a group
- [`GET /api/scim/v2/ServiceProviderConfig`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-serviceproviderconfig) — SCIM: service provider configuration (RFC 7643 §5)
- [`GET /api/scim/v2/ResourceTypes`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-resourcetypes) — SCIM: supported resource types
- [`GET /api/scim/v2/ResourceTypes/{id}`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-resourcetypes-id) — SCIM: a single resource type
- [`GET /api/scim/v2/Schemas`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-schemas) — SCIM: supported schemas
- [`GET /api/scim/v2/Schemas/{id}`](https://www.azothos.ai/docs/api/scim#get-api-scim-v2-schemas-id) — SCIM: a single schema definition
