Start free →

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.

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).

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

/api/v1/infer

/api/v1/models

/api/v1/exceptions

/api/v1/grounding

/api/v1/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

/api/arbiter

/api/cache

/api/loops

/api/v1/compress

/api/v1/reconstruct

/api/v1/marketplace

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

/api/v1/decisions

/api/proof

/api/v1/guard

/api/v1/incidents

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

/api/v1/policy

/api/v1/governance

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

/api/v1/reference-sets

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

/api/v1/mcp

/api/v1/insights

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

/api/v1/report

/api/v1/budgets

/api/v1/greenops

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

/api/v1/system

/api/v1/export

/api/v1/me

  • GET /api/v1/me — Your personal data (GDPR art. 15) — signed in, never an API key
  • 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

/api/scim/v2