Docs
Contents

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

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}Resource list/create (kind: model-deployments, targets)
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
POST .../resources/targets/{id}/health-checkTarget health check
POST .../resources/targets/{id}/models/discoverDiscover target's available models
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
POST /ai-gateway/standard-models/importBatch 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}/testTest tool connection (2.8.0)
GET .../resources/logical-models/{id}/mountsList logical model mounts (2.8.0)
PUT .../resources/logical-models/{id}/mountsFull replace logical model mounts (2.8.0)
GET /ai-gateway/invocations / GET .../invocations/{invocationId}Invocation records
GET /ai-gateway/metrics/model-deploymentsDeployment metrics
GET /ai-gateway/observability/overviewObservability 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:

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

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:

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

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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—Resource kind: model-deployments / 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:

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:

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—Resource kind: model-deployments / 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:

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:

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

ParameterLocationTypeRequiredDefault/enumDescription
kindpathstringYes—Resource kind: model-deployments / 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:

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:

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:

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:

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:

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:

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

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

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:

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

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:

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)

Read the logical model's mount list: mounts attach the logical model to one or more gateway snapshots (added in 2.8.0).

Input:

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

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:

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

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:

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.

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

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:

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

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:

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

Query the shared standard model catalog: model metadata (display name, status, meta information) reused across resources, with filtering by provider profile and status.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerProfileIdquerystringNoDefault ""Filter by provider profile.
statusquerystringNoEnum '', 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:

ParameterLocationTypeRequiredDefault/enumDescription
providerProfileIdbodystringYes—Provider profile ID.
profileVersionbodystringNo—Provider profile version (optional).
modelIdbodystringYes—Provider model ID.
displayNamebodystringNo—Model display name.
metadatabodyobjectNo—Standard model meta information object.
statusbodystringNoEnum active, inactiveCatalog 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:

ParameterLocationTypeRequiredDefault/enumDescription
providerProfileIdbodystringYes—Provider profile ID.
profileVersionbodystringNo—Provider profile version (optional).
fetchedAtbodystringNo—Upstream fetch time.
modelsbodyobject[]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:

ParameterLocationTypeRequiredDefault/enumDescription
standardModelIdpathstringYes—Standard model document ID.
displayNamebodystringNo—Model display name.
metadatabodyobjectNo—Standard model meta information object.
statusbodystringNoEnum active, inactiveCatalog 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).

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:

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

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

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

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

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