AgentbaseDocs
文档目录

AI Gateway API

AI Gateway 管理面:逻辑网关(gateway)、模型部署与目标(model-deployments / targets)资源及其修订(revision)状态机、策略引擎(policy engine + bundle + dry-run)、网关子密钥、工具连接(tool connections)、标准模型目录(standard models)、调用(invocation)观测与指标。与 llm-gateway 并存:那里面向 LLM 推理数据面,本域面向生成式 AI 资源的治理面。

服务与资源边界

AI Gateway API 是 Agentbase 面向生产级多模型与多工具治理的控制面与可观测性接口(如展示项目中的生产网关 prod-enterprise-ai-gateway / gw_7194685489feb1e169548619):

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。scope 仅两类:aiGateway.read(查询、观测)与 aiGateway.write(全部写操作与子密钥读取/管理)。网关子密钥(POST /ai-gateway/keys)签发的凭据用于下游调用网关数据面:以 gatewayIds 圈定可调用网关,allowedModels / allowedTools / allowedAgents 圈定模型、工具与 Agent Target,principal 携带角色与扁平 claims 供策略引擎判定。

端点总览

AI Gateway 端点围绕五大核心子域组织:统一资源与修订状态机(/ai-gateway/resources/{kind}*)、网关策略与封存快照(/ai-gateway/gateways/{gatewayId}/*)、策略引擎与试运行(/ai-gateway/policy-engines*)、子密钥与标准模型目录(/ai-gateway/keys*、/ai-gateway/standard-models*)、工具连接与调用观测(/ai-gateway/tool-connections*、/ai-gateway/invocations*、/ai-gateway/metrics*)。

端点清单

方法 + 路径用途
GET /ai-gateway/resources/{kind} / POST .../{kind}资源列表/创建(kind: model-deployments, targets)
`GETPUTDELETE /ai-gateway/resources/{kind}/{id}`资源读/整体替换/删除
POST .../resources/{kind}/{id}/revisions创建修订
GET .../revisions/{revisionId}读取修订
POST .../revisions/{revisionId}/{action}修订状态迁移
POST .../resources/model-deployments/{id}/test测试模型部署
POST .../resources/targets/{id}/health-check目标健康检查
POST .../resources/targets/{id}/models/discover发现目标可用模型
`GETPUT .../resources/targets/{id}/mounts`目标挂载列表/整体替换
PUT /ai-gateway/gateways/{gatewayId}/policy更新网关策略
POST /ai-gateway/gateways/{gatewayId}/snapshots封存快照(seal)
GET .../gateways/{gatewayId}/snapshots/status快照状态
`GETPOST /ai-gateway/policy-engines、GET .../{policyEngineId}`策略引擎列表/创建/详情
`GETPOST .../policy-engines/{policyEngineId}/bundles、GET .../bundles/{policyBundleId}`策略包列表/发布/详情
POST .../policy-engines/{policyEngineId}/dry-run策略试运行
`GETPOST /ai-gateway/keys、GET .../keys/{keyId}、PUT .../keys/{keyId}/status`网关子密钥
`GETPOST /ai-gateway/standard-models`标准模型目录
POST /ai-gateway/standard-models/import批量导入发现模型
PUT /ai-gateway/standard-models/{standardModelId}更新标准模型
POST /ai-gateway/tool-connections / .../discover、`PUTDELETE .../tool-connections/{id}`工具连接
POST .../tool-connections/{id}/test测试工具连接(2.8.0)
GET .../resources/logical-models/{id}/mounts列出逻辑模型挂载(2.8.0)
PUT .../resources/logical-models/{id}/mounts整体替换逻辑模型挂载(2.8.0)
GET /ai-gateway/invocations / GET .../invocations/{invocationId}调用记录
GET /ai-gateway/metrics/model-deployments部署指标
GET /ai-gateway/observability/overview观测总览

端点详解

统一资源(model-deployments、targets、logical-models)采用「草稿配置 → 创建修订(Revision)→ 状态迁移(Activate / Rollback)→ 网关快照封存(Snapshot Seal)」的变更治理流,确保生产流量切换零抖动。

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。

统一资源与修订

GET /v1/ai-gateway/resources/{kind}

分页列出指定 kind 的统一资源:model-deployments(模型部署)或 targets(上游目标)。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:model-deployments / targets。

输出:返回 200 + 资源列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为资源列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/resources/{kind}

创建统一资源:在项目内新建一个模型部署或上游目标;资源上线走修订流而非直接生效。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:model-deployments / targets。

输出:返回 201 + 新建资源文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 资源定义文档(泛化 schema,字段以资源定义为准) ... }'

响应示例:201:响应为资源文档 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/resources/{kind}/{id}

按 ID 读取单个统一资源。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:model-deployments / targets。
idpathstring是—资源 ID。

输出:返回 200 + 资源文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments/<ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为资源文档 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

PUT /v1/ai-gateway/resources/{kind}/{id}

整体替换资源定义:以请求体完整覆盖现有资源。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:model-deployments / targets。
idpathstring是—资源 ID。

输出:返回 200 + 替换后的资源文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments/<ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 完整资源定义文档 ... }'

响应示例:200:响应为替换后的资源文档 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

DELETE /v1/ai-gateway/resources/{kind}/{id}

删除统一资源:从项目内移除该模型部署或上游目标。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:model-deployments / targets。
idpathstring是—资源 ID。

输出:204 No Content,无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments/<ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:204 No Content:无响应体(已删除)。

POST /v1/ai-gateway/resources/{kind}/{id}/revisions

为资源创建新修订:模型部署与目标经修订(revision)状态机上线,保证配置可回溯、可回滚。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:model-deployments / targets。
idpathstring是—资源 ID。

输出:返回 201 + 新修订文档(含修订内容与状态)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments/<ID>/revisions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 修订内容 ... }'

响应示例:201:响应为修订文档 JSON(含修订 ID、内容与状态)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/resources/{kind}/{id}/revisions/{revisionId}

读取单个修订的内容与当前状态。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类。
idpathstring是—资源 ID。
revisionIdpathstring是—修订 ID。

输出:返回 200 + 修订文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments/<ID>/revisions/<REVISION_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为修订文档 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/resources/{kind}/{id}/revisions/{revisionId}/{action}

对修订执行状态迁移(action 为迁移动作名):推进修订在状态机中的流转,上线走此通道。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类。
idpathstring是—资源 ID。
revisionIdpathstring是—修订 ID。
actionpathstring是—迁移动作名(按当前状态判定合法取值;非法迁移返回 409)。

输出:返回 200 + 迁移后的修订文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments/<ID>/revisions/<REVISION_ID>/publish" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:200:响应为迁移后的修订文档 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/resources/model-deployments/{id}/test

实测一次模型部署的推理:验证部署通路与响应质量后再上线。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—模型部署资源 ID。

输出:返回 200 + 实测结果(含推理输出与元信息)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments/<ID>/test" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:200:响应为实测结果 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/resources/targets/{id}/health-check

对上游目标执行探活:验证目标当前可达与健康状态。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—目标资源 ID。

输出:返回 200 + 探活结果(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>/health-check" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:200:响应为探活结果 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/resources/targets/{id}/models/discover

发现上游目标实际可用的模型清单:结果可沉淀进标准模型目录(见 standard-models/import)。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—目标资源 ID。

输出:返回 200 + 发现的模型清单(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>/models/discover" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:200:响应为模型清单 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/resources/targets/{id}/mounts

读取目标的挂载列表:挂载把目标接入一个或多个网关快照。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—目标资源 ID。

输出:返回 200 + 挂载列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>/mounts" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为挂载列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

PUT /v1/ai-gateway/resources/targets/{id}/mounts

整体替换目标挂载列表:以请求体为准重建挂载关系。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—目标资源 ID。

输出:返回 200 + 替换后的挂载列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>/mounts" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 完整挂载列表 ... }'

响应示例:200:响应为替换后的挂载列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/resources/logical-models/{id}/mounts(2.8.0)

读取逻辑模型的挂载列表:挂载把逻辑模型接入一个或多个网关快照(2.8.0 新增)。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—逻辑模型资源 ID。

输出:返回 200 + 挂载列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/resources/logical-models/<ID>/mounts" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为逻辑模型挂载列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

PUT /v1/ai-gateway/resources/logical-models/{id}/mounts(2.8.0)

整体替换逻辑模型的挂载列表:以请求体为准重建挂载关系(2.8.0 新增)。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—逻辑模型资源 ID。

输出:返回 200 + 替换后的挂载列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/ai-gateway/resources/logical-models/<ID>/mounts" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '[ ... 挂载配置数组(全量替换,字段以 spec 为准) ... ]'

响应示例:200:响应为替换后的逻辑模型挂载列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

网关策略与快照

PUT /v1/ai-gateway/gateways/{gatewayId}/policy

更新网关策略:把策略引擎判定规则挂到指定网关。

输入:

参数位置类型必填默认/枚举说明
gatewayIdpathstring是—逻辑网关 ID。

输出:返回 200 + 更新后的网关策略(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/ai-gateway/gateways/<GATEWAY_ID>/policy" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 网关策略 ... }'

响应示例:200:响应为更新后的策略 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/gateways/{gatewayId}/snapshots

封存(seal)当前网关配置为快照:异步过程,封存结果经 status 端点轮询。

输入:

参数位置类型必填默认/枚举说明
gatewayIdpathstring是—逻辑网关 ID。

输出:返回 201 + 快照受理结果(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/gateways/<GATEWAY_ID>/snapshots" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:201:响应为快照受理 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/gateways/{gatewayId}/snapshots/status

查询快照封存进度与结果:封存是异步过程,轮询本端点至完成。

输入:

参数位置类型必填默认/枚举说明
gatewayIdpathstring是—逻辑网关 ID。

输出:返回 200 + 封存状态(进度、完成态与结果摘要)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/gateways/<GATEWAY_ID>/snapshots/status" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为封存状态 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

策略引擎

GET /v1/ai-gateway/policy-engines

列出项目内策略引擎。

输入:无 path/query/body 参数。

输出:返回 200 + 策略引擎列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/policy-engines" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为策略引擎列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/policy-engines

创建策略引擎:承载策略包(bundle)的评估载体。

输入:无 path/query/body 参数(泛化资源端点,payload 由目标资源定义决定)。

输出:返回 201 + 新建策略引擎(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/policy-engines" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 策略引擎定义 ... }'

响应示例:201:响应为策略引擎 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/policy-engines/{policyEngineId}

读取单个策略引擎详情。

输入:

参数位置类型必填默认/枚举说明
policyEngineIdpathstring是—策略引擎 ID。

输出:返回 200 + 策略引擎详情(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/policy-engines/<POLICY_ENGINE_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为策略引擎 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/policy-engines/{policyEngineId}/bundles

列出策略引擎已发布的策略包(bundle)。

输入:

参数位置类型必填默认/枚举说明
policyEngineIdpathstring是—策略引擎 ID。

输出:返回 200 + 策略包列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/policy-engines/<POLICY_ENGINE_ID>/bundles" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为策略包列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/policy-engines/{policyEngineId}/bundles

发布新策略包:发布并挂到网关策略后才对数据面实际生效。

输入:

参数位置类型必填默认/枚举说明
policyEngineIdpathstring是—策略引擎 ID。

输出:返回 201 + 新策略包(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/policy-engines/<POLICY_ENGINE_ID>/bundles" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 策略包内容 ... }'

响应示例:201:响应为策略包 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/policy-engines/{policyEngineId}/bundles/{policyBundleId}

读取单个策略包内容。

输入:

参数位置类型必填默认/枚举说明
policyEngineIdpathstring是—策略引擎 ID。
policyBundleIdpathstring是—策略包 ID。

输出:返回 200 + 策略包内容(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/policy-engines/<POLICY_ENGINE_ID>/bundles/<POLICY_BUNDLE_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为策略包 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/policy-engines/{policyEngineId}/dry-run

以试运行模式评估策略对请求的判定:不执行请求、不产生副作用。

输入:

参数位置类型必填默认/枚举说明
policyEngineIdpathstring是—策略引擎 ID。

输出:返回 200 + 评估结果(各策略对请求的判定)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/policy-engines/<POLICY_ENGINE_ID>/dry-run" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 待评估请求与语境 ... }'

响应示例:200:响应为评估结果 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

子密钥

GET /v1/ai-gateway/keys

列出已签发的 AI Gateway 子密钥(abk_ 凭据的元数据视图)。

输入:无 path/query/body 参数。

输出:返回 200 + 子密钥列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/keys" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为子密钥列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/keys

签发 AI Gateway 子密钥:加密存储、可恢复;用于下游以 abk_ 凭据调用网关数据面,权限由 gatewayIds 与三类 allowlist 圈定。

输入:

参数位置类型必填默认/枚举说明
namebodystring是—密钥名。
gatewayIdsbodystring[]是—允许调用的逻辑网关 ID 数组。
regionbodystring否—快照区域:调用侧就近使用该区域已封存快照。
allowedModelsbodystring[]否—允许的逻辑模型名;["*"] 放行已授权网关上的全部模型。
allowedToolsbodystring[]否—允许的 Tool 资源 ID;["*"] 放行全部,空数组 = 全部拒绝(与省略字段不同)。
allowedAgentsbodystring[]否—允许的 A2A / HTTP Agent Target 资源 ID;["*"] 放行全部,空数组 = 全部拒绝。
defaultLogicalModelbodystring否—请求缺 model 时使用的兜底逻辑模型。
principalbodyobject否—签入凭据的角色与扁平 claims(roles + claims),供策略引擎判定。
limitsbodyobject[]否—2.7.0 新增(appbase PR 526):硬性限流/配额规则,spec 描述为 "Optional hard credential/model/Tool/Agent rate and quota rules"。元素结构 { scope, resourceId?, rate?, quota? }:scope ∈ credential / model / tool / agent(非 credential 需带 resourceId);rate = { requestsPerSecond, burst }(burst 缺省取 requestsPerSecond,不能脱离它单配);quota = { period, requests?, tokens? },period ∈ minute / hour / day / month,tokens 仅 credential / model scope 支持。同一 scope+resourceId 不允许重复 rate,同周期不允许重复 quota。

输出:返回 201 + 签发结果(含一次性凭据)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/keys" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "docs-gateway-key",
    "gatewayIds": ["gw_docs"],
    "allowedModels": ["*"],
    "allowedTools": [],
    "defaultLogicalModel": "gpt-4o-mini",
    "principal": { "roles": ["chat-client"], "tenant": "docs" }
  }'

响应示例:201:响应为签发结果 JSON(泛化 schema;含一次性明文凭据与密钥元数据,字段以实际响应为准)。

GET /v1/ai-gateway/keys/{keyId}

读取子密钥明文凭据(可恢复语义):用于找回曾签发的 abk_ 凭据。

输入:

参数位置类型必填默认/枚举说明
keyIdpathstring是—子密钥 ID。

输出:返回 200 + 凭据明文与元数据(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/keys/<KEY_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为凭据 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

PUT /v1/ai-gateway/keys/{keyId}/status

更新子密钥启停状态:停用后该凭据立即无法通过网关校验。

输入:

参数位置类型必填默认/枚举说明
keyIdpathstring是—子密钥 ID。

输出:返回 200 + 更新后的子密钥(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/ai-gateway/keys/<KEY_ID>/status" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 目标状态 ... }'

响应示例:200:响应为更新后的子密钥 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

标准模型目录与工具连接

GET /v1/ai-gateway/standard-models

查询共享标准模型目录:跨资源复用的模型元数据(展示名、状态、元信息),支持按 provider profile 与状态过滤。

输入:

参数位置类型必填默认/枚举说明
providerProfileIdquerystring否默认 ""按 provider profile 过滤。
statusquerystring否枚举 '', active, inactive;默认 ""按目录状态过滤:active / inactive(空串不过滤)。

输出:返回 200 + 标准模型列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/standard-models?providerProfileId=<PROVIDER_PROFILE_ID>&status=active" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为标准模型列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/standard-models

手工登记标准模型元数据:providerProfileId + modelId 定位一个目录条目。

输入:

参数位置类型必填默认/枚举说明
providerProfileIdbodystring是—Provider profile ID。
profileVersionbodystring否—Provider profile 版本(可选)。
modelIdbodystring是—Provider 模型 ID。
displayNamebodystring否—模型展示名。
metadatabodyobject否—标准模型元信息对象。
statusbodystring否枚举 active, inactive目录状态:active / inactive,默认 active。

输出:返回 201 + 新建的标准模型条目(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/standard-models" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "providerProfileId": "profile-dashscope",
    "modelId": "qwen-plus",
    "displayName": "Qwen Plus",
    "metadata": { "contextWindow": 131072 },
    "status": "active"
  }'

响应示例:201:响应为标准模型条目 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/standard-models/import

把目标发现(discover)得到的模型元数据批量合并进标准模型目录:同 ID 以导入为准合并。

输入:

参数位置类型必填默认/枚举说明
providerProfileIdbodystring是—Provider profile ID。
profileVersionbodystring否—Provider profile 版本(可选)。
fetchedAtbodystring否—上游抓取时间。
modelsbodyobject[]是—发现的模型数组(来自 POST .../targets/{id}/models/discover 的结果)。

输出:返回 200 + 合并结果(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/standard-models/import" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "providerProfileId": "profile-dashscope",
    "fetchedAt": "2026-09-14T03:30:00Z",
    "models": [ { "modelId": "qwen-plus" }, { "modelId": "qwen-max" } ]
  }'

响应示例:200:响应为合并结果 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

PUT /v1/ai-gateway/standard-models/{standardModelId}

更新标准模型条目:改展示名、元信息或目录状态。

输入:

参数位置类型必填默认/枚举说明
standardModelIdpathstring是—标准模型文档 ID。
displayNamebodystring否—模型展示名。
metadatabodyobject否—标准模型元信息对象。
statusbodystring否枚举 active, inactive目录状态:active / inactive。

输出:返回 200 + 更新后的条目(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/ai-gateway/standard-models/<STANDARD_MODEL_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "Qwen Plus (2026-09)", "status": "active" }'

响应示例:200:响应为更新后的条目 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/tool-connections

创建工具连接:把 MCP / Tool 资源接入网关语境。

输入:无 path/query/body 参数(泛化资源端点,payload 由目标资源定义决定)。

输出:返回 201 + 工具连接文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/tool-connections" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 工具连接定义 ... }'

响应示例:201:响应为工具连接 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

POST /v1/ai-gateway/tool-connections/discover

发现工具连接可用的工具清单(如 MCP server 暴露的 tools)。

输入:无 path/query/body 参数(泛化资源端点,payload 由目标资源定义决定)。

输出:返回 200 + 可用工具清单(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/tool-connections/discover" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 发现语境 ... }'

响应示例:200:响应为工具清单 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

PUT /v1/ai-gateway/tool-connections/{id}

更新工具连接配置。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—工具连接 ID。

输出:返回 200 + 更新后的工具连接(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X PUT "https://<your-endpoint>/v1/ai-gateway/tool-connections/<ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ ... 连接更新 ... }'

响应示例:200:响应为更新后的工具连接 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

DELETE /v1/ai-gateway/tool-connections/{id}

删除工具连接:网关侧随即不可再经此连接调用工具。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—工具连接 ID。

输出:204 No Content,无响应体。

调用示例:

curl -X DELETE "https://<your-endpoint>/v1/ai-gateway/tool-connections/<ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:204 No Content:无响应体(已删除)。

POST /v1/ai-gateway/tool-connections/{id}/test(2.8.0)

对工具连接执行连通性测试与诊断(2.8.0 新增):验证目标可达性、凭据与逐工具状态;Console 连接诊断面板同源。

输入:

参数位置类型必填默认/枚举说明
idpathstring是—工具连接 ID。

输出:返回 200 + 测试与诊断结果(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl -X POST "https://<your-endpoint>/v1/ai-gateway/tool-connections/<ID>/test" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:200:响应为连通性测试结果 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

观测

GET /v1/ai-gateway/invocations

分页查询网关调用记录:一次推理 / 工具调用的请求、响应、策略判定与用量留痕。

输入:无 path/query/body 参数。

输出:返回 200 + 调用记录列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/invocations" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为调用记录列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)(含请求 / 响应 / 策略判定 / 用量语义)。

GET /v1/ai-gateway/invocations/{invocationId}

读取单条调用记录详情。

输入:

参数位置类型必填默认/枚举说明
invocationIdpathstring是—调用记录 ID。

输出:返回 200 + 调用记录详情(请求 / 响应 / 策略判定 / 用量)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/invocations/<INVOCATION_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为调用记录 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/metrics/model-deployments

查询模型部署维度的指标:调用量、延迟、错误等聚合视图。

输入:无 path/query/body 参数。

输出:返回 200 + 部署指标(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/metrics/model-deployments" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为部署指标 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

GET /v1/ai-gateway/observability/overview

查询网关观测总览:全局调用与策略命中概况。

输入:无 path/query/body 参数。

输出:返回 200 + 观测总览(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

调用示例:

curl "https://<your-endpoint>/v1/ai-gateway/observability/overview" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

响应示例:响应为观测总览 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。

错误与边界

与 Server SDK 的对应

service.method端点
AIGateway.listResources / createResource / getResource / replaceResource / deleteResource/ai-gateway/resources/{kind}*
AIGateway.createRevision / getRevision / transitionRevision.../revisions*
AIGateway.testModelDeployment / checkTargetHealth / discoverTargetModels / listTargetMounts / replaceTargetMounts资源专有操作端点
AIGateway.updateGatewayPolicy / sealSnapshot / getSnapshotStatus/ai-gateway/gateways/{gatewayId}/*
AIGateway.listPolicyEngines / createPolicyEngine / getPolicyEngine / listPolicyBundles / publishPolicyBundle / getPolicyBundle / dryRunPolicy/ai-gateway/policy-engines*
AIGateway.listKeys / createKey / getKey / updateKeyStatus/ai-gateway/keys*
AIGateway.listStandardModels / createStandardModel / importStandardModels / updateStandardModel/ai-gateway/standard-models*
AIGateway.createToolConnection / discoverToolConnection / updateToolConnection / deleteToolConnection/ai-gateway/tool-connections*
AIGateway.testToolConnectionPOST /ai-gateway/tool-connections/{id}/test(2.8.0)
AIGateway.listLogicalModelMounts / replaceLogicalModelMounts`GETPUT /ai-gateway/resources/logical-models/{id}/mounts`(2.8.0)
AIGateway.listInvocations / getInvocation / getModelDeploymentMetrics / getObservabilityOverview观测端点

事实源