SDK 与 CLI
API 参考
应用、智能体或身份提供商调用的每个路由:其认证方式、密钥所需的作用域、接受的字段以及给出的应答。
OpenAPI 文件
同一份参考的 OpenAPI 3.1 文件,供代码生成器和契约测试使用。它由 Azoth 自身测试在两个方向上与路由对照的契约生成:缺少某个路由,或列出不存在的路由,都会使这些测试失败。
路由摘要和字段名称均以英文撰写,本页与文件中都是如此。
认证
AuthorizationBearer <key>:在设置 › 访问权限中创建的工作区 API 密钥——az_live_…,免费套餐为 az_test_…。带作用域的密钥只能访问其作用域覆盖的路由。X-Azoth-API-Key<key>:放在独立请求头中的同一密钥。每个接受密钥的路由都同时接受这两种方式。控制台自身的读取——/api/v1/me 和 GreenOps 读取——使用已登录的会话,绝不接受密钥。SCIM 路由使用工作区的 SCIM 令牌(SCIM 用户配置)。
应答与错误
错误应答包含 error(一句说明)、一个稳定的 code 和一个 doc_url,后者指向该代码在错误代码中的条目;400 还会通过 field 指明出错的字段。速率限制以 429 应答,正文中有 retryAfterMs,请求头中有 Retry-After。若部署未运行某路由所需的模块,该路由会如实说明。非流式的网关调用(/api/v1/chat/completions、/api/v1/chat)可以带上 Idempotency-Key 请求头安全地重试:一小时内,对已得到应答的调用进行重试,会收到首次的应答——绝不会再次调用模型、再次封存或再次产生费用——前提是工作区的数据策略允许 Azoth 保留该应答;否则重试会得到相应说明(idempotency_replay_unavailable),并附上首次调用的追踪。
路由
API 的每个部分各占一页,其中完整列出每个路由:认证方式、密钥所需的作用域、参数和请求体字段、应答及其代码。下方列出每个部分及其路由,每个路由一行,链接到其完整条目。文件中给出每个字段的类型和限制,以及每个应答的正文。
网关调用
通过受治理的网关调用模型——以及围绕一次调用的操作:是否需要模型、首次调用可用的模型、恢复被暂挂的调用、申请例外、依据核查,以及您自有保险库的回执。
/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
遥测与优化
上报在网关之外发起的调用、为请求选择模型、查找和存储缓存的回答、检查智能体是否陷入循环、压缩长内容,以及查询提供商市场。
/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
证明
读取已封存的决策,导出审计档案或单项决策的档案,获取用于验证回执的公钥,并读取 Azoth Guard 的证据和工作区的事件。
/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
系统与策略
声明并读取您的系统(用例),以及超出其获批范围运行的调用;读取监管策略包和 SDK 所应用的数据策略。
/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
测试与模型变更
管理并运行回归测试套件,或在套件上比较多个模型;在模型变更时读取等待您的系统运行的参考集任务,并提交其结果。
/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
智能体与 MCP
读取每个智能体的支出与节省,通过受治理的 MCP 网关调用工具,并运行助手的只读工具。
/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
用量、支出与足迹
读取用量追踪记录、支出与节省报告、预算及其使用情况,以及估算的能耗与碳足迹。
/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: use /api/v1/greenops/summary
服务与账户
检查服务是否在线,查看哪些模块已可用于生产,导出工作区的数据,以及读取或删除您自己的账户。
/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 用户配置
使用工作区的 SCIM 令牌,从您的身份提供商创建、更新和移除用户与用户组。
/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