AI Gateway API
The AI Gateway management plane provides gateways, tool targets, policies, sub-keys, and invocation observability. Use LLM Gateway for model inference.
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):
v2.12.0 model boundary: AI Gateway model inference, logical models, model deployments, model discovery, and standard-model management are unavailable. Use LLM Gateway for model calls. This restriction does not disable the MCP, A2A, or HTTP Agent tool endpoints.
Policy and security boundaries: Use OPA policy dry-run to inspect policy decisions. Semantic response caching is unavailable, and input/output redaction is not guaranteed; remove sensitive data before sending.
Division of labor with LLM Gateway: LLM Gateway API connects model providers and invokes models; AI Gateway manages policies, sub-keys, tool connections, and invocation observability.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1, path prefix/ai-gateway.Resource model: tool Targets use
/ai-gateway/resources/{kind}and revision paths; model resources are disabled.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} | List/create resources (tool targets available; model resources disabled) |
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 unavailable in v2.12.0 |
POST .../resources/targets/{id}/health-check | Target health check |
POST .../resources/targets/{id}/models/discover | Discover target's available models unavailable in v2.12.0 |
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 unavailable in v2.12.0 |
POST /ai-gateway/standard-models/import | Batch import discovered models unavailable in v2.12.0 |
PUT /ai-gateway/standard-models/{standardModelId} | Update standard model unavailable in v2.12.0 |
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) unavailable in v2.12.0 |
PUT .../resources/logical-models/{id}/mounts | Full replace logical model mounts (2.8.0) unavailable in v2.12.0 |
GET /ai-gateway/invocations / GET .../invocations/{invocationId} | Invocation records |
GET /ai-gateway/metrics/model-deployments | Deployment metrics unavailable in v2.12.0 |
GET /ai-gateway/observability/overview | Observability overview |
Endpoint details
Tool Targets can be managed through revisions and gateway snapshots; model resources are unavailable in this version.
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
Version boundary: The generic {kind} endpoints below do not support logical-models, model-deployments, or inference Targets. Tool Targets depend on permissions and configuration.
GET /v1/ai-gateway/resources/{kind}
List with pagination the unified resources of a given kind: targets (tool target).
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | Yes | — | Resource kind: 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:
(
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 @-
)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: 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:
(
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,字段以资源定义为准) ... }'
)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: 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:
(
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 @-
)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: 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:
(
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 '{ ... 完整资源定义文档 ... }'
)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 tool target from the project.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
kind | path | string | Yes | — | Resource kind: targets. |
id | path | string | yes | — | Resource ID. |
Output: 204 No Content, no response body.
Call example:
(
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 @-
)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: 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:
(
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 '{ ... 修订内容 ... }'
)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:
(
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 @-
)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:
(
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 @-
)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
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
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
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
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)
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
PUT /v1/ai-gateway/resources/logical-models/{id}/mounts(2.8.0)
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
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).
Listing metadata requires
aiGateway.read; retrieving an individual plaintext key requiresaiGateway.write.
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.
When allowedModels, allowedTools, or allowedAgents is omitted, each defaults to ["*"]; an explicit empty array denies that type. Wildcards remain subject to the gateway snapshot and policy.
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 plaintext 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_.Callers with
aiGateway.writecan also recover the plaintext through the individual-key endpoint; store it securely and restrict that permission.
Call example:
(
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" } }
}'
)Response example: 201: The response is an issuance result JSON (generalized schema; includes the 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: Requires aiGateway.write and returns 200 with {"key":"<plaintext credential>"}; key metadata is not included.
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 sub-key status. The service attempts to invalidate gateway authentication caches; if invalidation fails, a previously active cached credential may remain valid briefly, and in-flight requests may continue. Verify that actual calls are rejected; a 200 alone does not prove revocation on every node.
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
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
POST /v1/ai-gateway/standard-models
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
POST /v1/ai-gateway/standard-models/import
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
PUT /v1/ai-gateway/standard-models/{standardModelId}
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
POST /v1/ai-gateway/tool-connections
Create a tool connection with aiGateway.write. The request body requires a nonempty name, supported targetKind, matching configuration, and at least one tools entry; slug, description, and catalogSource are optional. The MCP server example below requires a reachable service address and actual tool definition; ensure the network policy permits the connection.
(
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"}]}'
)A successful request returns 201 and the connection's target and tool resources. Tool calls remain subject to mounts, credentials, and policy.
POST /v1/ai-gateway/tool-connections/discover
Discover tools exposed by an MCP server with aiGateway.write. The request body requires endpoint; credentialProviderId and credential are optional, mutually exclusive credential methods. This unauthenticated example requires an actual reachable endpoint.
(
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"}'
)A successful request returns 200 and the discovery result; the upstream service must be reachable and allow the request.
PUT /v1/ai-gateway/tool-connections/{id}
Updating a connection requires aiGateway.write and the complete connection structure used for creation. Read the current configuration first and retain the tools and settings you still need; replace <ID> and use the creation body above as a reference.
DELETE /v1/ai-gateway/tool-connections/{id}
Deletion requires aiGateway.write, the connection ID, and a region query parameter. Disable an active connection first; a missing region or active connection prevents deletion. Replace <REGION> with the actual URL-encoded region:
(
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 @-
)Success returns 204 No Content. Check dependencies before deletion and verify the actual behavior of associated tool calls afterward.
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
v2.12.0: This model-related endpoint is disabled. The historical interface is retained for migration reference; use LLM Gateway for model calls.
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 |
2.12.0 endpoints and compatibility
Paths below are relative to /v1. Server requests carry X-Appwrite-Project and X-Appwrite-Key; keep the key on the server. Scopes below are necessary; dataset access, ownership and resource state may add checks. HTTP 202 means accepted; use the returned operation identifier to read its terminal result.
| 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
Success response: HTTP 200 — any.
GET /ai-gateway/approval-requests/{id}
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
id | path | yes | string | — | id path parameter. |
Success response: HTTP 200 — any.
POST /ai-gateway/approval-requests/{id}/approve
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
id | path | yes | string | — | id path parameter. |
Success response: HTTP 200 — any.
POST /ai-gateway/approval-requests/{id}/reject
| Parameter | Location | Required | Type | Constraints / default | Meaning |
|---|---|---|---|---|---|
id | path | yes | string | — | id path parameter. |
Success response: HTTP 200 — any.
GET /ai-gateway/initialization-status
Success response: HTTP 200 — any.
GET /ai-gateway/tool-embeddings
Success response: HTTP 200 — any.
POST /ai-gateway/tool-embeddings
Success response: HTTP 200 — any.
Errors and retries
400/422: check types, enumerations and rules. 401/403: verify identity and scopes; dataset analyses additionally require trace and dataset read access. 404: check that the resource exists in the current project. 409: read current state before deciding to retry. 429: honor Retry-After. After 5xx or network loss, inspect operation state first. Preserve an idempotency key across retries; change it only for a deliberate new operation. Confirm deletion and clearing targets before writing.