# Referencia de la API

Cada ruta que llama una aplicación, un agente o un proveedor de identidad: cómo se autentica, el ámbito que necesita una clave, los campos que recibe y las respuestas que da.

## El archivo OpenAPI

La misma referencia como archivo OpenAPI 3.1, para generadores de código y pruebas de contrato. Se construye a partir del contrato que las pruebas de Azoth contrastan con las rutas en ambos sentidos: una ruta que falte en él, o una que nombre y no exista, las hace fallar.

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

> Los resúmenes de las rutas y los nombres de los campos están en inglés, aquí y en el archivo.

## Autenticación

- `Authorization` — `Bearer <key>`: una clave API del espacio de trabajo, de **Ajustes › Acceso** — `az_live_…`, o `az_test_…` en el plan gratuito. Una clave con ámbitos solo alcanza las rutas que cubren sus ámbitos.
- `X-Azoth-API-Key` — `<key>`: la misma clave en su propia cabecera. Cada ruta que acepta una clave acepta las dos.

Las lecturas propias del panel — `/api/v1/me` y las lecturas de GreenOps — requieren una sesión iniciada, nunca una clave. Las rutas SCIM requieren el token SCIM del espacio de trabajo ([aprovisionamiento SCIM](https://www.azothos.ai/es/docs/admin#scim)).

## Respuestas y errores

Una respuesta de error lleva `error`, una frase, un `code` estable y un `doc_url` que lleva a la entrada del código en [Códigos de error](https://www.azothos.ai/es/docs/errors); un `400` nombra además el `field` que falló. Un límite de frecuencia responde `429` con `retryAfterMs` en el cuerpo y `Retry-After` en las cabeceras. Una ruta cuyo módulo no ejecuta el despliegue lo indica. Una llamada a la pasarela que no es en streaming (`/api/v1/chat/completions`, `/api/v1/chat`) se puede reintentar sin riesgo con una cabecera `Idempotency-Key`: dentro de la hora, un reintento de una llamada ya respondida recibe esa primera respuesta — nunca una segunda llamada al modelo, un segundo sellado ni un segundo gasto — cuando la política de datos del espacio de trabajo permite a Azoth conservarla; si no, el reintento lo indica (`idempotency_replay_unavailable`), con la traza de la primera llamada.

## Rutas

Una página por parte de la API, con cada una de sus rutas completa: cómo se autentica, el ámbito que necesita una clave, sus parámetros y los campos de su cuerpo, sus respuestas y sus códigos. Abajo, cada parte con sus rutas, una línea cada una, enlazada a su entrada completa. El archivo contiene el tipo y los límites de cada campo, y el cuerpo de cada respuesta.

## Llamadas a la pasarela

Llamar a un modelo a través de la pasarela gobernada — y en torno a una llamada: si necesita un modelo, el modelo que puede usar una primera llamada, reanudar una llamada retenida, pedir una excepción, la comprobación de anclaje y los recibos de tu propia bóveda.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/gateway)

### `/api/v1/chat`

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

## Telemetría y optimización

Informar de las llamadas hechas fuera de la pasarela, elegir un modelo para una solicitud, buscar y guardar respuestas en caché, comprobar si un agente entra en bucle, comprimir contenido largo y consultar el mercado de proveedores.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/optimisation)

### `/api/ingest`

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

### `/api/arbiter`

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

### `/api/cache`

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

### `/api/v1/marketplace`

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

## Prueba

Leer las decisiones selladas, exportar el expediente de auditoría o el de una decisión, obtener las claves públicas que verifican los recibos, y leer las pruebas de Azoth Guard y los incidentes del espacio de trabajo.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/proof)

### `/api/v1/journal`

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

## Sistemas y políticas

Declarar tus sistemas (casos de uso) y leerlos, con las llamadas que salieron de aquello para lo que uno fue aprobado; leer los paquetes regulatorios y la política de datos que aplica el SDK.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/governance)

### `/api/v1/usecases`

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

## Pruebas y cambios de modelo

Gestionar las suites de regresión y ejecutarlas, o comparar modelos en una; leer las ejecuciones de conjuntos de referencia que esperan a tu sistema cuando cambia un modelo, y enviar sus resultados.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/testing)

### `/api/v1/regression`

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

## Agentes y MCP

Leer el gasto y el ahorro por agente, llamar a herramientas a través de la pasarela MCP gobernada y ejecutar las herramientas de lectura del asistente.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/agents)

### `/api/v1/agents`

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

### `/api/v1/mcp`

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

## Uso, gasto y huella

Leer las trazas de uso, el informe de gasto y ahorro, los presupuestos y su consumo, y la huella estimada de energía y de carbono.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/usage)

### `/api/v1/usage`

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

## Servicio y cuenta

Comprobar que el servicio responde, ver qué módulos están listos para producción, exportar los datos del espacio de trabajo y leer o borrar tu propia cuenta.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/account)

### `/api/health`

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

### `/api/v1/system`

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

## Aprovisionamiento SCIM

Crear, actualizar y retirar usuarios y grupos desde tu proveedor de identidad, con el token SCIM del espacio de trabajo.

[Todas las rutas de esta parte, completas](https://www.azothos.ai/es/docs/api/scim)

### `/api/scim/v2`

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