# Référence de l’API

Chaque route qu’appelle une application, un agent ou un fournisseur d’identité : comment elle s’authentifie, la portée qu’une clé doit avoir, les champs qu’elle prend et les réponses qu’elle donne.

## Le fichier OpenAPI

La même référence sous forme de fichier OpenAPI 3.1, pour les générateurs de code et les tests de contrat. Il est construit à partir du contrat que les tests d’Azoth confrontent aux routes dans les deux sens : une route qui y manque, ou une route qu’il nomme et qui n’existe pas, les fait échouer.

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

> Les résumés des routes et les noms des champs sont écrits en anglais, ici comme dans le fichier.

## Authentification

- `Authorization` — `Bearer <key>` : une clé API de l’espace de travail, créée dans **Réglages › Accès** — `az_live_…`, ou `az_test_…` sur l’offre gratuite. Une clé à portée limitée n’atteint que les routes que ses portées couvrent.
- `X-Azoth-API-Key` — `<key>` : la même clé dans son propre en-tête. Chaque route qui prend une clé accepte les deux.

Les lectures propres au tableau de bord — `/api/v1/me` et les lectures GreenOps — prennent une session connectée, jamais une clé. Les routes SCIM prennent le jeton SCIM de l’espace de travail ([provisionnement SCIM](https://www.azothos.ai/fr/docs/admin#scim)).

## Réponses et erreurs

Une réponse d’erreur porte `error`, une phrase, un `code` stable et un `doc_url` qui mène à l’entrée du code dans [Codes d’erreur](https://www.azothos.ai/fr/docs/errors) ; un `400` nomme aussi le `field` en cause. Une limite de débit répond `429` avec `retryAfterMs` dans le corps et `Retry-After` dans les en-têtes. Une route dont le déploiement ne fait pas tourner le module le dit. Un appel à la passerelle qui n’est pas en streaming (`/api/v1/chat/completions`, `/api/v1/chat`) se réessaie sans risque avec un en-tête `Idempotency-Key` : dans l’heure, un nouvel essai d’un appel qui a reçu sa réponse reçoit cette première réponse — jamais un second appel au modèle, un second scellé ni une seconde dépense — quand la politique de données de l’espace permet à Azoth de la conserver ; sinon le nouvel essai en est averti (`idempotency_replay_unavailable`), avec la trace du premier appel.

## Routes

Une page par partie de l’API, avec chacune de ses routes en entier : son authentification, la portée qu’une clé doit avoir, ses paramètres et les champs de son corps, ses réponses et leurs codes. Ci-dessous, chaque partie avec ses routes, une ligne chacune, liée à son entrée complète. Le fichier donne le type et les limites de chaque champ, et le corps de chaque réponse.

## Appels à la passerelle

Appeler un modèle par la passerelle gouvernée — et autour d’un appel : s’il lui faut un modèle, le modèle qu’un premier appel peut utiliser, la reprise d’un appel retenu, une demande d’exception, la vérification d’ancrage et les reçus de votre propre coffre.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/gateway)

### `/api/v1/chat`

- [`POST /api/v1/chat/completions`](https://www.azothos.ai/fr/docs/api/gateway#post-api-v1-chat-completions) — The governed gateway, OpenAI-compatible
- [`POST /api/v1/chat`](https://www.azothos.ai/fr/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/fr/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/fr/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/fr/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/fr/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/fr/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/fr/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/fr/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/fr/docs/api/gateway#post-api-v1-vault-receipts) — Seal the receipt of a call kept in your own vault

## Télémétrie et optimisation

Déclarer les appels faits hors de la passerelle, choisir un modèle pour une requête, chercher et stocker des réponses en cache, vérifier qu’un agent ne boucle pas, compresser un long contenu et interroger la place de marché des fournisseurs.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/optimisation)

### `/api/ingest`

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

### `/api/arbiter`

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

### `/api/cache`

- [`POST /api/cache/lookup`](https://www.azothos.ai/fr/docs/api/optimisation#post-api-cache-lookup) — Look up a cached answer for a prompt
- [`POST /api/cache/store`](https://www.azothos.ai/fr/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/fr/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/fr/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/fr/docs/api/optimisation#post-api-v1-reconstruct) — Reconstruct compressed content from its id

### `/api/v1/marketplace`

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

## Preuve

Lire les décisions scellées, exporter le dossier d’audit ou le dossier d’une décision, récupérer les clés publiques qui vérifient les reçus, et lire les preuves d’Azoth Guard et les incidents de l’espace de travail.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/proof)

### `/api/v1/journal`

- [`GET /api/v1/journal`](https://www.azothos.ai/fr/docs/api/proof#get-api-v1-journal) — The sealed decisions of the workspace
- [`GET /api/v1/journal/export`](https://www.azothos.ai/fr/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/fr/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/fr/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/fr/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/fr/docs/api/proof#get-api-v1-incidents) — The workspace's incidents
- [`POST /api/v1/incidents/{id}/match`](https://www.azothos.ai/fr/docs/api/proof#post-api-v1-incidents-id-match) — Which of your business references an incident touched

## Systèmes et politiques

Déclarer vos systèmes (cas d’usage) et les lire, avec les appels passés hors de ce pour quoi l’un d’eux a été approuvé ; lire les packs réglementaires et la politique de données que le SDK applique.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/governance)

### `/api/v1/usecases`

- [`GET /api/v1/usecases`](https://www.azothos.ai/fr/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/fr/docs/api/governance#post-api-v1-usecases) — Declare a system (use case)
- [`GET /api/v1/usecases/{id}`](https://www.azothos.ai/fr/docs/api/governance#get-api-v1-usecases-id) — One declared system (use case)
- [`PATCH /api/v1/usecases/{id}`](https://www.azothos.ai/fr/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/fr/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/fr/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/fr/docs/api/governance#get-api-v1-governance-config) — The workspace's data policy, as the SDK applies it in your process

## Tests et changements de modèle

Gérer les suites de non-régression et les exécuter, ou y comparer des modèles ; lire les exécutions de jeux de référence qui attendent votre système quand un modèle change, et en envoyer les résultats.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/testing)

### `/api/v1/regression`

- [`GET /api/v1/regression/suites`](https://www.azothos.ai/fr/docs/api/testing#get-api-v1-regression-suites) — The workspace's regression suites
- [`POST /api/v1/regression/suites`](https://www.azothos.ai/fr/docs/api/testing#post-api-v1-regression-suites) — Create a regression suite
- [`PATCH /api/v1/regression/suites`](https://www.azothos.ai/fr/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/fr/docs/api/testing#delete-api-v1-regression-suites) — Delete a suite and its runs
- [`GET /api/v1/regression/runs`](https://www.azothos.ai/fr/docs/api/testing#get-api-v1-regression-runs) — The latest regression runs, newest first
- [`POST /api/v1/regression/runs`](https://www.azothos.ai/fr/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/fr/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/fr/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/fr/docs/api/testing#post-api-v1-reference-sets-receipts) — Post the results of a reference-set run your system ran

## Agents et MCP

Lire les dépenses et les économies par agent, appeler des outils par la passerelle MCP gouvernée, et exécuter les outils de lecture de l’assistant.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/agents)

### `/api/v1/agents`

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

### `/api/v1/mcp`

- [`GET /api/v1/mcp`](https://www.azothos.ai/fr/docs/api/agents#get-api-v1-mcp) — Not used — the MCP gateway opens no stream (405)
- [`POST /api/v1/mcp`](https://www.azothos.ai/fr/docs/api/agents#post-api-v1-mcp) — The governed MCP gateway (Streamable HTTP, tools only)
- [`DELETE /api/v1/mcp`](https://www.azothos.ai/fr/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/fr/docs/api/agents#post-api-v1-insights-tool) — Run one of the assistant's read tools

## Usage, dépenses et empreinte

Lire les traces d’usage, le rapport des dépenses et des économies, les budgets et leur consommation, et l’empreinte estimée en énergie et en carbone.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/usage)

### `/api/v1/usage`

- [`GET /api/v1/usage`](https://www.azothos.ai/fr/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/fr/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/fr/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/fr/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/fr/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/fr/docs/api/usage#get-api-v1-greenops-summary) — GreenOps key figures (the dashboard's read)
- [`GET /api/v1/greenops/carbon`](https://www.azothos.ai/fr/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/fr/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/fr/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/fr/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/fr/docs/api/usage#get-api-v1-greenops) — Obsolète — Deprecated: use /api/v1/greenops/summary

## Service et compte

Vérifier que le service répond, voir quels modules sont prêts pour la production, exporter les données de l’espace de travail, et lire ou effacer votre propre compte.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/account)

### `/api/health`

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

### `/api/v1/system`

- [`GET /api/v1/system/modules`](https://www.azothos.ai/fr/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/fr/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/fr/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/fr/docs/api/account#delete-api-v1-me) — Erase your account (GDPR art. 17) — signed in, never an API key

## Provisionnement SCIM

Créer, modifier et retirer des utilisateurs et des groupes depuis votre fournisseur d’identité, avec le jeton SCIM de l’espace de travail.

[Toutes les routes de cette partie, en entier](https://www.azothos.ai/fr/docs/api/scim)

### `/api/scim/v2`

- [`GET /api/scim/v2/Users`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-users) — SCIM: list users (filter, paginate)
- [`POST /api/scim/v2/Users`](https://www.azothos.ai/fr/docs/api/scim#post-api-scim-v2-users) — SCIM: create + provision a user
- [`GET /api/scim/v2/Users/{id}`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-users-id) — SCIM: get a user
- [`PUT /api/scim/v2/Users/{id}`](https://www.azothos.ai/fr/docs/api/scim#put-api-scim-v2-users-id) — SCIM: replace a user
- [`PATCH /api/scim/v2/Users/{id}`](https://www.azothos.ai/fr/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/fr/docs/api/scim#delete-api-scim-v2-users-id) — SCIM: delete (deprovision) a user
- [`GET /api/scim/v2/Groups`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-groups) — SCIM: list groups
- [`POST /api/scim/v2/Groups`](https://www.azothos.ai/fr/docs/api/scim#post-api-scim-v2-groups) — SCIM: create a group
- [`GET /api/scim/v2/Groups/{id}`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-groups-id) — SCIM: get a group
- [`PATCH /api/scim/v2/Groups/{id}`](https://www.azothos.ai/fr/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/fr/docs/api/scim#delete-api-scim-v2-groups-id) — SCIM: delete a group
- [`GET /api/scim/v2/ServiceProviderConfig`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-serviceproviderconfig) — SCIM: service provider configuration (RFC 7643 §5)
- [`GET /api/scim/v2/ResourceTypes`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-resourcetypes) — SCIM: supported resource types
- [`GET /api/scim/v2/ResourceTypes/{id}`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-resourcetypes-id) — SCIM: a single resource type
- [`GET /api/scim/v2/Schemas`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-schemas) — SCIM: supported schemas
- [`GET /api/scim/v2/Schemas/{id}`](https://www.azothos.ai/fr/docs/api/scim#get-api-scim-v2-schemas-id) — SCIM: a single schema definition
