SDK & CLI
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.
Route summaries and field names are written in English, here and in the file.
Authentication
AuthorizationBearer <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).
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; 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
/api/v1/chat
POST /api/v1/chat/completions— The governed gateway, OpenAI-compatiblePOST /api/v1/chat— The governed gateway with an explicit provider, fallbacks and streaming
/api/v1/infer
POST /api/v1/infer/resume— Run a held call once a reviewer approved itPOST /api/v1/infer/preflight— Score whether a request needs a model call at all
/api/v1/models
GET /api/v1/models/defaults— Which model a first call can use, per provider
/api/v1/exceptions
POST /api/v1/exceptions— Ask the rule's owner for a time-limited exception to a refusalGET /api/v1/exceptions/{id}— Where an exception this key asked for stands
/api/v1/grounding
POST /api/v1/grounding/release— Fetch a high-stakes answer the grounding check held, once approvedPOST /api/v1/grounding/receipts— Seal the receipt of a grounding check run on your side
/api/v1/vault
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
/api/ingest
POST /api/ingest— Ingest AI usage events
/api/arbiter
POST /api/arbiter/route— Select optimal model for a request
/api/cache
POST /api/cache/lookup— Look up a cached answer for a promptPOST /api/cache/store— Store a prompt and its answer in the cache
/api/loops
POST /api/loops/check— Check an agent for a loop, reset its counters, or read its state
/api/v1/compress
POST /api/v1/compress— Compress long reasoning content (levels L1 to L3)
/api/v1/reconstruct
POST /api/v1/reconstruct— Reconstruct compressed content from its id
/api/v1/marketplace
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
/api/v1/journal
GET /api/v1/journal— The sealed decisions of the workspaceGET /api/v1/journal/export— The evidence pack, or the signed audit dossier as a ZIP
/api/v1/decisions
POST /api/v1/decisions/export— The decision dossier of one business decision, as a ZIP
/api/proof
GET /api/proof/keys/{workspaceId}— A workspace's public receipt keys (JWKS)
/api/v1/guard
GET /api/v1/guard/evidence— Azoth Guard's evidence pack, by obligation
/api/v1/incidents
GET /api/v1/incidents— The workspace's incidentsPOST /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
/api/v1/usecases
GET /api/v1/usecases— The workspace's declared systems (use cases) and their flagsPOST /api/v1/usecases— Declare a system (use case)GET /api/v1/usecases/{id}— One declared system (use case)PATCH /api/v1/usecases/{id}— Always refused — a person reviews a use case, from the dashboardGET /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— The regulatory policy packs, or one pack in full
/api/v1/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
/api/v1/regression
GET /api/v1/regression/suites— The workspace's regression suitesPOST /api/v1/regression/suites— Create a regression suitePATCH /api/v1/regression/suites— Change a suite's name, description, provider or modelDELETE /api/v1/regression/suites— Delete a suite and its runsGET /api/v1/regression/runs— The latest regression runs, newest firstPOST /api/v1/regression/runs— Run a suite, or compare 2 to 5 models on itGET /api/v1/regression/runs/{id}— One run, with each case's result
/api/v1/reference-sets
GET /api/v1/reference-sets/pending— The reference-set runs waiting for your system (model change control)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
/api/v1/agents
GET /api/v1/agents— Spend and savings per agent
/api/v1/mcp
GET /api/v1/mcp— Not used — the MCP gateway opens no stream (405)POST /api/v1/mcp— The governed MCP gateway (Streamable HTTP, tools only)DELETE /api/v1/mcp— Not used — the MCP gateway keeps no session (405)
/api/v1/insights
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
/api/v1/usage
GET /api/v1/usage— The workspace's usage traces, newest first (paginated)
/api/v1/report
GET /api/v1/report— The spend and savings report of the workspace
/api/v1/budgets
GET /api/v1/budgets— The workspace's budgets and their use
/api/v1/greenops
GET /api/v1/greenops/footprint— The workspace's estimated energy and carbon footprint, over an API keyGET /api/v1/greenops/energy— Energy per day and per strategy, and the workspace's energy budgetGET /api/v1/greenops/summary— GreenOps key figures (the dashboard's read)GET /api/v1/greenops/carbon— Estimated carbon totals and their monthly trend (the dashboard's read)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— Energy saved by reusing answers (the dashboard's read)GET /api/v1/greenops/abatement— Avoided CO₂ with its traceability (the dashboard's read)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
/api/health
GET /api/health— Health check, for uptime monitors
/api/v1/system
GET /api/v1/system/modules— Which modules are production-grade, beta or experimental
/api/v1/export
GET /api/v1/export— The workspace's data, for portability (GDPR art. 20)
/api/v1/me
GET /api/v1/me— Your personal data (GDPR art. 15) — signed in, never an API keyDELETE /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
/api/scim/v2
GET /api/scim/v2/Users— SCIM: list users (filter, paginate)POST /api/scim/v2/Users— SCIM: create + provision a userGET /api/scim/v2/Users/{id}— SCIM: get a userPUT /api/scim/v2/Users/{id}— SCIM: replace a userPATCH /api/scim/v2/Users/{id}— SCIM: patch a user (e.g. deactivate via active=false)DELETE /api/scim/v2/Users/{id}— SCIM: delete (deprovision) a userGET /api/scim/v2/Groups— SCIM: list groupsPOST /api/scim/v2/Groups— SCIM: create a groupGET /api/scim/v2/Groups/{id}— SCIM: get a groupPATCH /api/scim/v2/Groups/{id}— SCIM: patch a group (membership changes)DELETE /api/scim/v2/Groups/{id}— SCIM: delete a groupGET /api/scim/v2/ServiceProviderConfig— SCIM: service provider configuration (RFC 7643 §5)GET /api/scim/v2/ResourceTypes— SCIM: supported resource typesGET /api/scim/v2/ResourceTypes/{id}— SCIM: a single resource typeGET /api/scim/v2/Schemas— SCIM: supported schemasGET /api/scim/v2/Schemas/{id}— SCIM: a single schema definition