AI Gateway API
AI Gateway management plane: logical gateways (gateway), model deployments and targets (model-deployments / targets) resources and their revision (revision) state machine, policy engine (policy engine + bundle + dry-run), gateway sub-keys, tool connections, standard model catalog (standard models), invocation observation and metrics. Coexists with llm-gateway: that one targets the LLM inference data plane, while this domain targets the governance plane for generative AI resources.
Service and resource boundaries
The AI Gateway API is Agentbase's control plane and observability interface for production-grade multi-model and multi-tool governance (e.g. showing the production gateways prod-enterprise-ai-gateway / gw_7194685489feb1e169548619 in a project):
Logical models and multi-target routing: via logical models (e.g.
lm-enterprise-chat), business calls are decoupled from underlying physical model providers (e.g.dashscope-prod'sqwen-plusprimary model andqwen-turbofallback model), supporting weighted traffic splitting, health checks, and automatic failover.Safety guardrails and semantic cache: built-in Policy Engine, safety guardrail configurations (e.g.
gp-enterprise-safety), and semantic cache policies (e.g.cp-semantic-cache), which are atomically pushed to the data plane after the gateway Snapshot Seal.Division of labor with LLM Gateway: LLM Gateway API focuses on project-level foundational model provider management and direct inference calls, while this AI Gateway API page handles cross-deployment routing orchestration, gateway consumer sub-keys (Keys), MCP/A2A tool connections, and invocation-level monitoring metrics.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/ai-gateway.Resource model: most entities use the unified resource endpoint
/ai-gateway/resources/{kind}, wherekindcurrently takes the values:model-deployments(model deployment),targets(upstream target, carrying mounts); withid+ revision sub-path.Dedicated endpoints:
gateways/{gatewayId}(policies/snapshots),keys,policy-engines,tool-connections,standard-models,invocations,metrics,observability.
Authentication and Permissions
For authentication and request header conventions, see Common conventions. There are only two scope types: aiGateway.read (queries, observation) and aiGateway.write (all write operations and sub-key read/management). Credentials issued by gateway sub-keys (POST /ai-gateway/keys) are used to call the gateway data plane downstream: use gatewayIds to scope callable gateways, allowedModels / allowedTools / allowedAgents to scope models, tools, and Agent Targets, and principal carries roles and flat claims for the policy engine to evaluate.
Endpoint overview
AI Gateway endpoints are organized around five core subdomains: unified resources and the revision state machine (/ai-gateway/resources/{kind}*), gateway policies and sealed snapshots (/ai-gateway/gateways/{gatewayId}/*), policy engine and dry-run (/ai-gateway/policy-engines*), sub-keys and the standard model catalog (/ai-gateway/keys*, /ai-gateway/standard-models*), and tool connections and invocation observation (/ai-gateway/tool-connections*, /ai-gateway/invocations*, /ai-gateway/metrics*).
Endpoint List
| Method + path | Purpose |
|---|---|
GET /ai-gateway/resources/{kind} / POST .../{kind} | Resource list/create (kind: model-deployments, targets) |
GET|PUT|DELETE /ai-gateway/resources/{kind}/{id} | Resource read/full replace/delete |
POST .../resources/{kind}/{id}/revisions | Create revision |
GET .../revisions/{revisionId} | Read revision |
POST .../revisions/{revisionId}/{action} | Revision state transition |
POST .../resources/model-deployments/{id}/test | Test model deployment |
POST .../resources/targets/{id}/health-check | Target health check |
POST .../resources/targets/{id}/models/discover | Discover target's available models |
GET|PUT .../resources/targets/{id}/mounts | Target mount list/full replace |
PUT /ai-gateway/gateways/{gatewayId}/policy | Update gateway policy |
POST /ai-gateway/gateways/{gatewayId}/snapshots | Seal snapshot (seal) |
GET .../gateways/{gatewayId}/snapshots/status | Snapshot status |
GET|POST /ai-gateway/policy-engines, GET .../{policyEngineId} | Policy engine list/create/details |
GET|POST .../policy-engines/{policyEngineId}/bundles, GET .../bundles/{policyBundleId} | Policy bundle list/publish/details |
POST .../policy-engines/{policyEngineId}/dry-run | Policy dry-run |
GET|POST /ai-gateway/keys, GET .../keys/{keyId}, PUT .../keys/{keyId}/status | Gateway sub-keys |
GET|POST /ai-gateway/standard-models | Standard model catalog |
POST /ai-gateway/standard-models/import | Batch import discovered models |
PUT /ai-gateway/standard-models/{standardModelId} | Update standard model |
POST /ai-gateway/tool-connections / .../discover, PUT|DELETE .../tool-connections/{id} | Tool connections |
POST .../tool-connections/{id}/test | Test tool connection (2.8.0) |
GET .../resources/logical-models/{id}/mounts | List logical model mounts (2.8.0) |
PUT .../resources/logical-models/{id}/mounts | Full replace logical model mounts (2.8.0) |
GET /ai-gateway/invocations / GET .../invocations/{invocationId} | Invocation records |
GET /ai-gateway/metrics/model-deployments | Deployment metrics |
GET /ai-gateway/observability/overview | Observability overview |
Endpoint details
Unified resources (model-deployments, targets, logical-models) follow the change governance flow of "draft config → create revision (Revision) → state transition (Activate / Rollback) → gateway Snapshot Seal", ensuring zero-jitter switching of production traffic.
Requests and Responses
Complete specifications are given per endpoint below: input (field-level tables for path / query / body), output (return model and key fields), call examples (copyable curl) and response examples. Endpoints marked with "generalized schema any" return the JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for specific fields.
Unified Resources and Revisions
GET /v1/ai-gateway/resources/{kind}
List with pagination the unified resources of a given kind: model-deployments (model deployment) or targets (upstream target).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | Yes | — | Resource kind: model-deployments / targets. |
Output: Returns 200 + the resource list (generalized schema any: the response body is the JSON document of the corresponding resource; concrete fields follow the Server SDK type definitions and the actual resource).
Entity fields depend on
kind; the spec is exposed as a generalized schema; construct payloads according to the Server SDK type definitions.
Call example:
curl "https://<your-endpoint>/v1/ai-gateway/resources/model-deployments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a resource list JSON (generalized schema any: the response body is the JSON document of the corresponding resource; concrete fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/resources/{kind}
Create a unified resource: create a new model deployment or upstream target within a project; bringing a resource online follows the revision flow rather than taking effect directly.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | Yes | — | Resource kind: model-deployments / targets. |
Output: Returns 201 + the newly created resource document (generalized schema any: the response body is the JSON document of the corresponding resource; concrete fields follow the Server SDK type definitions and the actual resource).
The spec does not define concrete request body fields (generalized schema): the request body is the definition document of the target resource; field errors return
400structural validation failure.After creation, use
POST .../revisionsto create a revision and bring it online via state transition.
Call example:
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,字段以资源定义为准) ... }'Response example: 201: the response is the resource document JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
GET /v1/ai-gateway/resources/{kind}/{id}
Read a single unified resource by ID.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | Yes | — | Resource kind: model-deployments / targets. |
id | path | string | yes | — | Resource ID. |
Output: returns 200 + the resource document (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: the response is the resource document JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
PUT /v1/ai-gateway/resources/{kind}/{id}
Fully replace the resource definition: the request body completely overwrites the existing resource.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | Yes | — | Resource kind: model-deployments / targets. |
id | path | string | yes | — | Resource ID. |
Output: returns 200 + the replaced resource document (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Full replacement: fields not provided are treated as deleted according to request body semantics; use with caution.
Call example:
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 '{ ... 完整资源定义文档 ... }'Response example: 200: the response is the replaced resource document JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
DELETE /v1/ai-gateway/resources/{kind}/{id}
Delete a unified resource: remove the model deployment or upstream target from the project.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | Yes | — | Resource kind: model-deployments / targets. |
id | path | string | yes | — | Resource ID. |
Output: 204 No Content, no response body.
Call example:
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>"Response example: 204 No Content: No response body (deleted).
POST /v1/ai-gateway/resources/{kind}/{id}/revisions
Create a new revision for a resource: model deployments and targets go live through a revision state machine, ensuring configuration is traceable and rollback-capable.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | Yes | — | Resource kind: model-deployments / targets. |
id | path | string | yes | — | Resource ID. |
Output: returns 201 + the new revision document (including revision content and status) (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
After the revision is created, use
POST .../revisions/{revisionId}/{action}to perform state transitions and advance the rollout.
Call example:
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 '{ ... 修订内容 ... }'Response example: 201: the response is the revision document JSON (including revision ID, content, and status) (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
GET /v1/ai-gateway/resources/{kind}/{id}/revisions/{revisionId}
Read the content and current status of a single revision.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | yes | — | Resource kind. |
id | path | string | yes | — | Resource ID. |
revisionId | path | string | yes | — | Revision ID. |
Output: returns 200 + the revision document (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: the response is the revision document JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/resources/{kind}/{id}/revisions/{revisionId}/{action}
Perform a state transition on a revision (action is the transition action name): advance the revision through the state machine; go-live goes through this channel.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | yes | — | Resource kind. |
id | path | string | yes | — | Resource ID. |
revisionId | path | string | yes | — | Revision ID. |
action | path | string | yes | — | Transition action name (valid values depend on the current status; invalid transitions return 409). |
Output: returns 200 + the revision document after the transition (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
The valid
actiondepends on the current status: an invalid transition is a409conflict, not a parameter error.
Call example:
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>"Response example: 200: the response is the post-transition revision document JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/resources/model-deployments/{id}/test
Live-test the inference of a model deployment: verify the deployment path and response quality before going live.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | yes | — | Model deployment resource ID. |
Output: returns 200 + the test result (including inference output and metadata) (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: 200: the response is the test result JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/resources/targets/{id}/health-check
Run a health probe against an upstream target: verify the target's current reachability and health status.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | yes | — | Target resource ID. |
Output: returns 200 + the probe result (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: 200: the response is the probe result JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/resources/targets/{id}/models/discover
Discover the list of models actually available on an upstream target: the results can be consolidated into the standard model catalog (see standard-models/import).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | yes | — | Target resource ID. |
Output: returns 200 + the discovered model list (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Outbound access is subject to SSRF, redirect, and request/response size limits; do not use Target to access private network or cloud metadata addresses.
Call example:
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>"Response example: 200: the response is the model list JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
GET /v1/ai-gateway/resources/targets/{id}/mounts
Read the target's mount list: mounts attach the target to one or more gateway snapshots.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | yes | — | Target resource ID. |
Output: returns 200 + the mount list (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Target does not directly store
gatewayId: the association between the target and gateways is expressed through mount relations.
Call example:
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>"Response example: the response is the mount list JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
PUT /v1/ai-gateway/resources/targets/{id}/mounts
Fully replace the target's mount list: rebuild the mount relations based on the request body.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | yes | — | Target resource ID. |
Output: returns 200 + the replaced mount list (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Full replacement semantics: existing mounts not included in the request body will be removed.
Call example:
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 '{ ... 完整挂载列表 ... }'Response example: 200: the response is the replaced mount list JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
GET /v1/ai-gateway/resources/logical-models/{id}/mounts(2.8.0)
Read the logical model's mount list: mounts attach the logical model to one or more gateway snapshots (added in 2.8.0).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | yes | — | Logical model resource ID. |
Output: returns 200 + the mount list (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Same as Target mounts: the logical model does not directly store
gatewayId; the association with gateways is expressed through mount relations.
Call example:
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>"Response example: the response is the logical model mount list JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
PUT /v1/ai-gateway/resources/logical-models/{id}/mounts(2.8.0)
Fully replace the logical model's mount list: rebuild the mount relations based on the request body (added in 2.8.0).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | yes | — | Logical model resource ID. |
Output: returns 200 + the replaced mount list (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Full replacement semantics: the request body is an array of mount configurations (full replacement semantics; existing mounts not included will be removed); the concrete fields follow the spec.
Call example:
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 为准) ... ]'Response example: 200: the response is the replaced logical model mount list JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Gateway policies and snapshots
PUT /v1/ai-gateway/gateways/{gatewayId}/policy
Update the gateway policy: attach the policy engine's decision rules to the specified gateway.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
gatewayId | path | string | yes | — | Logical gateway ID. |
Output: returns 200 + the updated gateway policy (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Actual effect of policies on the data plane requires publishing the bundle and attaching it to the gateway policy;
dry-runonly performs evaluation.
Call example:
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 '{ ... 网关策略 ... }'Response example: 200: the response is the updated policy JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/gateways/{gatewayId}/snapshots
Seal the current gateway configuration as a snapshot: an asynchronous process; poll the status endpoint for the sealing result.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
gatewayId | path | string | yes | — | Logical gateway ID. |
Output: returns 201 + the snapshot acceptance result (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Configuration changes after sealing are not written back to the old snapshot; when creating a child key, you can specify
regionto use the nearest sealed snapshot.Public listeners verify consistency among Key, Gateway, Consumer, and the published Snapshot: after changing configuration, you must re-seal and publish.
Call example:
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>"Response example: 201: the response is the snapshot acceptance JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
GET /v1/ai-gateway/gateways/{gatewayId}/snapshots/status
Query snapshot sealing progress and result: sealing is an asynchronous process; poll this endpoint until completion.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
gatewayId | path | string | yes | — | Logical gateway ID. |
Output: returns 200 + the sealing status (progress, completion state, and result summary) (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: the response is the sealing status JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Policy engine
GET /v1/ai-gateway/policy-engines
List the policy engines in the project.
Input: no path/query/body parameters.
Output: returns 200 + the policy engine list (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Call example:
curl "https://<your-endpoint>/v1/ai-gateway/policy-engines" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: the response is the policy engine list JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/policy-engines
Create a policy engine: the evaluation carrier that hosts policy bundles.
Input: no path/query/body parameters (generalized resource endpoint; the payload is determined by the target resource definition).
Output: returns 201 + the newly created policy engine (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Call example:
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 '{ ... 策略引擎定义 ... }'Response example: 201: the response is the policy engine JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
GET /v1/ai-gateway/policy-engines/{policyEngineId}
Read the details of a single policy engine.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
policyEngineId | path | string | yes | — | Policy engine ID. |
Output: returns 200 + the policy engine details (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: the response is the policy engine JSON (generalized schema any: the response body is the JSON document of the corresponding resource; the concrete fields follow the Server SDK type definitions and the actual resource).
GET /v1/ai-gateway/policy-engines/{policyEngineId}/bundles
List the policy bundles (bundles) published by the policy engine.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
policyEngineId | path | string | yes | — | Policy engine ID. |
Output: Returns 200 + the policy bundle list (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: The response is a policy bundle list JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/policy-engines/{policyEngineId}/bundles
Publish a new policy bundle: it only takes actual effect on the data plane after being published and attached to the gateway policy.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
policyEngineId | path | string | yes | — | Policy engine ID. |
Output: Returns 201 + the new policy bundle (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Publish order:
dry-runvalidation → publish the bundle → attach it toPUT .../gateways/{gatewayId}/policy.
Call example:
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 '{ ... 策略包内容 ... }'Response example: 201: The response is a policy bundle JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
GET /v1/ai-gateway/policy-engines/{policyEngineId}/bundles/{policyBundleId}
Read the content of a single policy bundle.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
policyEngineId | path | string | yes | — | Policy engine ID. |
policyBundleId | path | string | Yes | — | Policy bundle ID. |
Output: Returns 200 + the policy bundle content (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: The response is a policy bundle JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/policy-engines/{policyEngineId}/dry-run
Evaluate policy decisions on a request in dry-run mode: the request is not executed and no side effects are produced.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
policyEngineId | path | string | yes | — | Policy engine ID. |
Output: Returns 200 + the evaluation result (each policy's decision on the request) (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
dry-runonly performs policy evaluation: actual effect on the data plane still requires publishing the bundle and attaching it to the gateway policy.
Call example:
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 '{ ... 待评估请求与语境 ... }'Response example: 200: The response is an evaluation result JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Sub-keys
GET /v1/ai-gateway/keys
List issued AI Gateway sub-keys (metadata view of abk_ credentials).
Input: no path/query/body parameters.
Output: Returns 200 + the sub-key list (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
The scope is
aiGateway.write(sub-key read is included under write permission; this differs from the management-plane read/write separation — pay attention to the authorization surface).
Call example:
curl "https://<your-endpoint>/v1/ai-gateway/keys" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a sub-key list JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/keys
Issue an AI Gateway sub-key: stored encrypted and recoverable; used by downstream callers to invoke the gateway data plane with abk_ credentials, with permissions bounded by gatewayIds and the three types of allowlists.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
name | body | string | Yes | — | Key name. |
gatewayIds | body | string[] | Yes | — | Array of logical gateway IDs allowed to be called. |
region | body | string | No | — | Snapshot region: callers nearby use the sealed snapshot in that region. |
allowedModels | body | string[] | No | — | Allowed logical model names; ["*"] allows all models on authorized gateways. |
allowedTools | body | string[] | No | — | Allowed Tool resource IDs; ["*"] allows all, empty array = deny all (different from omitting the field). |
allowedAgents | body | string[] | No | — | Allowed A2A / HTTP Agent Target resource IDs; ["*"] allows all, empty array = deny all. |
defaultLogicalModel | body | string | No | — | Fallback logical model used when the request lacks model. |
principal | body | object | No | — | The role and flat claims of the checked-in credential (roles + claims) for the policy engine to evaluate. |
limits | body | object[] | No | — | 2.7.0 Added (appbase PR 526): hard rate limit/quota rules; the spec description is "Optional hard credential/model/Tool/Agent rate and quota rules". Element structure { scope, resourceId?, rate?, quota? }: scope ∈ credential / model / tool / agent (non-credential requires resourceId); rate = { requestsPerSecond, burst } (burst defaults to requestsPerSecond and cannot be configured independently of it); quota = { period, requests?, tokens? }, period ∈ minute / hour / day / month, and tokens are only supported for credential / model scopes. Duplicate rates are not allowed for the same scope+resourceId, and duplicate quotas are not allowed for the same period. |
Output: Returns 201 + the issuance result (including the one-time credential) (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Public listeners use
abk_credentials and verify the consistency of Key, Gateway, Consumer, and the published Snapshot; do not use an LLM Gateway Key, Project API Key, or upstream Provider Key asabk_.The plaintext credential appears only once in the issuance response; be sure to save it properly and immediately.
Call example:
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" }
}'Response example: 201: The response is an issuance result JSON (generalized schema; includes the one-time plaintext credential and key metadata; fields follow the actual response).
GET /v1/ai-gateway/keys/{keyId}
Read the sub-key plaintext credential (recoverable semantics): used to retrieve a previously issued abk_ credential.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
keyId | path | string | Yes | — | Sub-key ID. |
Output: Returns 200 + the plaintext credential and metadata (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Unlike LLM Gateway sub-keys which are "returned only once at creation": AI Gateway keys are stored encrypted and recoverable; still avoid frequently fetching the plaintext.
Call example:
curl "https://<your-endpoint>/v1/ai-gateway/keys/<KEY_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: The response is a credential JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
PUT /v1/ai-gateway/keys/{keyId}/status
Update the sub-key enable/disable status: once disabled, the credential immediately fails gateway validation.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
keyId | path | string | Yes | — | Sub-key ID. |
Output: Returns 200 + the updated sub-key (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Call example:
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 '{ ... 目标状态 ... }'Response example: 200: The response is the updated sub-key JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Standard Model Catalog and Tool Connections
GET /v1/ai-gateway/standard-models
Query the shared standard model catalog: model metadata (display name, status, meta information) reused across resources, with filtering by provider profile and status.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerProfileId | query | string | No | Default "" | Filter by provider profile. |
status | query | string | No | Enum '', active, inactive; default "" | Filter by catalog status: active / inactive (empty string means no filtering). |
Output: Returns 200 + the standard model list (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Call example:
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>"Response example: The response is a standard model list JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/standard-models
Manually register standard model metadata: providerProfileId + modelId locate a catalog entry.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerProfileId | body | string | Yes | — | Provider profile ID. |
profileVersion | body | string | No | — | Provider profile version (optional). |
modelId | body | string | Yes | — | Provider model ID. |
displayName | body | string | No | — | Model display name. |
metadata | body | object | No | — | Standard model meta information object. |
status | body | string | No | Enum active, inactive | Catalog status: active / inactive, default active. |
Output: Returns 201 + the newly created standard model entry (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Call example:
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"
}'Response example: 201: The response is a standard model entry JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
POST /v1/ai-gateway/standard-models/import
Batch-merge model metadata obtained from target discovery (discover) into the standard model catalog: entries with the same ID are merged with the imported data taking precedence.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
providerProfileId | body | string | Yes | — | Provider profile ID. |
profileVersion | body | string | No | — | Provider profile version (optional). |
fetchedAt | body | string | No | — | Upstream fetch time. |
models | body | object[] | Yes | — | Array of discovered models (the result from POST .../targets/{id}/models/discover). |
Output: Returns 200 + the merge result (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
Call example:
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" } ]
}'Response example: 200: The response is a merge result JSON (generalized schema any: the response body is a JSON document of the corresponding resource; specific fields follow the Server SDK type definitions and the actual resource).
PUT /v1/ai-gateway/standard-models/{standardModelId}
Update a standard model entry: change the display name, meta information, or catalog status.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
standardModelId | path | string | Yes | — | Standard model document ID. |
displayName | body | string | No | — | Model display name. |
metadata | body | object | No | — | Standard model meta information object. |
status | body | string | No | Enum active, inactive | Catalog status: active / inactive. |
Output: Returns 200 + the updated entry (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Call example:
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" }'Response example: 200: the response is the updated entry JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
POST /v1/ai-gateway/tool-connections
Create a tool connection: bring an MCP / Tool resource into the gateway context.
Input: no path/query/body parameters (generalized resource endpoint; the payload is determined by the target resource definition).
Output: Returns 201 + the tool connection document (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
MCP Tool listing, search, and invocation share the Agent allowlist and OPA authorization; Tool side effects are protected by an idempotency gate.
Call example:
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 '{ ... 工具连接定义 ... }'Response example: 201: the response is the tool connection JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
POST /v1/ai-gateway/tool-connections/discover
Discover the list of tools available to the tool connection (e.g., tools exposed by an MCP server).
Input: no path/query/body parameters (generalized resource endpoint; the payload is determined by the target resource definition).
Output: Returns 200 + the list of available tools (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Call example:
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 '{ ... 发现语境 ... }'Response example: 200: the response is the tool list JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
PUT /v1/ai-gateway/tool-connections/{id}
Update tool connection configuration.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | Yes | — | Tool connection ID. |
Output: Returns 200 + the updated tool connection (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Call example:
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 '{ ... 连接更新 ... }'Response example: 200: the response is the updated tool connection JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
DELETE /v1/ai-gateway/tool-connections/{id}
Delete a tool connection: the gateway immediately stops allowing tool invocation through this connection.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | Yes | — | Tool connection ID. |
Output: 204 No Content, no response body.
Call example:
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>"Response example: 204 No Content: No response body (deleted).
POST /v1/ai-gateway/tool-connections/{id}/test(2.8.0)
Run a connectivity test and diagnostics on a tool connection (added in 2.8.0): verifies target reachability, credentials, and per-tool status; same source as the Console connection diagnostics panel.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
id | path | string | Yes | — | Tool connection ID. |
Output: Returns 200 + the test and diagnostic results (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Optional body
toolIdtests a single tool only; returns per-tool status and check details (see spec for exact fields).
Call example:
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>"Response example: 200: the response is the connectivity test result JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Observability
GET /v1/ai-gateway/invocations
Paginated query of gateway invocation records: the request, response, policy decision, and usage audit trail of one inference / tool invocation.
Input: no path/query/body parameters.
Output: Returns 200 + the invocation record list (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Call example:
curl "https://<your-endpoint>/v1/ai-gateway/invocations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: the response is the invocation record list JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields) (including request / response / policy decision / usage semantics).
GET /v1/ai-gateway/invocations/{invocationId}
Read the details of a single invocation record.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
invocationId | path | string | Yes | — | Invocation record ID. |
Output: Returns 200 + invocation record details (request / response / policy decision / usage) (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Call example:
curl "https://<your-endpoint>/v1/ai-gateway/invocations/<INVOCATION_ID>" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: the response is the invocation record JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
GET /v1/ai-gateway/metrics/model-deployments
Query metrics by model deployment: aggregated views of call volume, latency, errors, and more.
Input: no path/query/body parameters.
Output: Returns 200 + deployment metrics (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Call example:
curl "https://<your-endpoint>/v1/ai-gateway/metrics/model-deployments" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: the response is the deployment metrics JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
GET /v1/ai-gateway/observability/overview
Query the gateway observability overview: a summary of global invocations and policy hits.
Input: no path/query/body parameters.
Output: Returns 200 + the observability overview (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Call example:
curl "https://<your-endpoint>/v1/ai-gateway/observability/overview" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Response example: the response is the observability overview JSON (generalized schema any: the response body is a JSON document of the corresponding resource; refer to Server SDK type definitions and the actual resource for exact fields).
Errors and boundaries
Resource/gateway/policy engine/sub-key not found:
404; duplicate creation:409; illegal revision state machine transition:409conflict (the legalactionis determined by the current state).The unified resource endpoint uses a generalized schema: invalid request body fields likewise return 400 structure validation failure; construct the payload according to Server SDK type definitions.
For sub-key
allowedTools/allowedAgents, an empty array means deny-all, which differs from omitting the field; pass["*"]explicitly to allow access.Snapshot archival is asynchronous: after
POSTreturns, poll withsnapshots/statusuntil completion; configuration changes after archival are not written back to old snapshots.dry-runonly performs policy evaluation and does not execute the request; actual policy effect on the data plane takes place only when the bundle is published and attached to the gateway policy.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
AIGateway.listResources / createResource / getResource / replaceResource / deleteResource | /ai-gateway/resources/{kind}* |
AIGateway.createRevision / getRevision / transitionRevision | .../revisions* |
AIGateway.testModelDeployment / checkTargetHealth / discoverTargetModels / listTargetMounts / replaceTargetMounts | Resource-specific operation endpoints |
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 | Observability endpoints |