# API 参考

应用、智能体或身份提供商调用的每个路由：其认证方式、密钥所需的作用域、接受的字段以及给出的应答。

## OpenAPI 文件

同一份参考的 OpenAPI 3.1 文件，供代码生成器和契约测试使用。它由 Azoth 自身测试在两个方向上与路由对照的契约生成：缺少某个路由，或列出不存在的路由，都会使这些测试失败。

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

> 路由摘要和字段名称均以英文撰写，本页与文件中都是如此。

## 认证

- `Authorization` — `Bearer <key>`：在**设置 › 访问权限**中创建的工作区 API 密钥——`az_live_…`，免费套餐为 `az_test_…`。带作用域的密钥只能访问其作用域覆盖的路由。
- `X-Azoth-API-Key` — `<key>`：放在独立请求头中的同一密钥。每个接受密钥的路由都同时接受这两种方式。

控制台自身的读取——`/api/v1/me` 和 GreenOps 读取——使用已登录的会话，绝不接受密钥。SCIM 路由使用工作区的 SCIM 令牌（[SCIM 用户配置](https://www.azothos.ai/zh/docs/admin#scim)）。

## 应答与错误

错误应答包含 `error`（一句说明）、一个稳定的 `code` 和一个 `doc_url`，后者指向该代码在[错误代码](https://www.azothos.ai/zh/docs/errors)中的条目；`400` 还会通过 `field` 指明出错的字段。速率限制以 `429` 应答，正文中有 `retryAfterMs`，请求头中有 `Retry-After`。若部署未运行某路由所需的模块，该路由会如实说明。非流式的网关调用（`/api/v1/chat/completions`、`/api/v1/chat`）可以带上 `Idempotency-Key` 请求头安全地重试：一小时内，对已得到应答的调用进行重试，会收到首次的应答——绝不会再次调用模型、再次封存或再次产生费用——前提是工作区的数据策略允许 Azoth 保留该应答；否则重试会得到相应说明（`idempotency_replay_unavailable`），并附上首次调用的追踪。

## 路由

API 的每个部分各占一页，其中完整列出每个路由：认证方式、密钥所需的作用域、参数和请求体字段、应答及其代码。下方列出每个部分及其路由，每个路由一行，链接到其完整条目。文件中给出每个字段的类型和限制，以及每个应答的正文。

## 网关调用

通过受治理的网关调用模型——以及围绕一次调用的操作：是否需要模型、首次调用可用的模型、恢复被暂挂的调用、申请例外、依据核查，以及您自有保险库的回执。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/gateway)

### `/api/v1/chat`

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

## 遥测与优化

上报在网关之外发起的调用、为请求选择模型、查找和存储缓存的回答、检查智能体是否陷入循环、压缩长内容，以及查询提供商市场。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/optimisation)

### `/api/ingest`

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

### `/api/arbiter`

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

### `/api/cache`

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

### `/api/v1/marketplace`

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

## 证明

读取已封存的决策，导出审计档案或单项决策的档案，获取用于验证回执的公钥，并读取 Azoth Guard 的证据和工作区的事件。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/proof)

### `/api/v1/journal`

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

## 系统与策略

声明并读取您的系统（用例），以及超出其获批范围运行的调用；读取监管策略包和 SDK 所应用的数据策略。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/governance)

### `/api/v1/usecases`

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

## 测试与模型变更

管理并运行回归测试套件，或在套件上比较多个模型；在模型变更时读取等待您的系统运行的参考集任务，并提交其结果。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/testing)

### `/api/v1/regression`

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

## 智能体与 MCP

读取每个智能体的支出与节省，通过受治理的 MCP 网关调用工具，并运行助手的只读工具。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/agents)

### `/api/v1/agents`

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

### `/api/v1/mcp`

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

## 用量、支出与足迹

读取用量追踪记录、支出与节省报告、预算及其使用情况，以及估算的能耗与碳足迹。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/usage)

### `/api/v1/usage`

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

## 服务与账户

检查服务是否在线，查看哪些模块已可用于生产，导出工作区的数据，以及读取或删除您自己的账户。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/account)

### `/api/health`

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

### `/api/v1/system`

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

## SCIM 用户配置

使用工作区的 SCIM 令牌，从您的身份提供商创建、更新和移除用户与用户组。

[此部分的全部路由（完整内容）](https://www.azothos.ai/zh/docs/api/scim)

### `/api/scim/v2`

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