Docs
Contents

LLM Gateway API

Project-scoped LLM gateway data plane and management plane: OpenAI-compatible chat/completions and embeddings, Anthropic Messages-compatible messages, and rerank; upstream provider (openai / anthropic / dashscope / theta) connections, model catalogs, health checks, gateway sub-keys, and platform trial provider bindings.

Service and resource boundaries

The LLM Gateway API (/v1/llm-gateway/*) is the project-wide unified data plane and management plane interface for managed hosting of LLM provider credentials (e.g., displaying the project's configured Alibaba Cloud Bailian dashscope-prod) and for standardized model inference:

Resources and Base Paths

Authentication and Permissions

See Common conventions for authentication and request header conventions. Four scope types:

Data plane rate limiting is independent of the ordinary management plane: chat / messages / rerank 60 requests per minute, embeddings 120 requests per minute. When a provider enables allowByok, callers may bring their own upstream API key via the X-Provider-Key header (BYOK).

Endpoint overview

The LLM Gateway provides 26 endpoints in total, divided into: model inference and vector/rerank data plane (6), provider credential CRUD and health checks/model discovery/preset catalog (10), gateway sub-key management (4), and platform trial provider binding management (6).

Endpoint List

Method + pathPurpose
POST /llm-gateway/chat/completionsChat Completions (OpenAI-compatible)
POST /llm-gateway/messagesMessages (Anthropic-compatible)
POST /llm-gateway/embeddingsText embeddings
POST /llm-gateway/rerankDocument reranking
GET /llm-gateway/models / GET .../models/{modelId}Available model list/details
GET|POST /llm-gateway/providers、GET|PATCH|DELETE .../providers/{providerId}provider CRUD
GET .../providers/{providerId}/healthProvider health
POST .../providers/{providerId}/health-checksValidate all configured provider models
GET .../providers/{providerId}/modelsUpstream actually available models
POST .../providers/cache/refreshRefresh provider cache
POST /llm-gateway/provider-model-discoveriesDiscover and classify models available to DashScope credentials
GET /llm-gateway/provider-presetsVendor preset model catalog (2.9.0: 24 vendors / 313 models, including Base URL and per-model parameters)
GET|POST /llm-gateway/keys, PATCH|DELETE .../keys/{keyId}Gateway sub-key management
GET|POST /llm-gateway/trial-provider-bindings, GET|DELETE .../trial-provider-bindings/{bindingId}, POST .../{bindingId}/health-checksPlatform trial provider bindings and binding health checks
GET /llm-gateway/trial-providersList of bindable platform trial providers

Endpoint details

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.

Data plane

POST /v1/llm-gateway/chat/completions

Create a chat completion in OpenAI Chat Completions-compatible format: the gateway routes to the active Provider based on the request body's model, passes native message fields through, and records usage at the project / model / gateway sub-key three levels.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
modelbodystringYes—Model ID used for the completion; must exactly match a model in an active Provider's model catalog (the provider/model prefix is not supported).
messagesbodyobject[]Yes—Upstream native conversation message array; fields are passed through as-is: text, multimodal (content as an array of segments), and tool-calling (role: tool, tool_calls) are all supported.
temperaturebodynumberNo—Sampling temperature, 0–2; defaults to the upstream default value if omitted.
maxTokensbodyintegerNo—Maximum number of tokens to generate.
streambodybooleanNo—Whether to return as an SSE stream; when true, the response consists of text/event-stream chunks (chat.completion.chunk).
toolsbodyobject[]No—Array of OpenAI-compatible tool definitions (type: function + function.{name,parameters}), passed through to the upstream.
tool_choicebodyobjectNo—Tool choice policy: "auto" / "none" or {"type":"function","function":{"name":"..."}} to force a specific tool.

Output: Returns the upstream native completion (passed through by the gateway): for non-streaming, a complete chat.completion JSON (including choices[].message and usage usage fields); when stream=true, a sequence of SSE chunks. Usage is aggregated per UTC day at the project / model / sub-key levels.

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/chat/completions" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      { "role": "system", "content": "你是一个简洁的中文助手。" },
      { "role": "user", "content": "用一句话介绍 TablesDB。" }
    ],
    "temperature": 0.7,
    "maxTokens": 1024,
    "stream": false
  }'
# Streaming: set stream to true; the response is SSE (data: {"choices":[{"delta":{...}}]} chunks, ending with data: [DONE])

Response example:

{
  "id": "chatcmpl-8f2a9c1d",
  "object": "chat.completion",
  "created": 1757491200,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "TablesDB 是 Agentbase 提供的结构化表格存储服务,支持行级权限与事务。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 33,
    "total_tokens": 61
  }
}

POST /v1/llm-gateway/messages

Creates messages in the Anthropic Messages compatible format: routing prefers anthropic-type Providers, falls back to general model routing when necessary, and returns an Anthropic Messages structure.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
modelbodystringYes—Target model ID; anthropic models are routed preferentially to anthropic Providers.
messagesbodyobject[]Yes—Anthropic native message array (role: user|assistant, where content is a string or an array of segments), passed through as-is.
maxTokensbodyintegerYes—Maximum number of tokens to generate, required; when omitted, the gateway treats it as 1024.
systembodystringNo—System prompt; the gateway prepends it as a system message before passing it through.
temperaturebodynumberNo—Sampling temperature, 0–1.
streambodybooleanNo—Whether to return chunks as an SSE stream.

Output: Returns an Anthropic Messages compatible structure: content[] (segments such as type: text), stop_reason, and usage (input_tokens / output_tokens); for streaming, SSE chunks.

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/messages" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20241022",
    "maxTokens": 1024,
    "system": "你是客服质检助手,只输出 JSON。",
    "messages": [
      { "role": "user", "content": "检查这条回复是否包含承诺赔付的表述。" }
    ],
    "temperature": 0.5,
    "stream": false
  }'
# Gateway Key auth: Authorization: Bearer abk_... (X-Appwrite-Project may be omitted)

Response example:

{
  "id": "msg_01XFDUDYJgAACzvnptvVoaEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-3-5-sonnet-20241022",
  "content": [
    {
      "type": "text",
      "text": "{\"contains_compensation\": false, \"confidence\": 0.92}"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 42,
    "output_tokens": 28
  }
}

POST /v1/llm-gateway/embeddings

Generates vectors for a batch of texts: routes to an active Provider by embedding model ID and returns an OpenAI-compatible vector array with token usage. Streaming is not supported.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
modelbodystringYes—embedding model ID, must be in the Provider's embeddingModels.
inputbodystring[]Yes—Array of input texts; each element generates one vector; result data[].index corresponds to the array order.

Output: Returns llmGatewayEmbeddingResponse:

FieldTypeDescription
objectstringObject type, always list (OpenAI-compatible field).
modelstringThe model that actually generated the vectors.
dataobject[]Array of vector objects, each containing object, index, and a embedding float array, in one-to-one correspondence with input.
usageobjectToken usage: prompt_tokens / total_tokens.

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/embeddings" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-3-small",
    "input": [
      "Agentbase 是一个 BaaS 平台",
      "TablesDB 提供结构化数据存储"
    ]
  }'

Response example:

{
  "object": "list",
  "model": "text-embedding-3-small",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [
        0.0023,
        -0.0091,
        0.0154
      ]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [
        0.0031,
        -0.0087,
        0.0149
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "total_tokens": 24
  }
}

POST /v1/llm-gateway/rerank

Reranks candidate documents by query relevance: returns input indices and scores in descending relevance order, optionally with the document text. Streaming is not supported.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
modelbodystringYes—rerank model ID, must be in the Provider's rerankModels.
querybodystringYes—Query text used for relevance judgment.
documentsbodystring[]Yes—Array of candidate document texts; the index in the results points to indices of this array.
topNbodyintegerNo—Return only the top N results.
returnDocumentsbodybooleanNo—Whether to include the document text (document field) in the results.

Output: Returns llmGatewayRerankResponse:

FieldTypeDescription
modelstringThe model that performed the rerank.
resultsobject[]Array of results in descending relevance order, each containing index (index into the input documents) and relevance_score (0–1); when returnDocuments=true, the document text is included.
usageobjectToken usage: total_tokens.

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/rerank" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gte-rerank",
    "query": "如何创建 Agentbase 用户",
    "documents": [
      "使用 Account API 创建邮箱密码用户。",
      "TablesDB 提供结构化数据存储。"
    ],
    "topN": 2,
    "returnDocuments": false
  }'

Response example:

{
  "model": "gte-rerank",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.97
    },
    {
      "index": 1,
      "relevance_score": 0.31
    }
  ],
  "usage": {
    "total_tokens": 45
  }
}

GET /v1/llm-gateway/models

Lists all currently routable models in the project: aggregates and deduplicates chatModels / embeddingModels / rerankModels / vlmModels across active Providers.

Input: no path/query/body parameters.

Output: Returns llmGatewayModelList (total + models[]), where array elements are llmGatewayModel:

FieldTypeDescription
$idstringModel ID (the value that must be matched exactly by the request body's model).
objectstringObject type, always model (OpenAI-compatible field).
createdintegerUpstream model creation time (Unix seconds).
ownedBystringOwning Provider (type or connection identifier).
capabilitiesstring[]Supported capabilities: chat / embedding / rerank / vlm.
activebooleanWhether currently routable (the Provider must be active).
sourcestring, optionalModel source: project (project Provider) / platformTrial (platform trial) / mixed.
sourcesobject[], optionalList of sanitized source projections.
trialQuotaobject, optionalWhen a platform trial source exists, the trial quota at the account-model dimension.

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/models" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 2,
  "models": [
    {
      "$id": "gpt-4o-mini",
      "object": "model",
      "created": 1721174400,
      "ownedBy": "openai",
      "capabilities": [
        "chat"
      ],
      "active": true,
      "source": "project",
      "sources": [
        "project"
      ]
    },
    {
      "$id": "gte-rerank",
      "object": "model",
      "created": 1719043200,
      "ownedBy": "dashscope",
      "capabilities": [
        "rerank"
      ],
      "active": true,
      "source": "platformTrial",
      "sources": [
        "platformTrial"
      ],
      "trialQuota": {
        "remainingTokens": 480000
      }
    }
  ]
}

GET /v1/llm-gateway/models/{modelId}

Reads details of a single available model; the model must be explicitly declared by an active Provider or matched via wildcard routing.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
modelIdpathstringYes—Model ID, identical to the $id returned by the list endpoint.

Output: Returns llmGatewayModel:

FieldTypeDescription
$idstringModel ID (the value that must be matched exactly by the request body's model).
objectstringObject type, always model (OpenAI-compatible field).
createdintegerUpstream model creation time (Unix seconds).
ownedBystringOwning Provider (type or connection identifier).
capabilitiesstring[]Supported capabilities: chat / embedding / rerank / vlm.
activebooleanWhether currently routable (the Provider must be active).
sourcestring, optionalModel source: project (project Provider) / platformTrial (platform trial) / mixed.
sourcesobject[], optionalList of sanitized source projections.
trialQuotaobject, optionalWhen a platform trial source exists, the trial quota at the account-model dimension.

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/models/gpt-4o-mini" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "gpt-4o-mini",
  "object": "model",
  "created": 1721174400,
  "ownedBy": "openai",
  "capabilities": [
    "chat"
  ],
  "active": true,
  "source": "project",
  "sources": [
    "project"
  ]
}

Provider management

GET /v1/llm-gateway/providers

Lists all Provider connections in the project: sorted by routing priority, used to inspect configured upstreams, model inventories, status, and health.

Input: no path/query/body parameters.

Output: Returns llmGatewayProviderList (total + providers[]), with elements of llmGatewayProvider:

FieldTypeDescription
$idstringProvider ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
connectionNamestringConnection name, unique within the project.
providerTypestringUpstream type: openai / anthropic / dashscope / theta.
baseUrlstringUpstream API base URL.
apiKeySetbooleanWhether an upstream key has been configured; responses never echo the apiKey itself.
defaultModelstringDefault model for this connection.
allowedCapabilitiesstring[]Allowed capabilities: chat / embedding / rerank / vlm (derived from each model inventory).
supportedModelsstring[]Compatibility field: aggregated list of all supported model IDs (server-derived).
chatModelsstring[]Model IDs available for chat completions.
embeddingModelsstring[]Model IDs available for embeddings.
rerankModelsstring[]Model IDs available for rerank.
vlmModelsstring[]Model IDs available for vision understanding (reuses the chat completions endpoint).
descriptionstringConnection description.
statusstringRuntime status: active / paused.
isDefaultbooleanWhether this is the default Provider for its type.
priorityintegerFailover priority; lower values take precedence.
timeoutMsintegerUpstream request timeout (milliseconds).
maxRetriesintegerMaximum number of retries.
maxInputTokensintegerMaximum input tokens; null means unlimited.
allowByokbooleanWhether callers may supply their own upstream key via the X-Provider-Key header (BYOK).
healthStatusstringHealth status: HEALTHY / UNHEALTHY / UNKNOWN.
healthMessagestringSummary of the most recent model validation failure.
lastValidatedAtstringTime of the most recent health check.
lastUsedAtstringTime of the most recent routing use.
memoryEmbeddingReferencedbooleanWhether it is already referenced by the project's Memory embedding configuration; null means the constraint was not evaluated in this response.
immutableFieldsstring[]List of fields that cannot be modified while referenced by Memory.
deleteAllowedbooleanWhether deletion is currently allowed; null means not evaluated.
credentialPolicystringCredential rotation policy: mutable / rotate-only; empty means not evaluated.

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/providers" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "providers": [
    {
      "$id": "openai-prod",
      "$createdAt": "2026-08-01T03:12:45.231+00:00",
      "$updatedAt": "2026-08-01T03:12:45.231+00:00",
      "connectionName": "openai-production",
      "providerType": "openai",
      "baseUrl": "https://api.openai.com",
      "apiKeySet": true,
      "defaultModel": "gpt-4o-mini",
      "allowedCapabilities": [
        "chat",
        "embedding"
      ],
      "supportedModels": [
        "gpt-4o-mini",
        "text-embedding-3-small"
      ],
      "chatModels": [
        "gpt-4o-mini"
      ],
      "embeddingModels": [
        "text-embedding-3-small"
      ],
      "rerankModels": [],
      "vlmModels": [],
      "description": "生产 OpenAI 连接",
      "status": "active",
      "isDefault": true,
      "priority": 0,
      "timeoutMs": 60000,
      "maxRetries": 3,
      "maxInputTokens": 128000,
      "allowByok": false,
      "healthStatus": "HEALTHY",
      "healthMessage": "",
      "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
      "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
      "memoryEmbeddingReferenced": false,
      "immutableFields": [],
      "deleteAllowed": true,
      "credentialPolicy": "mutable"
    }
  ]
}

POST /v1/llm-gateway/providers

Create a Provider connection: it is recommended to declare the available models for each capability using the four capability model lists; the server derives allowedCapabilities and the compatibility field supportedModels, and verifies all models one by one before saving.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdbodystringYes—Provider ID, custom or ID.unique().
connectionNamebodystringYes—Connection name, unique within the project; duplicate creation returns 409.
providerTypebodystringYesEnum openai, anthropic, dashscope, thetaUpstream type enum: openai / anthropic / dashscope / theta.
baseUrlbodystringYes—Upstream API base URL, must be a valid HTTP(S) address.
apiKeybodystringNo—Upstream key or token; stored encrypted, any read endpoint only echoes apiKeySet and never returns the original.
defaultModelbodystringNo—Default model for this connection.
allowedCapabilitiesbodystring[]No—Allowed capability array; usually omitted, derived from the four model lists.
supportedModelsbodystring[]No—Field for backward compatibility with old clients; when passed together with the four lists, the list-derived result takes precedence. The * wildcard is not accepted.
chatModelsbodystring[]No—chat capability model list; VLM reuses the chat completions endpoint, vision models are registered in vlmModels.
embeddingModelsbodystring[]No—embedding capability model list.
rerankModelsbodystring[]No—rerank capability model list.
vlmModelsbodystring[]No—Vision-language model list.
chatCompletionsPathbodystringNo—Upstream chat completions path override, default /v1/chat/completions.
embeddingsPathbodystringNo—Upstream embeddings path override, default /v1/embeddings.
rerankPathbodystringNo—Upstream rerank path override; empty means the Provider does not support rerank.
descriptionbodystringNo—Provider connection description.
isDefaultbodybooleanNo—Set as the default Provider of its type.
isActivebodybooleanNo—Whether the connection participates in routing immediately after creation.
timeoutMsbodyintegerNo—Upstream request timeout (milliseconds).
maxRetriesbodyintegerNo—Maximum number of retries.
prioritybodyintegerNo—Failover priority, lower is tried first; tried in ascending order when the primary Provider fails.
maxInputTokensbodyintegerNo—Maximum input tokens; null means unlimited.
allowByokbodybooleanNo—Allow callers to supply their own upstream key via the X-Provider-Key header.

output : returns 201 + llmGatewayProvider:

FieldTypeDescription
$idstringProvider ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
connectionNamestringConnection name, unique within the project.
providerTypestringUpstream type: openai / anthropic / dashscope / theta.
baseUrlstringUpstream API base URL.
apiKeySetbooleanWhether an upstream key has been configured; responses never echo the apiKey itself.
defaultModelstringDefault model for this connection.
allowedCapabilitiesstring[]Allowed capabilities: chat / embedding / rerank / vlm (derived from each model inventory).
supportedModelsstring[]Compatibility field: aggregated list of all supported model IDs (server-derived).
chatModelsstring[]Model IDs available for chat completions.
embeddingModelsstring[]Model IDs available for embeddings.
rerankModelsstring[]Model IDs available for rerank.
vlmModelsstring[]Model IDs available for vision understanding (reuses the chat completions endpoint).
descriptionstringConnection description.
statusstringRuntime status: active / paused.
isDefaultbooleanWhether this is the default Provider for its type.
priorityintegerFailover priority; lower values take precedence.
timeoutMsintegerUpstream request timeout (milliseconds).
maxRetriesintegerMaximum number of retries.
maxInputTokensintegerMaximum input tokens; null means unlimited.
allowByokbooleanWhether callers may supply their own upstream key via the X-Provider-Key header (BYOK).
healthStatusstringHealth status: HEALTHY / UNHEALTHY / UNKNOWN.
healthMessagestringSummary of the most recent model validation failure.
lastValidatedAtstringTime of the most recent health check.
lastUsedAtstringTime of the most recent routing use.
memoryEmbeddingReferencedbooleanWhether it is already referenced by the project's Memory embedding configuration; null means the constraint was not evaluated in this response.
immutableFieldsstring[]List of fields that cannot be modified while referenced by Memory.
deleteAllowedbooleanWhether deletion is currently allowed; null means not evaluated.
credentialPolicystringCredential rotation policy: mutable / rotate-only; empty means not evaluated.

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "providerId": "openai-prod",
    "connectionName": "openai-production",
    "providerType": "openai",
    "baseUrl": "https://api.openai.com",
    "apiKey": "sk-xxxxxxxxxxxxxxxx",
    "defaultModel": "gpt-4o-mini",
    "chatModels": ["gpt-4o-mini"],
    "embeddingModels": ["text-embedding-3-small"],
    "priority": 0,
    "timeoutMs": 60000,
    "maxRetries": 3,
    "isActive": true,
    "description": "生产 OpenAI 连接"
  }'

Response example:

{
  "$id": "openai-prod",
  "$createdAt": "2026-08-01T03:12:45.231+00:00",
  "$updatedAt": "2026-08-01T03:12:45.231+00:00",
  "connectionName": "openai-production",
  "providerType": "openai",
  "baseUrl": "https://api.openai.com",
  "apiKeySet": true,
  "defaultModel": "gpt-4o-mini",
  "allowedCapabilities": [
    "chat",
    "embedding"
  ],
  "supportedModels": [
    "gpt-4o-mini",
    "text-embedding-3-small"
  ],
  "chatModels": [
    "gpt-4o-mini"
  ],
  "embeddingModels": [
    "text-embedding-3-small"
  ],
  "rerankModels": [],
  "vlmModels": [],
  "description": "生产 OpenAI 连接",
  "status": "active",
  "isDefault": true,
  "priority": 0,
  "timeoutMs": 60000,
  "maxRetries": 3,
  "maxInputTokens": 128000,
  "allowByok": false,
  "healthStatus": "HEALTHY",
  "healthMessage": "",
  "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
  "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
  "memoryEmbeddingReferenced": false,
  "immutableFields": [],
  "deleteAllowed": true,
  "credentialPolicy": "mutable"
}

GET /v1/llm-gateway/providers/{providerId}

Read a single Provider by ID: returns the routing configuration and health metadata, never exposing the upstream key in plaintext.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdpathstringYes—Provider ID.

Output: Returns llmGatewayProvider:

FieldTypeDescription
$idstringProvider ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
connectionNamestringConnection name, unique within the project.
providerTypestringUpstream type: openai / anthropic / dashscope / theta.
baseUrlstringUpstream API base URL.
apiKeySetbooleanWhether an upstream key has been configured; responses never echo the apiKey itself.
defaultModelstringDefault model for this connection.
allowedCapabilitiesstring[]Allowed capabilities: chat / embedding / rerank / vlm (derived from each model inventory).
supportedModelsstring[]Compatibility field: aggregated list of all supported model IDs (server-derived).
chatModelsstring[]Model IDs available for chat completions.
embeddingModelsstring[]Model IDs available for embeddings.
rerankModelsstring[]Model IDs available for rerank.
vlmModelsstring[]Model IDs available for vision understanding (reuses the chat completions endpoint).
descriptionstringConnection description.
statusstringRuntime status: active / paused.
isDefaultbooleanWhether this is the default Provider for its type.
priorityintegerFailover priority; lower values take precedence.
timeoutMsintegerUpstream request timeout (milliseconds).
maxRetriesintegerMaximum number of retries.
maxInputTokensintegerMaximum input tokens; null means unlimited.
allowByokbooleanWhether callers may supply their own upstream key via the X-Provider-Key header (BYOK).
healthStatusstringHealth status: HEALTHY / UNHEALTHY / UNKNOWN.
healthMessagestringSummary of the most recent model validation failure.
lastValidatedAtstringTime of the most recent health check.
lastUsedAtstringTime of the most recent routing use.
memoryEmbeddingReferencedbooleanWhether it is already referenced by the project's Memory embedding configuration; null means the constraint was not evaluated in this response.
immutableFieldsstring[]List of fields that cannot be modified while referenced by Memory.
deleteAllowedbooleanWhether deletion is currently allowed; null means not evaluated.
credentialPolicystringCredential rotation policy: mutable / rotate-only; empty means not evaluated.

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "openai-prod",
  "$createdAt": "2026-08-01T03:12:45.231+00:00",
  "$updatedAt": "2026-08-01T03:12:45.231+00:00",
  "connectionName": "openai-production",
  "providerType": "openai",
  "baseUrl": "https://api.openai.com",
  "apiKeySet": true,
  "defaultModel": "gpt-4o-mini",
  "allowedCapabilities": [
    "chat",
    "embedding"
  ],
  "supportedModels": [
    "gpt-4o-mini",
    "text-embedding-3-small"
  ],
  "chatModels": [
    "gpt-4o-mini"
  ],
  "embeddingModels": [
    "text-embedding-3-small"
  ],
  "rerankModels": [],
  "vlmModels": [],
  "description": "生产 OpenAI 连接",
  "status": "active",
  "isDefault": true,
  "priority": 0,
  "timeoutMs": 60000,
  "maxRetries": 3,
  "maxInputTokens": 128000,
  "allowByok": false,
  "healthStatus": "HEALTHY",
  "healthMessage": "",
  "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
  "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
  "memoryEmbeddingReferenced": false,
  "immutableFields": [],
  "deleteAllowed": true,
  "credentialPolicy": "mutable"
}

PATCH /v1/llm-gateway/providers/{providerId}

Update a Provider: only explicitly passed fields are modified; capability model lists can be updated independently, and the server re-derives allowedCapabilities and supportedModels.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdpathstringYes—Provider ID.
connectionNamebodystringNo—Connection name (uniqueness check same as creation).
providerTypebodystringNoEnum openai, anthropic, dashscope, thetaUpstream type; when only the type is changed, explicit custom paths are kept, and if rerankPath equals the old type's built-in default it migrates to the new type's default.
baseUrlbodystringNo—Upstream base URL.
apiKeybodystringNo—Pass an empty string to clear the stored key; omitting the field keeps the existing key unchanged.
defaultModelbodystringNo—Default model.
allowedCapabilitiesbodystring[]No—Compatibility field, generally not passed directly.
supportedModelsbodystring[]No—When only the legacy field is passed, legacy compatibility semantics apply.
chatModelsbodystring[]No—When updating the chat list alone, the other three capability lists remain unchanged.
embeddingModelsbodystring[]No—Update the embedding list alone.
rerankModelsbodystring[]No—Update the rerank list alone.
vlmModelsbodystring[]No—Update the VLM list alone.
chatCompletionsPathbodystringNo—chat completions path override.
embeddingsPathbodystringNo—embeddings path override.
rerankPathbodystringNo—rerank path override.
descriptionbodystringNo—Connection description.
isDefaultbodybooleanNo—Set as the default of its type.
isActivebodybooleanNo—false removes the Provider from routing.
timeoutMsbodyintegerNo—Upstream timeout (milliseconds).
maxRetriesbodyintegerNo—Maximum number of retries.
prioritybodyintegerNo—Failover priority.
maxInputTokensbodyintegerNo—Maximum input tokens.
allowByokbodybooleanNo—Whether BYOK is allowed.

Output: Returns the updated llmGatewayProvider:

FieldTypeDescription
$idstringProvider ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
connectionNamestringConnection name, unique within the project.
providerTypestringUpstream type: openai / anthropic / dashscope / theta.
baseUrlstringUpstream API base URL.
apiKeySetbooleanWhether an upstream key has been configured; responses never echo the apiKey itself.
defaultModelstringDefault model for this connection.
allowedCapabilitiesstring[]Allowed capabilities: chat / embedding / rerank / vlm (derived from each model inventory).
supportedModelsstring[]Compatibility field: aggregated list of all supported model IDs (server-derived).
chatModelsstring[]Model IDs available for chat completions.
embeddingModelsstring[]Model IDs available for embeddings.
rerankModelsstring[]Model IDs available for rerank.
vlmModelsstring[]Model IDs available for vision understanding (reuses the chat completions endpoint).
descriptionstringConnection description.
statusstringRuntime status: active / paused.
isDefaultbooleanWhether this is the default Provider for its type.
priorityintegerFailover priority; lower values take precedence.
timeoutMsintegerUpstream request timeout (milliseconds).
maxRetriesintegerMaximum number of retries.
maxInputTokensintegerMaximum input tokens; null means unlimited.
allowByokbooleanWhether callers may supply their own upstream key via the X-Provider-Key header (BYOK).
healthStatusstringHealth status: HEALTHY / UNHEALTHY / UNKNOWN.
healthMessagestringSummary of the most recent model validation failure.
lastValidatedAtstringTime of the most recent health check.
lastUsedAtstringTime of the most recent routing use.
memoryEmbeddingReferencedbooleanWhether it is already referenced by the project's Memory embedding configuration; null means the constraint was not evaluated in this response.
immutableFieldsstring[]List of fields that cannot be modified while referenced by Memory.
deleteAllowedbooleanWhether deletion is currently allowed; null means not evaluated.
credentialPolicystringCredential rotation policy: mutable / rotate-only; empty means not evaluated.

Call example:

curl -X PATCH "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "priority": 10,
    "timeoutMs": 30000,
    "maxRetries": 2
  }'

Response example:

{
  "$id": "openai-prod",
  "$createdAt": "2026-08-01T03:12:45.231+00:00",
  "$updatedAt": "2026-08-01T03:12:45.231+00:00",
  "connectionName": "openai-production",
  "providerType": "openai",
  "baseUrl": "https://api.openai.com",
  "apiKeySet": true,
  "defaultModel": "gpt-4o-mini",
  "allowedCapabilities": [
    "chat",
    "embedding"
  ],
  "supportedModels": [
    "gpt-4o-mini",
    "text-embedding-3-small"
  ],
  "chatModels": [
    "gpt-4o-mini"
  ],
  "embeddingModels": [
    "text-embedding-3-small"
  ],
  "rerankModels": [],
  "vlmModels": [],
  "description": "生产 OpenAI 连接",
  "status": "active",
  "isDefault": true,
  "priority": 0,
  "timeoutMs": 60000,
  "maxRetries": 3,
  "maxInputTokens": 128000,
  "allowByok": false,
  "healthStatus": "HEALTHY",
  "healthMessage": "",
  "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
  "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
  "memoryEmbeddingReferenced": false,
  "immutableFields": [],
  "deleteAllowed": true,
  "credentialPolicy": "mutable"
}

DELETE /v1/llm-gateway/providers/{providerId}

Delete a Provider connection: removes it from routing, after which it no longer serves model requests for the project.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdpathstringYes—Provider ID.

Output: 204 No Content, no response body.

Call example:

curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

response example : 204 No Content: no response body (deletion succeeded).

GET /v1/llm-gateway/providers/{providerId}/health

Run live validation on all (能力, 模型) combinations of the Provider and update health status; compatibility interface, still returns the latest Provider object.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdpathstringYes—Provider ID.

output : returns llmGatewayProvider carrying the latest health status (see healthStatus / healthMessage / lastValidatedAt):

FieldTypeDescription
$idstringProvider ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
connectionNamestringConnection name, unique within the project.
providerTypestringUpstream type: openai / anthropic / dashscope / theta.
baseUrlstringUpstream API base URL.
apiKeySetbooleanWhether an upstream key has been configured; responses never echo the apiKey itself.
defaultModelstringDefault model for this connection.
allowedCapabilitiesstring[]Allowed capabilities: chat / embedding / rerank / vlm (derived from each model inventory).
supportedModelsstring[]Compatibility field: aggregated list of all supported model IDs (server-derived).
chatModelsstring[]Model IDs available for chat completions.
embeddingModelsstring[]Model IDs available for embeddings.
rerankModelsstring[]Model IDs available for rerank.
vlmModelsstring[]Model IDs available for vision understanding (reuses the chat completions endpoint).
descriptionstringConnection description.
statusstringRuntime status: active / paused.
isDefaultbooleanWhether this is the default Provider for its type.
priorityintegerFailover priority; lower values take precedence.
timeoutMsintegerUpstream request timeout (milliseconds).
maxRetriesintegerMaximum number of retries.
maxInputTokensintegerMaximum input tokens; null means unlimited.
allowByokbooleanWhether callers may supply their own upstream key via the X-Provider-Key header (BYOK).
healthStatusstringHealth status: HEALTHY / UNHEALTHY / UNKNOWN.
healthMessagestringSummary of the most recent model validation failure.
lastValidatedAtstringTime of the most recent health check.
lastUsedAtstringTime of the most recent routing use.
memoryEmbeddingReferencedbooleanWhether it is already referenced by the project's Memory embedding configuration; null means the constraint was not evaluated in this response.
immutableFieldsstring[]List of fields that cannot be modified while referenced by Memory.
deleteAllowedbooleanWhether deletion is currently allowed; null means not evaluated.
credentialPolicystringCredential rotation policy: mutable / rotate-only; empty means not evaluated.

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/health" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "$id": "openai-prod",
  "$createdAt": "2026-08-01T03:12:45.231+00:00",
  "$updatedAt": "2026-08-01T03:12:45.231+00:00",
  "connectionName": "openai-production",
  "providerType": "openai",
  "baseUrl": "https://api.openai.com",
  "apiKeySet": true,
  "defaultModel": "gpt-4o-mini",
  "allowedCapabilities": [
    "chat",
    "embedding"
  ],
  "supportedModels": [
    "gpt-4o-mini",
    "text-embedding-3-small"
  ],
  "chatModels": [
    "gpt-4o-mini"
  ],
  "embeddingModels": [
    "text-embedding-3-small"
  ],
  "rerankModels": [],
  "vlmModels": [],
  "description": "生产 OpenAI 连接",
  "status": "active",
  "isDefault": true,
  "priority": 0,
  "timeoutMs": 60000,
  "maxRetries": 3,
  "maxInputTokens": 128000,
  "allowByok": false,
  "healthStatus": "UNHEALTHY",
  "healthMessage": "Model validation failed: 1 invalid, 0 unavailable, 0 skipped.",
  "lastValidatedAt": "2026-09-14T02:00:11.400+00:00",
  "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
  "memoryEmbeddingReferenced": false,
  "immutableFields": [],
  "deleteAllowed": true,
  "credentialPolicy": "mutable"
}

POST /v1/llm-gateway/providers/{providerId}/health-checks

Run a unified validity check on all configured models of the Provider, returning the Provider, summary statistics, and per-model results; health fields are written back via sparse update.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdpathstringYes—Provider ID.

Output: Returns llmGatewayProviderHealthCheck:

FieldTypeDescription
providerobjectProvider object carrying the latest persisted health status (fields same as llmGatewayProvider, see the Provider management section, not repeated here).
summaryobjectValidation summary (fields below).
summary.totalintegerTotal number of validation results.
summary.validintegerNumber of validations passed.
summary.invalidintegerNumber of validation failures (invalid configuration).
summary.unavailableintegerNumber of models whose upstream is temporarily unavailable.
summary.skippedintegerNumber skipped.
summary.durationMsintegerTotal batch validation time (milliseconds).
resultsllmGatewayProviderValidationResult[]Validation result per (capability, model) (fields below).
results[].capabilitystringThe capability this validation targets.
results[].modelstringThe model ID being validated.
results[].statusstringResult: valid / invalid / unavailable / skipped.
results[].codestringStable machine-readable result code (e.g. ok).
results[].retryablebooleanWhether retrying later without configuration changes could succeed.
results[].latencyMsintegerDuration of a single probe (milliseconds).

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/health-checks" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "provider": {
    "$id": "openai-prod",
    "$createdAt": "2026-08-01T03:12:45.231+00:00",
    "$updatedAt": "2026-08-01T03:12:45.231+00:00",
    "connectionName": "openai-production",
    "providerType": "openai",
    "baseUrl": "https://api.openai.com",
    "apiKeySet": true,
    "defaultModel": "gpt-4o-mini",
    "allowedCapabilities": [
      "chat",
      "embedding"
    ],
    "supportedModels": [
      "gpt-4o-mini",
      "text-embedding-3-small"
    ],
    "chatModels": [
      "gpt-4o-mini"
    ],
    "embeddingModels": [
      "text-embedding-3-small"
    ],
    "rerankModels": [],
    "vlmModels": [],
    "description": "生产 OpenAI 连接",
    "status": "active",
    "isDefault": true,
    "priority": 0,
    "timeoutMs": 60000,
    "maxRetries": 3,
    "maxInputTokens": 128000,
    "allowByok": false,
    "healthStatus": "HEALTHY",
    "healthMessage": "",
    "lastValidatedAt": "2026-08-01T03:13:02.884+00:00",
    "lastUsedAt": "2026-09-01T08:00:11.102+00:00",
    "memoryEmbeddingReferenced": false,
    "immutableFields": [],
    "deleteAllowed": true,
    "credentialPolicy": "mutable"
  },
  "summary": {
    "total": 2,
    "valid": 1,
    "invalid": 1,
    "unavailable": 0,
    "skipped": 0,
    "durationMs": 256
  },
  "results": [
    {
      "capability": "chat",
      "model": "gpt-4o-mini",
      "status": "valid",
      "code": "ok",
      "retryable": false,
      "latencyMs": 128
    },
    {
      "capability": "embedding",
      "model": "text-embedding-3-small",
      "status": "invalid",
      "code": "model_not_allowed",
      "retryable": false,
      "latencyMs": 94
    }
  ]
}

GET /v1/llm-gateway/providers/{providerId}/models

Pull the actually available model list directly from the upstream (model discovery): currently for the dashscope Provider; other compatible types require manual maintenance of the model list.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdpathstringYes—Provider ID.

Output: returns plain-ID-shaped { "models": string[], "total": number } (not an array of llmGatewayModel objects).

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/providers/openai-prod/models" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "models": [
    "qwen-plus",
    "qwen-max",
    "text-embedding-v3"
  ],
  "total": 3
}

POST /v1/llm-gateway/providers/cache/refresh

Force-reload the current project's in-memory Provider routing cache: after batch Provider changes, make the new routing snapshot take effect immediately on the current Worker.

Input: no path/query/body parameters.

Output: 204 No Content, no response body.

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/providers/cache/refresh" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example: 204 No Content: no response body (cache refreshed).

POST /v1/llm-gateway/provider-model-discoveries

Use Bailian DashScope credentials to pull the account's available models, and pre-classify them via the built-in model catalog as Chat / Embedding / Rerank / VLM for use when creating or editing a Provider.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdbodystringNo—Existing Provider ID; used in the edit context to reuse saved credentials.
providerTypebodystringNoEnum openai, anthropic, dashscope, thetaUsed in the create context (required when providerId is absent); the enum matches the Provider.
baseUrlbodystringNo—When non-empty, overrides the saved Provider's base URL.
apiKeybodystringNo—When non-empty, overrides the saved Provider's key.

Output: returns the discovery result: a model list pre-classified by chat / embedding / rerank / vlm plus an unclassified preview.

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/provider-model-discoveries" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "providerType": "dashscope",
    "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode",
    "apiKey": "sk-xxxxxxxxxxxxxxxx"
  }'

Response example: the response is a discovery-result JSON (model list pre-classified by capability + unclassified preview; fields are subject to the actual response): for preview only; nothing is written to any Provider automatically.

GET /v1/llm-gateway/provider-presets (added in 2.9.0)

Vendor preset model catalog: returns the built-in vendor preset list (24 vendors, 313 preset models) and per-model parameters (context window, max output, Embedding dimensions and input limit, tool calling, multimodal Embedding) for each model, for selecting vendor presets and importing model lists when creating / editing a Provider.

Input: no path/query/body parameters.

Output: Returns llmGatewayProviderPresetList (total + presets[]), with elements of llmGatewayProviderPreset:

FieldTypeDescription
providerTypestringThe Provider type the preset corresponds to (e.g. volcengine, openai-official, openai-compatible, ollama, etc.).
name / descriptionstringVendor display name and description.
baseUrlstringThe upstream Base URL fixed by the preset.
modelsarrayThe preset model list (llmGatewayProviderPresetModel: model ID, capability annotations, and per-model parameters metadata).

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/provider-presets" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 24,
  "presets": [
    {
      "providerType": "volcengine",
      "name": "火山方舟(豆包)",
      "baseUrl": "https://ark.cn-beijing.volces.com/api/v3",
      "models": [
        {
          "model": "doubao-seed-2-1-pro-260915",
          "capabilities": ["chat", "vlm"],
          "metadata": { "contextWindow": 262144 }
        }
      ]
    }
  ]
}

Gateway Sub-keys

GET /v1/llm-gateway/keys

List the gateway sub-keys of the current project: plaintext is never returned; keys are identified by keyPrefix, name, enabled/disabled state, expiry time, and last used time.

Input: no path/query/body parameters.

Output: returns llmGatewayKeyList (total + keys[]), whose elements are llmGatewayKey (where key plaintext is always empty / not echoed back):

FieldTypeDescription
$idstringKey ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
keystringThe full plaintext key (abk_ prefix), appearing only once in the creation response; afterwards no read endpoint returns it again.
keyPrefixstringThe key's display prefix (non-sensitive), used to identify the key in lists.
namestringKey name.
descriptionstringKey description.
allowedModelsstring[]Allowlist of model IDs permitted for calls; ["*"] allows all models.
monthlyTokenBudgetintegerMonthly token budget; null means unlimited. Rolled up cumulatively from tiered usage data aggregated by UTC day; once exhausted, requests with this key are rejected.
monthlyTokensUsedintegerTokens consumed in the current billing cycle.
budgetResetAtstringNext monthly budget reset time.
rateLimitintegerPer-minute request limit; null uses the project-level default rate limit.
isActivebooleanWhether enabled; when false, the key becomes immediately unavailable.
expiresAtstringExpiry time (ISO 8601); null means never expires.
lastUsedAtstringLast used time.

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/keys" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example:

{
  "total": 1,
  "keys": [
    {
      "$id": "key_mobile_chat",
      "$createdAt": "2026-08-12T09:20:00.000+00:00",
      "$updatedAt": "2026-08-12T09:20:00.000+00:00",
      "key": "",
      "keyPrefix": "abk_proj6789_aB3xK9",
      "name": "mobile-app-chat",
      "description": "移动端聊天功能专用",
      "allowedModels": [
        "gpt-4o-mini"
      ],
      "monthlyTokenBudget": 1000000,
      "monthlyTokensUsed": 45230,
      "budgetResetAt": "2026-09-01T00:00:00.000+00:00",
      "rateLimit": 60,
      "isActive": true,
      "expiresAt": null,
      "lastUsedAt": "2026-09-10T14:02:33.000+00:00"
    }
  ]
}

POST /v1/llm-gateway/keys

Issue a gateway sub-key: a restricted credential for downstream applications that can only call data-plane endpoints, constrained by allowedModels / budget / rate limit / validity period.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
keyIdbodystringYes—Sub-key ID, custom or ID.unique().
namebodystringYes—Key name.
descriptionbodystringNo—Key description.
allowedModelsbodystring[]No—Model allowlist; ["*"] allows all. If the requested model is not in the allowlist, the data plane returns 403.
monthlyTokenBudgetbodyintegerNo—Monthly token budget; null unlimited. Once exhausted, requests with this key are rejected until the next reset.
rateLimitbodyintegerNo—Per-minute request limit; null uses the global default.
expiresAtbodystringNo—Expiry time (ISO 8601); null never expires.

Output: returns 201 + llmGatewayKey, where only this response contains the plaintext key (abk_ prefix); afterwards only keyPrefix is visible:

FieldTypeDescription
$idstringKey ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
keystringThe full plaintext key (abk_ prefix), appearing only once in the creation response; afterwards no read endpoint returns it again.
keyPrefixstringThe key's display prefix (non-sensitive), used to identify the key in lists.
namestringKey name.
descriptionstringKey description.
allowedModelsstring[]Allowlist of model IDs permitted for calls; ["*"] allows all models.
monthlyTokenBudgetintegerMonthly token budget; null means unlimited. Rolled up cumulatively from tiered usage data aggregated by UTC day; once exhausted, requests with this key are rejected.
monthlyTokensUsedintegerTokens consumed in the current billing cycle.
budgetResetAtstringNext monthly budget reset time.
rateLimitintegerPer-minute request limit; null uses the project-level default rate limit.
isActivebooleanWhether enabled; when false, the key becomes immediately unavailable.
expiresAtstringExpiry time (ISO 8601); null means never expires.
lastUsedAtstringLast used time.

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/keys" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "keyId": "key_mobile_chat",
    "name": "mobile-app-chat",
    "description": "移动端聊天功能专用",
    "allowedModels": ["gpt-4o-mini"],
    "monthlyTokenBudget": 1000000,
    "rateLimit": 60,
    "expiresAt": null
  }'

Response example:

{
  "$id": "key_mobile_chat",
  "$createdAt": "2026-08-12T09:20:00.000+00:00",
  "$updatedAt": "2026-08-12T09:20:00.000+00:00",
  "key": "abk_proj6789_aB3xK9mN2pQ7wR4tY8vF1jH5cE0iU6oL3sA9bD2gX7zW4nM",
  "keyPrefix": "abk_proj6789_aB3xK9",
  "name": "mobile-app-chat",
  "description": "移动端聊天功能专用",
  "allowedModels": [
    "gpt-4o-mini"
  ],
  "monthlyTokenBudget": 1000000,
  "monthlyTokensUsed": 45230,
  "budgetResetAt": "2026-09-01T00:00:00.000+00:00",
  "rateLimit": 60,
  "isActive": true,
  "expiresAt": null,
  "lastUsedAt": "2026-09-10T14:02:33.000+00:00"
}

PATCH /v1/llm-gateway/keys/{keyId}

Update a sub-key: rename, adjust the model allowlist, rate limit, budget, enabled state, or expiry time; only explicitly passed fields are modified.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
keyIdpathstringYes—Sub-key ID.
namebodystringNo—Key name.
descriptionbodystringNo—Key description.
allowedModelsbodystring[]No—Model allowlist.
monthlyTokenBudgetbodyintegerNo—Monthly token budget.
rateLimitbodyintegerNo—Per-minute request limit.
isActivebodybooleanNo—false disables immediately.
expiresAtbodystringNo—Expiry time (ISO 8601).

Output: Returns the updated llmGatewayKey:

FieldTypeDescription
$idstringKey ID。
$createdAtstringCreation time (ISO 8601).
$updatedAtstringLast update time (ISO 8601).
keystringThe full plaintext key (abk_ prefix), appearing only once in the creation response; afterwards no read endpoint returns it again.
keyPrefixstringThe key's display prefix (non-sensitive), used to identify the key in lists.
namestringKey name.
descriptionstringKey description.
allowedModelsstring[]Allowlist of model IDs permitted for calls; ["*"] allows all models.
monthlyTokenBudgetintegerMonthly token budget; null means unlimited. Rolled up cumulatively from tiered usage data aggregated by UTC day; once exhausted, requests with this key are rejected.
monthlyTokensUsedintegerTokens consumed in the current billing cycle.
budgetResetAtstringNext monthly budget reset time.
rateLimitintegerPer-minute request limit; null uses the project-level default rate limit.
isActivebooleanWhether enabled; when false, the key becomes immediately unavailable.
expiresAtstringExpiry time (ISO 8601); null means never expires.
lastUsedAtstringLast used time.

Call example:

curl -X PATCH "https://<your-endpoint>/v1/llm-gateway/keys/key_mobile_chat" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "rateLimit": 30,
    "isActive": false
  }'

Response example:

{
  "$id": "key_mobile_chat",
  "$createdAt": "2026-08-12T09:20:00.000+00:00",
  "$updatedAt": "2026-09-14T02:10:00.000+00:00",
  "key": "abk_proj6789_aB3xK9mN2pQ7wR4tY8vF1jH5cE0iU6oL3sA9bD2gX7zW4nM",
  "keyPrefix": "abk_proj6789_aB3xK9",
  "name": "mobile-app-chat",
  "description": "移动端聊天功能专用",
  "allowedModels": [
    "gpt-4o-mini"
  ],
  "monthlyTokenBudget": 1000000,
  "monthlyTokensUsed": 45230,
  "budgetResetAt": "2026-09-01T00:00:00.000+00:00",
  "rateLimit": 30,
  "isActive": false,
  "expiresAt": null,
  "lastUsedAt": "2026-09-10T14:02:33.000+00:00"
}

DELETE /v1/llm-gateway/keys/{keyId}

Permanently delete a sub-key (hard delete, not via soft revocation): the document is removed immediately and the key immediately becomes unable to call execution endpoints.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
keyIdpathstringYes—Sub-key ID.

Output: 204 No Content, no response body.

Call example:

curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/keys/key_mobile_chat" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example: 204 No Content: no response body (key revoked).

Trial Provider Bindings

GET /v1/llm-gateway/trial-providers

List the bindable trial Providers offered by the platform: before binding, confirm the platform provider ID and trial quota here.

Input: no path/query/body parameters.

Output: returns the trial provider list (generalized schema any: elements contain the platform provider ID, capabilities, and trial quota information; fields are subject to the actual response).

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/trial-providers" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example: the response is a trial provider array document (generalized schema; fields are subject to the actual response); use the platform provider ID within it to create a binding.

GET /v1/llm-gateway/trial-provider-bindings

List the platform trial Provider bindings currently in effect for this project.

Input: no path/query/body parameters.

Output: returns the binding list (generalized schema any: each entry contains bindingId, platform provider and project associations, quota status, and other information; fields are subject to the actual response).

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example: the response is a binding array document (generalized schema; fields are subject to the actual response).

POST /v1/llm-gateway/trial-provider-bindings

Bind a platform trial Provider to a project under your account: after a successful binding (201), it participates in model routing as trial:<bindingId>.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
providerIdbodystringYes—Platform provider ID (from GET /llm-gateway/trial-providers).

Output: returns 201 + the binding object (generalized schema any; fields are subject to the actual response).

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{ "providerId": "trial-dashscope-gte-rerank" }'

Response example: 201: the response is a binding object JSON (generalized schema; fields are subject to the actual response); note the bindingId for use by subsequent endpoints.

GET /v1/llm-gateway/trial-provider-bindings/{bindingId}

Read the details and quota status of a single trial Provider binding.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
bindingIdpathstringYes—Trial binding ID.

Output: returns the binding object (generalized schema any; fields are subject to the actual response).

Call example:

curl "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example: the response is a binding object JSON (generalized schema; fields are subject to the actual response).

DELETE /v1/llm-gateway/trial-provider-bindings/{bindingId}

Unbind the trial Provider binding: trial:<bindingId> routing immediately becomes invalid.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
bindingIdpathstringYes—Trial binding ID.

Output: 204 No Content, no response body.

Call example:

curl -X DELETE "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example: 204 No Content: no response body (unbound).

POST /v1/llm-gateway/trial-provider-bindings/{bindingId}/health-checks

Live-test the availability of the bound platform trial Provider: verify credentials, network, and model connectivity.

Input:

ParameterLocationTypeRequiredDefault/enumDescription
bindingIdpathstringYes—Trial binding ID.

Output: returns the live test result (generalized schema any: contains health status and per-model verification information; fields are subject to the actual response).

Call example:

curl -X POST "https://<your-endpoint>/v1/llm-gateway/trial-provider-bindings/<BINDING_ID>/health-checks" \
  -H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
  -H "X-Appwrite-Key: <YOUR_API_KEY>"

Response example: the response is a health check result JSON (generalized schema; fields are subject to the actual response).

Errors and boundaries

Correspondence with the Server SDK

service.methodEndpoint
LLMGateway.createChatCompletionPOST /llm-gateway/chat/completions
LLMGateway.createMessagePOST /llm-gateway/messages
LLMGateway.createEmbeddingsPOST /llm-gateway/embeddings
LLMGateway.createRerankPOST /llm-gateway/rerank
LLMGateway.listModels / getModel/llm-gateway/models*
LLMGateway.listProviders / createProvider / getProvider / updateProvider / deleteProvider/llm-gateway/providers*
LLMGateway.getProviderHealth / createProviderHealthCheck / listProviderModels / refreshProviderCache.../health*、.../models、.../cache/refresh
LLMGateway.createProviderModelDiscoveryPOST /llm-gateway/provider-model-discoveries
LLMGateway.listKeys / createKey / updateKey / deleteKey/llm-gateway/keys*
LLMGateway.listTrialProviders / listTrialProviderBindings / createTrialProviderBinding / getTrialProviderBinding / deleteTrialProviderBinding / createTrialProviderBindingHealthCheck/llm-gateway/trial-provider*

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
POST /llm-gateway/rerankllm-gateway.executellmGateway.createRerank

POST /llm-gateway/rerank

Rerank documents

ParameterLocationRequiredTypeConstraints / defaultMeaning
modelbodyyesstring—Rerank model ID.
querybodyyesstring—Query text to rank documents against.
documentsbodyyesarray[string]—Documents to rerank.
topNbodynointegerformat=int32Return only the top N results.
returnDocumentsbodynobooleandefault=falseInclude document text in the response.
instructbodynostringdefault=""Optional native sorting instruction for supported DashScope rerank models. Empty omits the instruction.

Success response: HTTP 200 — llmGatewayRerankResponse.

Response fields: model (string), results (array), usage (object).

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.