AI Gateway API
AI Gateway 管理面:逻辑网关(gateway)、模型部署与目标(model-deployments / targets)资源及其修订(revision)状态机、策略引擎(policy engine + bundle + dry-run)、网关子密钥、工具连接(tool connections)、标准模型目录(standard models)、调用(invocation)观测与指标。与 llm-gateway 并存:那里面向 LLM 推理数据面,本域面向生成式 AI 资源的治理面。
资源与基础路径
- Base URL:
https://<your-endpoint>/v1,路径前缀/ai-gateway。 - 资源模型:多数实体走统一资源端点
/ai-gateway/resources/{kind},kind当前取值:model-deployments(模型部署)、targets(上游目标,承载 mounts);带id+ 修订子路径。 - 专有端点:
gateways/{gatewayId}(策略/快照)、keys、policy-engines、tool-connections、standard-models、invocations、metrics、observability。
认证与权限
认证与请求头约定见 通用约定。scope 仅两类:aiGateway.read(查询、观测)与 aiGateway.write(全部写操作与子密钥读取/管理)。网关子密钥(POST /ai-gateway/keys)签发的凭据用于下游调用网关数据面:以 gatewayIds 圈定可调用网关,allowedModels / allowedTools / allowedAgents 圈定模型、工具与 Agent Target,principal 携带角色与扁平 claims 供策略引擎判定。
端点清单
| 方法 + 路径 | 用途 | ||
|---|---|---|---|
GET /ai-gateway/resources/{kind} / POST .../{kind} | 资源列表/创建(kind: model-deployments, targets) | ||
| `GET | PUT | DELETE /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 | 发现目标可用模型 | ||
| `GET | PUT .../resources/targets/{id}/mounts` | 目标挂载列表/整体替换 | |
PUT /ai-gateway/gateways/{gatewayId}/policy | 更新网关策略 | ||
POST /ai-gateway/gateways/{gatewayId}/snapshots | 封存快照(seal) | ||
GET .../gateways/{gatewayId}/snapshots/status | 快照状态 | ||
| `GET | POST /ai-gateway/policy-engines、GET .../{policyEngineId}` | 策略引擎列表/创建/详情 | |
| `GET | POST .../policy-engines/{policyEngineId}/bundles、GET .../bundles/{policyBundleId}` | 策略包列表/发布/详情 | |
POST .../policy-engines/{policyEngineId}/dry-run | 策略试运行 | ||
| `GET | POST /ai-gateway/keys、GET .../keys/{keyId}、PUT .../keys/{keyId}/status` | 网关子密钥 | |
| `GET | POST /ai-gateway/standard-models` | 标准模型目录 | |
POST /ai-gateway/standard-models/import | 批量导入发现模型 | ||
PUT /ai-gateway/standard-models/{standardModelId} | 更新标准模型 | ||
POST /ai-gateway/tool-connections / .../discover、`PUT | DELETE .../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 | 观测总览 |
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。
统一资源与修订
GET /v1/ai-gateway/resources/{kind}
分页列出指定 kind 的统一资源:model-deployments(模型部署)或 targets(上游目标)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:model-deployments / targets。 |
输出:返回 200 + 资源列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 实体字段随
kind而定,spec 以泛化 schema 暴露;构造 payload 以 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}
创建统一资源:在项目内新建一个模型部署或上游目标;资源上线走修订流而非直接生效。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:model-deployments / targets。 |
输出:返回 201 + 新建资源文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- spec 未定义具体请求体字段(泛化 schema):请求体为目标资源的定义文档,字段错误返回
400结构校验失败。 - 创建后用
POST .../revisions建修订并经状态迁移上线。
调用示例:
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 读取单个统一资源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:model-deployments / targets。 |
id | path | string | 是 | — | 资源 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}
整体替换资源定义:以请求体完整覆盖现有资源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:model-deployments / targets。 |
id | path | string | 是 | — | 资源 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}
删除统一资源:从项目内移除该模型部署或上游目标。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:model-deployments / targets。 |
id | path | string | 是 | — | 资源 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)状态机上线,保证配置可回溯、可回滚。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:model-deployments / targets。 |
id | path | string | 是 | — | 资源 ID。 |
输出:返回 201 + 新修订文档(含修订内容与状态)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 修订创建后用
POST .../revisions/{revisionId}/{action}做状态迁移推进上线。
调用示例:
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}
读取单个修订的内容与当前状态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类。 |
id | path | string | 是 | — | 资源 ID。 |
revisionId | path | string | 是 | — | 修订 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 为迁移动作名):推进修订在状态机中的流转,上线走此通道。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类。 |
id | path | string | 是 | — | 资源 ID。 |
revisionId | path | string | 是 | — | 修订 ID。 |
action | path | string | 是 | — | 迁移动作名(按当前状态判定合法取值;非法迁移返回 409)。 |
输出:返回 200 + 迁移后的修订文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 按当前状态判定合法
action:非法迁移是409冲突而不是参数错误。
调用示例:
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
实测一次模型部署的推理:验证部署通路与响应质量后再上线。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 模型部署资源 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
对上游目标执行探活:验证目标当前可达与健康状态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 目标资源 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)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 目标资源 ID。 |
输出:返回 200 + 发现的模型清单(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 出站访问受 SSRF、重定向与请求/响应大小限制;不要用 Target 访问私网或云元数据地址。
调用示例:
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
读取目标的挂载列表:挂载把目标接入一个或多个网关快照。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 目标资源 ID。 |
输出:返回 200 + 挂载列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- Target 不直接保存
gatewayId:目标与网关的关联通过挂载关系表达。
调用示例:
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
整体替换目标挂载列表:以请求体为准重建挂载关系。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 目标资源 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 新增)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 逻辑模型资源 ID。 |
输出:返回 200 + 挂载列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 与 Target 挂载一致:逻辑模型不直接保存
gatewayId,与网关的关联通过挂载关系表达。
调用示例:
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 新增)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 逻辑模型资源 ID。 |
输出:返回 200 + 替换后的挂载列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 整体替换语义:请求体为挂载配置数组(全量替换语义,未包含的现有挂载会被移除),具体字段以 spec 为准。
调用示例:
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
更新网关策略:把策略引擎判定规则挂到指定网关。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
gatewayId | path | string | 是 | — | 逻辑网关 ID。 |
输出:返回 200 + 更新后的网关策略(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 策略对数据面的实际生效以发布 bundle 并挂到网关策略为准;
dry-run只做评估。
调用示例:
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 端点轮询。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
gatewayId | path | string | 是 | — | 逻辑网关 ID。 |
输出:返回 201 + 快照受理结果(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 封存后的配置变更不回写旧快照;子密钥创建时可指定
region就近使用已封存快照。 - 公开 listener 验证 Key、Gateway、Consumer 与已发布 Snapshot 的一致性:改配置后须重新封存发布。
调用示例:
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
查询快照封存进度与结果:封存是异步过程,轮询本端点至完成。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
gatewayId | path | string | 是 | — | 逻辑网关 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}
读取单个策略引擎详情。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
policyEngineId | path | string | 是 | — | 策略引擎 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)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
policyEngineId | path | string | 是 | — | 策略引擎 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
发布新策略包:发布并挂到网关策略后才对数据面实际生效。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
policyEngineId | path | string | 是 | — | 策略引擎 ID。 |
输出:返回 201 + 新策略包(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 发布顺序:
dry-run验证 → 发布 bundle → 挂到PUT .../gateways/{gatewayId}/policy。
调用示例:
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}
读取单个策略包内容。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
policyEngineId | path | string | 是 | — | 策略引擎 ID。 |
policyBundleId | path | string | 是 | — | 策略包 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
以试运行模式评估策略对请求的判定:不执行请求、不产生副作用。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
policyEngineId | path | string | 是 | — | 策略引擎 ID。 |
输出:返回 200 + 评估结果(各策略对请求的判定)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
dry-run只做策略评估:对数据面的实际生效仍以发布 bundle 并挂到网关策略为准。
调用示例:
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 类型定义与实际资源为准)。
- scope 为
aiGateway.write(子密钥读取挂写权限之下,与管理面读写分离的口径不同,注意授权面)。
调用示例:
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 圈定。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | body | string | 是 | — | 密钥名。 |
gatewayIds | body | string[] | 是 | — | 允许调用的逻辑网关 ID 数组。 |
region | body | string | 否 | — | 快照区域:调用侧就近使用该区域已封存快照。 |
allowedModels | body | string[] | 否 | — | 允许的逻辑模型名;["*"] 放行已授权网关上的全部模型。 |
allowedTools | body | string[] | 否 | — | 允许的 Tool 资源 ID;["*"] 放行全部,空数组 = 全部拒绝(与省略字段不同)。 |
allowedAgents | body | string[] | 否 | — | 允许的 A2A / HTTP Agent Target 资源 ID;["*"] 放行全部,空数组 = 全部拒绝。 |
defaultLogicalModel | body | string | 否 | — | 请求缺 model 时使用的兜底逻辑模型。 |
principal | body | object | 否 | — | 签入凭据的角色与扁平 claims(roles + claims),供策略引擎判定。 |
limits | body | object[] | 否 | — | 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 类型定义与实际资源为准)。
- 公开 listener 使用
abk_凭据并验证 Key、Gateway、Consumer 与已发布 Snapshot 的一致性;不要把 LLM Gateway Key、Project API Key 或上游 Provider Key 当abk_使用。 - 明文凭据只在签发响应中出现一次,务必立即妥善保存。
调用示例:
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_ 凭据。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
keyId | path | string | 是 | — | 子密钥 ID。 |
输出:返回 200 + 凭据明文与元数据(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 与 LLM Gateway 子密钥「仅创建时返回一次」不同:AI Gateway 密钥为加密存储、可恢复;仍应避免频繁拉取明文。
调用示例:
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
更新子密钥启停状态:停用后该凭据立即无法通过网关校验。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
keyId | path | string | 是 | — | 子密钥 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 与状态过滤。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerProfileId | query | string | 否 | 默认 "" | 按 provider profile 过滤。 |
status | query | string | 否 | 枚举 '', 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 定位一个目录条目。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerProfileId | body | string | 是 | — | Provider profile ID。 |
profileVersion | body | string | 否 | — | Provider profile 版本(可选)。 |
modelId | body | string | 是 | — | Provider 模型 ID。 |
displayName | body | string | 否 | — | 模型展示名。 |
metadata | body | object | 否 | — | 标准模型元信息对象。 |
status | body | string | 否 | 枚举 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 以导入为准合并。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
providerProfileId | body | string | 是 | — | Provider profile ID。 |
profileVersion | body | string | 否 | — | Provider profile 版本(可选)。 |
fetchedAt | body | string | 否 | — | 上游抓取时间。 |
models | body | object[] | 是 | — | 发现的模型数组(来自 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}
更新标准模型条目:改展示名、元信息或目录状态。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
standardModelId | path | string | 是 | — | 标准模型文档 ID。 |
displayName | body | string | 否 | — | 模型展示名。 |
metadata | body | object | 否 | — | 标准模型元信息对象。 |
status | body | string | 否 | 枚举 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 类型定义与实际资源为准)。
- MCP Tool 列表、搜索和调用共用 Agent allowlist 与 OPA 授权;Tool 副作用受幂等门禁保护。
调用示例:
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}
更新工具连接配置。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 工具连接 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}
删除工具连接:网关侧随即不可再经此连接调用工具。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 工具连接 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 连接诊断面板同源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
id | path | string | 是 | — | 工具连接 ID。 |
输出:返回 200 + 测试与诊断结果(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
- 可选 body
toolId只测单个工具;返回逐工具状态与检查明细(字段以 spec 为准)。
调用示例:
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}
读取单条调用记录详情。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
invocationId | path | string | 是 | — | 调用记录 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 类型定义与实际资源为准)。
错误与边界
- 资源/网关/策略引擎/子密钥不存在:
404;重复创建:409;修订状态机非法迁移:409冲突(按当前状态判定合法action)。 - 统一资源端点为泛化 schema:请求体字段错误同样返回 400 结构校验失败;以 Server SDK 类型定义为准构造 payload。
- 子密钥
allowedTools/allowedAgents的空数组语义是全部拒绝,与省略字段不同;需要放行时显式传["*"]。 - 快照封存是异步过程:
POST返回后以snapshots/status轮询至完成;封存后的配置变更不回写旧快照。 dry-run只做策略评估,不执行请求;策略对数据面的实际生效以发布 bundle 并挂到网关策略为准。
与 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.testToolConnection | POST /ai-gateway/tool-connections/{id}/test(2.8.0) | |
AIGateway.listLogicalModelMounts / replaceLogicalModelMounts | `GET | PUT /ai-gateway/resources/logical-models/{id}/mounts`(2.8.0) |
AIGateway.listInvocations / getInvocation / getModelDeploymentMetrics / getObservabilityOverview | 观测端点 |
事实源
- Server API spec:
agentbase-sdksv2.6.0specs/open-api3-latest-server.json(/ai-gateway域 39 个端点;统一资源端点与泛化响应 schema)。 - Server SDK 生成物:
server-nodejs/server-javav2.6.0AIGatewayservice。 - 2.7.0 行为增量:appbase release-2.7.0 PR 526(凭据治理/工具审批/托管模板);spec v2.6.0 → v2.7.0 ai-gateway 段唯一参数变化为
POST /ai-gateway/keys新增limits(实读git diff确认)。 - 2.8.0 新增端点:
POST /ai-gateway/tool-connections/{id}/test、GET|PUT /ai-gateway/resources/logical-models/{id}/mounts(specopen-api3-latest-server.jsonv2.8.0 实读确认,响应均为泛化 schema)。 - 语义深度参考:
skills/ob-agentbase/references/ai-gateway.md。