Docs
Contents

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):

Resources and Base Paths

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 + pathPurpose
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}/revisionsCreate revision
GET .../revisions/{revisionId}Read revision
POST .../revisions/{revisionId}/{action}Revision state transition
POST .../resources/model-deployments/{id}/testTest model deployment unavailable in v2.12.0
POST .../resources/targets/{id}/health-checkTarget health check
POST .../resources/targets/{id}/models/discoverDiscover target's available models unavailable in v2.12.0
GET|PUT .../resources/targets/{id}/mountsTarget mount list/full replace
PUT /ai-gateway/gateways/{gatewayId}/policyUpdate gateway policy
POST /ai-gateway/gateways/{gatewayId}/snapshotsSeal snapshot (seal)
GET .../gateways/{gatewayId}/snapshots/statusSnapshot 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-runPolicy dry-run
GET|POST /ai-gateway/keys, GET .../keys/{keyId}, PUT .../keys/{keyId}/statusGateway sub-keys
GET|POST /ai-gateway/standard-modelsStandard model catalog unavailable in v2.12.0
POST /ai-gateway/standard-models/importBatch 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}/testTest tool connection (2.8.0)
GET .../resources/logical-models/{id}/mountsList logical model mounts (2.8.0) unavailable in v2.12.0
PUT .../resources/logical-models/{id}/mountsFull 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-deploymentsDeployment metrics unavailable in v2.12.0
GET /ai-gateway/observability/overviewObservability 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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—Resource kind: targets.
idpathstringyes—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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—Resource kind: targets.
idpathstringyes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—Resource kind: targets.
idpathstringyes—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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—Resource kind: targets.
idpathstringyes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringyes—Resource kind.
idpathstringyes—Resource ID.
revisionIdpathstringyes—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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringyes—Resource kind.
idpathstringyes—Resource ID.
revisionIdpathstringyes—Revision ID.
actionpathstringyes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
idpathstringyes—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:

ParameterLocationTypeRequiredDefault/enumDescription
idpathstringyes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
idpathstringyes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
gatewayIdpathstringyes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
gatewayIdpathstringyes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
gatewayIdpathstringyes—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:

ParameterLocationTypeRequiredDefault/enumDescription
policyEngineIdpathstringyes—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:

ParameterLocationTypeRequiredDefault/enumDescription
policyEngineIdpathstringyes—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:

ParameterLocationTypeRequiredDefault/enumDescription
policyEngineIdpathstringyes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
policyEngineIdpathstringyes—Policy engine ID.
policyBundleIdpathstringYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
policyEngineIdpathstringyes—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).

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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
namebodystringYes—Key name.
gatewayIdsbodystring[]Yes—Array of logical gateway IDs allowed to be called.
regionbodystringNo—Snapshot region: callers nearby use the sealed snapshot in that region.
allowedModelsbodystring[]No—Allowed logical model names; ["*"] allows all models on authorized gateways.
allowedToolsbodystring[]No—Allowed Tool resource IDs; ["*"] allows all, empty array = deny all (different from omitting the field).
allowedAgentsbodystring[]No—Allowed A2A / HTTP Agent Target resource IDs; ["*"] allows all, empty array = deny all.
defaultLogicalModelbodystringNo—Fallback logical model used when the request lacks model.
principalbodyobjectNo—The role and flat claims of the checked-in credential (roles + claims) for the policy engine to evaluate.
limitsbodyobject[]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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
keyIdpathstringYes—Sub-key ID.

Output: Requires aiGateway.write and returns 200 with {"key":"<plaintext credential>"}; key metadata is not included.

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:

ParameterLocationTypeRequiredDefault/enumDescription
keyIdpathstringYes—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:

ParameterLocationTypeRequiredDefault/enumDescription
idpathstringYes—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).

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:

ParameterLocationTypeRequiredDefault/enumDescription
invocationIdpathstringYes—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

Correspondence with the Server SDK

service.methodEndpoint
AIGateway.listResources / createResource / getResource / replaceResource / deleteResource/ai-gateway/resources/{kind}*
AIGateway.createRevision / getRevision / transitionRevision.../revisions*
AIGateway.testModelDeployment / checkTargetHealth / discoverTargetModels / listTargetMounts / replaceTargetMountsResource-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.testToolConnectionPOST /ai-gateway/tool-connections/{id}/test(2.8.0)
AIGateway.listLogicalModelMounts / replaceLogicalModelMountsGET|PUT /ai-gateway/resources/logical-models/{id}/mounts(2.8.0)
AIGateway.listInvocations / getInvocation / getModelDeploymentMetrics / getObservabilityOverviewObservability 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.

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

GET /ai-gateway/approval-requests

Success response: HTTP 200 — any.

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

ParameterLocationRequiredTypeConstraints / defaultMeaning
idpathyesstring—id path parameter.

Success response: HTTP 200 — any.

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

ParameterLocationRequiredTypeConstraints / defaultMeaning
idpathyesstring—id path parameter.

Success response: HTTP 200 — any.

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

ParameterLocationRequiredTypeConstraints / defaultMeaning
idpathyesstring—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.