Docs
文档目录

AI Gateway API

AI Gateway 管理面提供网关、工具目标、策略、子密钥及调用观测。模型推理请使用 LLM Gateway。

服务与资源边界

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}资源列表/创建(工具 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(工具目标)。

输入:

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

输出:返回 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" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  --header @-

)

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

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

创建统一资源:在项目内新建工具目标;资源上线走修订流而非直接生效。

输入:

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

输出:返回 201 + 新建资源文档(泛化 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 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 读取单个统一资源。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:targets。
idpathstring是—资源 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}

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

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:targets。
idpathstring是—资源 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}

删除统一资源:从项目内移除该工具目标。

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类:targets。
idpathstring是—资源 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)状态机上线,保证配置可回溯、可回滚。

输入:

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

输出:返回 201 + 新修订文档(含修订内容与状态)(泛化 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 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}

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

输入:

参数位置类型必填默认/枚举说明
kindpathstring是—资源种类。
idpathstring是—资源 ID。
revisionIdpathstring是—修订 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 为迁移动作名):推进修订在状态机中的流转,上线走此通道。

输入:

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

输出:返回 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 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

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

输入:

参数位置类型必填默认/枚举说明
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

v2.12.0:此模型相关入口已禁用。 以下保留历史接口结构供迁移参考;请使用 LLM Gateway 调用模型。

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)

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

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

输入:

参数位置类型必填默认/枚举说明
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 圈定。

省略 allowedModels、allowedTools 或 allowedAgents 时,各自默认 ["*"];显式空数组拒绝该类型。默认通配仍受网关快照与策略约束。

输入:

参数位置类型必填默认/枚举说明
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 类型定义与实际资源为准)。

调用示例:

(
  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_ 凭据。

输入:

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

输出:需要 aiGateway.write;成功返回 200 和 {"key":"<明文凭据>"},不包含密钥元数据。

调用示例:

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 判定所有节点已撤销。

输入:

参数位置类型必填默认/枚举说明
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

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 连接诊断面板同源。

输入:

参数位置类型必填默认/枚举说明
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

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 类型定义与实际资源为准)。

错误与边界

与 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 / replaceLogicalModelMountsGET|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 只表示接受,须使用返回的任务标识查询终态。

HTTPScopeSDK
GET /ai-gateway/approval-requestsaiGateway.readaiGateway.listApprovalRequests
GET /ai-gateway/approval-requests/{id}aiGateway.readaiGateway.getApprovalRequest
POST /ai-gateway/approval-requests/{id}/approveaiGateway.writeaiGateway.approveApprovalRequest
POST /ai-gateway/approval-requests/{id}/rejectaiGateway.writeaiGateway.rejectApprovalRequest
GET /ai-gateway/initialization-statusaiGateway.readaiGateway.getInitializationStatus
GET /ai-gateway/tool-embeddingsaiGateway.readaiGateway.listToolEmbeddings
POST /ai-gateway/tool-embeddingsaiGateway.writeaiGateway.createToolEmbeddings

GET /ai-gateway/approval-requests

成功响应:HTTP 200 — any.

GET /ai-gateway/approval-requests/{id}

参数位置必填类型约束 / 默认值含义
idpath是string—路径参数 id。

成功响应:HTTP 200 — any.

POST /ai-gateway/approval-requests/{id}/approve

参数位置必填类型约束 / 默认值含义
idpath是string—路径参数 id。

成功响应:HTTP 200 — any.

POST /ai-gateway/approval-requests/{id}/reject

参数位置必填类型约束 / 默认值含义
idpath是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 或断网后先读取任务状态。涉及幂等键的写入重试保留同一个键,主动重新执行才换键。删除与清空前确认目标,禁止通过循环重试扩大写入。