AI Gateway API
AI Gateway 管理面提供网关、工具目标、策略、子密钥及调用观测。模型推理请使用 LLM Gateway。
服务与资源边界
AI Gateway API 是 Agentbase 面向生产级多模型与多工具治理的控制面与可观测性接口(如展示项目中的生产网关 prod-enterprise-ai-gateway / gw_7194685489feb1e169548619):
v2.12.0 模型能力限制:AI Gateway 模型推理、逻辑模型、模型部署、模型发现和标准模型管理不可用;模型调用请使用 LLM Gateway。MCP、A2A 和 HTTP Agent 工具接口不属于此限制。
策略与安全边界:可通过 OPA 策略预演检查策略决策。当前版本不提供语义响应缓存,不能保证对输入输出自动脱敏;请在发送前处理敏感数据。
与 LLM Gateway 的分工:LLM Gateway API 用于模型供应商与推理调用;AI Gateway 用于网关策略、子密钥、工具连接与调用观测。
资源与基础路径
Base URL:
https://<your-endpoint>/v1,路径前缀/ai-gateway。资源模型:工具目标使用统一资源端点
/ai-gateway/resources/{kind}与修订子路径;模型资源已禁用。专有端点:
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 供策略引擎判定。
端点总览
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} | 资源列表/创建(工具 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 | 测试模型部署 v2.12.0 不可用 |
POST .../resources/targets/{id}/health-check | 目标健康检查 |
POST .../resources/targets/{id}/models/discover | 发现目标可用模型 v2.12.0 不可用 |
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 | 标准模型目录 v2.12.0 不可用 |
POST /ai-gateway/standard-models/import | 批量导入发现模型 v2.12.0 不可用 |
PUT /ai-gateway/standard-models/{standardModelId} | 更新标准模型 v2.12.0 不可用 |
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) v2.12.0 不可用 |
PUT .../resources/logical-models/{id}/mounts | 整体替换逻辑模型挂载(2.8.0) v2.12.0 不可用 |
GET /ai-gateway/invocations / GET .../invocations/{invocationId} | 调用记录 |
GET /ai-gateway/metrics/model-deployments | 部署指标 v2.12.0 不可用 |
GET /ai-gateway/observability/overview | 观测总览 |
端点详解
工具目标可通过修订与网关快照管理;模型相关资源在本版本不可用。
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。
统一资源与修订
版本限制:以下通用 {kind} 接口不支持 logical-models、model-deployments 或推理型 Target;工具 Target 按对应权限和配置使用。
GET /v1/ai-gateway/resources/{kind}
分页列出指定 kind 的统一资源:targets(工具目标)。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:targets。 |
输出:返回 200 + 资源列表(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
实体字段随
kind而定,spec 以泛化 schema 暴露;构造 payload 以 Server SDK 类型定义为准。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "https://<your-endpoint>/v1/ai-gateway/resources/targets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @-
)响应示例:响应为资源列表 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
POST /v1/ai-gateway/resources/{kind}
创建统一资源:在项目内新建工具目标;资源上线走修订流而非直接生效。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:targets。 |
输出:返回 201 + 新建资源文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
spec 未定义具体请求体字段(泛化 schema):请求体为目标资源的定义文档,字段错误返回
400结构校验失败。创建后用
POST .../revisions建修订并经状态迁移上线。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "https://<your-endpoint>/v1/ai-gateway/resources/targets" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-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 | 是 | — | 资源种类:targets。 |
id | path | string | 是 | — | 资源 ID。 |
输出:返回 200 + 资源文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @-
)响应示例:响应为资源文档 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
PUT /v1/ai-gateway/resources/{kind}/{id}
整体替换资源定义:以请求体完整覆盖现有资源。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:targets。 |
id | path | string | 是 | — | 资源 ID。 |
输出:返回 200 + 替换后的资源文档(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
整体替换:未传字段按请求体语义视为删除,谨慎使用。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X PUT "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{ ... 完整资源定义文档 ... }'
)响应示例:200:响应为替换后的资源文档 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
DELETE /v1/ai-gateway/resources/{kind}/{id}
删除统一资源:从项目内移除该工具目标。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:targets。 |
id | path | string | 是 | — | 资源 ID。 |
输出:204 No Content,无响应体。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X DELETE "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @-
)响应示例:204 No Content:无响应体(已删除)。
POST /v1/ai-gateway/resources/{kind}/{id}/revisions
为资源创建新修订:工具目标经修订(revision)状态机上线,保证配置可回溯、可回滚。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
kind | path | string | 是 | — | 资源种类:targets。 |
id | path | string | 是 | — | 资源 ID。 |
输出:返回 201 + 新修订文档(含修订内容与状态)(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
修订创建后用
POST .../revisions/{revisionId}/{action}做状态迁移推进上线。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>/revisions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-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 类型定义与实际资源为准)。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>/revisions/<REVISION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @-
)响应示例:响应为修订文档 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冲突而不是参数错误。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "https://<your-endpoint>/v1/ai-gateway/resources/targets/<ID>/revisions/<REVISION_ID>/publish" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @-
)响应示例:200:响应为迁移后的修订文档 JSON(泛化 schema any:响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准)。
POST /v1/ai-gateway/resources/model-deployments/{id}/test
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
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
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
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)
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
PUT /v1/ai-gateway/resources/logical-models/{id}/mounts(2.8.0)
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
网关策略与快照
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.read;读取单个密钥明文需要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 圈定。
省略 allowedModels、allowedTools 或 allowedAgents 时,各自默认 ["*"];显式空数组拒绝该类型。默认通配仍受网关快照与策略约束。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
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_使用。明文凭据也可由拥有
aiGateway.write的调用者通过单密钥读取接口恢复;请妥善保存并严格限制该权限。
调用示例:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "https://<your-endpoint>/v1/ai-gateway/keys" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"name": "docs-gateway-key",
"gatewayIds": ["gw_docs"],
"allowedModels": [],
"allowedTools": ["<TOOL_ID>"],
"allowedAgents": [],
"principal": { "roles": ["tool-client"], "claims": { "tenant": "docs" } }
}'
)响应示例:201:响应为签发结果 JSON(泛化 schema;含明文凭据与密钥元数据,字段以实际响应为准)。
GET /v1/ai-gateway/keys/{keyId}
读取子密钥明文凭据(可恢复语义):用于找回曾签发的 abk_ 凭据。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
keyId | path | string | 是 | — | 子密钥 ID。 |
输出:需要 aiGateway.write;成功返回 200 和 {"key":"<明文凭据>"},不包含密钥元数据。
与 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
更新子密钥启停状态。服务会尝试使网关认证缓存失效;若缓存失效失败,旧的有效缓存可能短暂继续通过校验,已在途请求也可能继续。操作后应验证实际调用被拒绝,不能仅凭 200 判定所有节点已撤销。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
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
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
POST /v1/ai-gateway/standard-models
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
POST /v1/ai-gateway/standard-models/import
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
PUT /v1/ai-gateway/standard-models/{standardModelId}
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
POST /v1/ai-gateway/tool-connections
创建工具连接,使用 aiGateway.write。请求体包含非空 name、受支持的 targetKind、对应的 configuration 和至少一个 tools 条目;可选 slug、description 与 catalogSource。以下示例为 MCP 服务:替换可访问的服务地址和工具定义,并确保网络策略允许连接。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "https://<your-endpoint>/v1/ai-gateway/tool-connections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{"name":"docs-tools","targetKind":"MCP_SERVER","configuration":{"mcpServer":{"endpoint":"https://tools.example.com/mcp"}},"tools":[{"name":"search","inputSchema":{"type":"object"},"sideEffectLevel":"READ"}]}'
)成功返回 201 和连接的目标及工具资源。工具实际调用仍受挂载、凭证和策略限制。
POST /v1/ai-gateway/tool-connections/discover
发现 MCP 服务暴露的工具,使用 aiGateway.write。请求体必须包含 endpoint;credentialProviderId 与 credential 是可选且互斥的凭据方式,二者不可同时提供。下例不提供认证,请替换为实际可访问的地址。
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "https://<your-endpoint>/v1/ai-gateway/tool-connections/discover" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{"endpoint":"https://tools.example.com/mcp"}'
)成功返回 200 及发现结果;上游需可达并允许调用。
PUT /v1/ai-gateway/tool-connections/{id}
更新连接使用 aiGateway.write,请求体采用与创建相同的完整连接结构。先获取当前配置,并在提交前保留需要继续使用的工具和配置;替换 <ID> 后可参考上面的创建请求体。
DELETE /v1/ai-gateway/tool-connections/{id}
删除需 aiGateway.write、连接 ID 和查询参数 region。活动连接须先停用;缺少区域或连接仍处于活动状态时不能删除。以下 <REGION> 应替换为实际区域并进行 URL 编码:
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X DELETE "https://<your-endpoint>/v1/ai-gateway/tool-connections/<ID>?region=<REGION>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
--header @-
)成功返回 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
v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。
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 | 观测端点 |
2.12.0 接口与兼容增量
以下路径相对于 /v1。服务端请求携带 X-Appwrite-Project 与 X-Appwrite-Key;Key 仅留在服务端。Scope 是下表的必要条件;数据集、归属和资源状态还会追加校验。HTTP 202 只表示接受,须使用返回的任务标识查询终态。
| HTTP | Scope | SDK |
|---|---|---|
GET /ai-gateway/approval-requests | aiGateway.read | aiGateway.listApprovalRequests |
GET /ai-gateway/approval-requests/{id} | aiGateway.read | aiGateway.getApprovalRequest |
POST /ai-gateway/approval-requests/{id}/approve | aiGateway.write | aiGateway.approveApprovalRequest |
POST /ai-gateway/approval-requests/{id}/reject | aiGateway.write | aiGateway.rejectApprovalRequest |
GET /ai-gateway/initialization-status | aiGateway.read | aiGateway.getInitializationStatus |
GET /ai-gateway/tool-embeddings | aiGateway.read | aiGateway.listToolEmbeddings |
POST /ai-gateway/tool-embeddings | aiGateway.write | aiGateway.createToolEmbeddings |
GET /ai-gateway/approval-requests
成功响应:HTTP 200 — any.
GET /ai-gateway/approval-requests/{id}
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
id | path | 是 | string | — | 路径参数 id。 |
成功响应:HTTP 200 — any.
POST /ai-gateway/approval-requests/{id}/approve
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
id | path | 是 | string | — | 路径参数 id。 |
成功响应:HTTP 200 — any.
POST /ai-gateway/approval-requests/{id}/reject
| 参数 | 位置 | 必填 | 类型 | 约束 / 默认值 | 含义 |
|---|---|---|---|---|---|
id | path | 是 | string | — | 路径参数 id。 |
成功响应:HTTP 200 — any.
GET /ai-gateway/initialization-status
成功响应:HTTP 200 — any.
GET /ai-gateway/tool-embeddings
成功响应:HTTP 200 — any.
POST /ai-gateway/tool-embeddings
成功响应:HTTP 200 — any.
错误与重试边界
400/422:核对类型、枚举与规则;401/403:核对身份与 Scope,数据集分析还要求 traces.read 和 datasets.read;404:确认资源仍存在且属于当前项目;409:重新读取当前状态后决定是否重试;429:按 Retry-After 等待;5xx 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。