GraphQL API
Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1> with the intended environment API endpoint and verify that the project and credentials belong to that environment.
Access the Agentbase platform data plane via the GraphQL Query and Mutation protocol: the query syntax, permission evaluation, rate limit quotas, and REST data model remain strictly consistent, supporting aggregation of multi-domain resource reads and field-level projection trimming within a single request.
Service and resource boundaries
The GraphQL API provides a unified graph query and mutation entry point for each core business domain within a project (accounts and users, teams, TablesDB / DocumentsDB databases, Storage buckets and files, Functions execution, etc.). Its core boundaries are as follows:
Protocol and model isomorphism: The GraphQL Schema is dynamically mapped by the platform based on the current project's system metadata and user-defined table/collection structures, reusing at the underlying level the exact same Service layer, Validator, and OceanBase storage engine as the REST API (supporting table pool modes such as
Shared V2).Multi-resource aggregation in a single round trip: In scenarios requiring simultaneous reads of multiple related resources within a project (e.g. fetching the current team information, support ticket table records, and storage bucket metadata at the same time) or trimming response fields to reduce bandwidth overhead, a single
POST /v1/graphqlrequest can replace multiple REST round trips.Does not replace binary streams and long-lived connections: File streaming download (
/storage/buckets/{bucketId}/files/{fileId}/download), knowledge base raw document streams, and the Agent Runtime SSE event stream (/v1/agent-runtime/runs/{runId}/events) are not carried over GraphQL and still use the corresponding REST / SSE endpoints.Separation of HTTP status codes and business errors: Following the GraphQL specification, as long as the HTTP transport layer and JSON parsing succeed, the HTTP status code still returns
200 OKeven if an individual resolver encounters a permission denial or parameter validation failure, with specific exceptions encapsulated in theerrors[]array of the response body.
Resources and Base Paths
Base URL:
https://appbuild-sit.oceanbase.com/v1(or your private deployment instance endpointhttps://<your-endpoint>/v1).Path prefix:
/graphql; a stateless computation endpoint that does not persist the GraphQL query document itself.Core request/response models:
| Model Name | Direction | Core Fields | Description |
|---|---|---|---|
GraphQLRequest | Request body | query (string), variables (object), operationName (string) | Standard GraphQL POST JSON payload; raw query text such as application/graphql is also supported |
GraphQLResponse | Response body | data (object | null), errors (GraphQLError[]) | Standard GraphQL response envelope; on partial success, data and errors may coexist |
GraphQLError | Error item | message (string), locations (array), path (array), extensions (object) | Location information and error context for a single field resolution or mutation execution failure |
Authentication and Permissions
See general conventions for authentication and request header conventions.
Request Header Matrix
| Request Header | Required | Example Value | Description |
|---|---|---|---|
X-Appwrite-Project | Yes | enterprise-ai-hub-210 | Target project ID (e.g. the "Enterprise Intelligent Customer Service and Knowledge Hub" project in the demo environment) |
X-Appwrite-Key | Required on the server side | <APPBASE_API_KEY> | Project-level API Key; server-side calls must include graphql and the scope corresponding to the resource being invoked |
X-Appwrite-JWT | Optional on the client side | <USER_JWT_TOKEN> | Short-lived JWT token passed in when the client invokes on behalf of an end user |
X-Appwrite-Response-Format | No | 1.6.0 | Response compatibility format version header |
Content-Type | Yes | application/json or application/graphql | JSON payload mode or plain GraphQL query text mode |
Scope and Resource-Level Permission Evaluation
Entry-level scope: The API Key must first possess the
graphqlscope (otherwise the entry point is rejected outright and returnsgeneral_unauthorized_scope).Downstream resolver cascaded authorization: When executing each top-level Query or Mutation field, the GraphQL engine performs a second check of the scope required by the underlying REST operation mapped to that field (e.g. executing
teamsCreaterequiresteams.write, and executingtablesCreateRowrequiresrows.write).Row / Document / File Security: When accessed with a client session or
X-Appwrite-JWT, the underlying$permissionspolicy of the target table/collection/bucket is enforced (see permission string grammar); when a server-sideX-Appwrite-Keyis presented, only the API Key scope is checked.
Endpoint overview
The GraphQL module provides two core HTTP POST endpoints, serving read-only queries and state changes respectively (the underlying execution pipeline shares the same Schema resolver; the split into two paths facilitates read/write separation, rate limiting, and audit policy configuration at the gateway layer by path):
| Capability Category | Endpoint Path | Idempotency | Rate Limit | Typical Use Cases |
|---|---|---|---|---|
| Data query (Query) | POST /v1/graphql | Yes (only when executing query operations) | 60 requests/minute | Aggregate queries of teams, users, business table records (e.g. customer service support tickets customer_tickets), and storage bucket file lists |
| State change (Mutation) | POST /v1/graphql/mutation | No (depends on the specific mutation operation) | 60 requests/minute | Creating teams, writing/updating business table row records, creating function executions, or updating user preference configurations |
Endpoint List
| Method + Path | Scope | Idempotency | Purpose |
|---|---|---|---|
POST /graphql | graphql + target domain read scope | Yes | Execute GraphQL query (Query) operations |
POST /graphql/mutation | graphql + target domain write scope | No | Execute GraphQL mutation (Mutation) operations |
Endpoint details
Query and Mutation Execution Mechanism
Parse and Validate: After receiving the
querystring, the server parses it into an AST and validates field names, argument types, and nesting depth. The default maximum query depth (Max Query Depth) is10levels, and the single batch operation limit is constrained by the project quota to prevent malicious circular nested queries from exhausting the CPU.Variables Substitution: It is recommended to extract dynamic filter conditions (e.g. support ticket ID
TK-20261022-001within the project, paginationqueriesarray) into thevariablesJSON object for passing, so that the server can reuse compiled query plans and completely avoid string concatenation injection risks.Field naming mapping rules:
System metadata fields in REST responses (prefixed with
$, such as$id,CreatedAt,$updatedAt,$permissions,$databaseId,$tableId) are uniformly mapped to underscore-prefixed names in the GraphQL Schema due to grammar specification restrictions:_id,_createdAt,_updatedAt,_permissions,_databaseId,_tableId.Nested JSON objects or dynamic payload fields without a fixed schema (such as the
datafield of row records, or userprefs) are serialized as JSON strings in GraphQL responses; clients can restore them into structured objects after parsing.
Requests and Responses
Complete specifications are given per endpoint below: input (field-level tables for path / query / body), output (return model and key fields), examples (copyable curl), and response examples.
POST /v1/graphql
Execute a GraphQL query: the request body is a standard GraphQL query / variables / operationName JSON document, with the schema covering the equivalent read operations of each domain's REST API.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
query | body | string | Yes | — | GraphQL query document string (e.g. query ListSupportTeams(...) { ... }). |
variables | body | object | No | {} | Key-value pair object of query variables, strictly corresponding to the $varName variable declarations in the query document. |
operationName | body | string | No | null | When query When the document contains multiple named operations, explicitly specify the name of the operation to perform. |
Output: Returns 200 OK plus the standard GraphQL response object:
| Field | Type | Description |
|---|---|---|
data | object | null | The structured result object trimmed according to the query selection set; null when top-level execution fails entirely |
errors | array | Optional list of errors; omitted when execution succeeds entirely. Each element contains message, locations (line/column), and path |
Example (aggregate query for the team list and customer service business database info within a project):
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/graphql" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"operationName": "GetSupportWorkspaceOverview",
"query": "query GetSupportWorkspaceOverview($teamQueries: [String!], $bucketId: String!) { teamsList(queries: $teamQueries) { total teams { _id _createdAt name total } } storageGetBucket(bucketId: $bucketId) { _id name fileSecurity maximumFileSize enabled } }",
"variables": {
"teamQueries": ["limit(10)"],
"bucketId": "kb_enterprise_docs"
}
}'
)Response example (200 OK):
{
"data": {
"teamsList": {
"total": 2,
"teams": [
{
"_id": "team_tier2_support",
"_createdAt": "2026-10-20T08:15:00.000+00:00",
"name": "二线分布式数据库专家组",
"total": 8
},
{
"_id": "team_ai_ops",
"_createdAt": "2026-10-21T03:40:00.000+00:00",
"name": "AI 网关与知识中台运维组",
"total": 5
}
]
},
"storageGetBucket": {
"_id": "kb_enterprise_docs",
"name": "企业知识库文档存储桶",
"fileSecurity": true,
"maximumFileSize": 52428800,
"enabled": true
}
}
}POST /v1/graphql/mutation
Executes a GraphQL mutation: the request body is a standard GraphQL mutation document, and the Schema covers the equivalents of the create, update, and delete operations of each domain's REST APIs.
Input:
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
query | body | string | Yes | — | The GraphQL mutation document string (e.g., mutation CreateSupportTeam(...) { ... }). |
variables | body | object | No | {} | The mutation input variables object, corresponding to the $varName variable declarations in the mutation document. |
operationName | body | string | No | null | Specifies the mutation name to execute in a multi-operation document. |
Output: Returns 200 OK plus the standard GraphQL response object (including data and an optional errors array).
Example (create an on-call customer service agent team and return metadata):
(
set +x
set -o pipefail
: "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "<APPBASE_ENDPOINT_WITH_V1>/graphql/mutation" \
-H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
--header @- \
-H "Content-Type: application/json" \
-d '{
"operationName": "CreateOnCallTeam",
"query": "mutation CreateOnCallTeam($teamId: String!, $name: String!, $roles: [String!]) { teamsCreate(teamId: $teamId, name: $name, roles: $roles) { _id _createdAt _updatedAt name total } }",
"variables": {
"teamId": "team_oncall_2026",
"name": "企业智能客服 7x24 值班组",
"roles": ["owner", "dispatcher", "specialist"]
}
}'
)Response example (200 OK):
{
"data": {
"teamsCreate": {
"_id": "team_oncall_2026",
"_createdAt": "2026-10-22T09:12:30.000+00:00",
"_updatedAt": "2026-10-22T09:12:30.000+00:00",
"name": "企业智能客服 7x24 值班组",
"total": 0
}
}
}Partial failure / business error response example (200 OK carrying errors[]):
{
"errors": [
{
"message": "Team with the requested ID already exists.",
"locations": [
{
"line": 1,
"column": 78
}
],
"path": [
"teamsCreate"
]
}
],
"data": {
"teamsCreate": null
}
}Errors and boundaries
The GraphQL API has a two-layer error handling mechanism: transport/gateway-layer errors (returning a non-2xx HTTP status code) and GraphQL execution-layer errors (returning 200 OK with errors listed in errors[]):
| Layer | HTTP status code | Error type (type) or behavior | Trigger cause | Troubleshooting and retry advice |
|---|---|---|---|---|
| Gateway authentication layer | 401 Unauthorized | general_access_forbidden | X-Appwrite-Project or X-Appwrite-Key missing or mismatched | Verify that the project ID (e.g., enterprise-ai-hub-210) and the API Key belong to the same environment |
| Gateway permission layer | 401 Unauthorized | general_unauthorized_scope | The API Key does not have the graphql basic scope checked | In the Console, under "Project Settings -> API Keys", check graphql and the corresponding business domain scopes for this Key |
| Gateway rate limiting layer | 429 Too Many Requests | general_rate_limit_exceeded | Exceeds the quota of 60 GraphQL calls per minute | Read the Retry-After response header and apply exponential backoff, or consolidate multiple scattered queries into a single multi-field GraphQL query |
| Query complexity boundary | 200 OK (errors[]) | Max query depth exceeded | Query nesting depth exceeds the platform limit (default 10 levels) | Split deeply nested selection sets and remove unnecessary circular relation references |
| Business resolver layer | 200 OK (errors[]) | errors[0].message + path | Downstream resource does not exist (404), unique key conflict (409), or missing sub-domain scope | Business code must not only check response.status === 200; it must also check whether body.errors is an empty array or undefined |
Correspondence with the Server SDK
The Server SDKs for all languages provide a Graphql service class that encapsulates calls to the two HTTP endpoints above:
Server SDK service.method | Node.js / Python / Java / Go Method name | HTTP method and path | Description |
|---|---|---|---|
Graphql.query | graphql.query({ query }) | POST /v1/graphql | Pass a Map/Object containing query, variables, operationName to execute a query |
Graphql.mutation | graphql.mutation({ query }) | POST /v1/graphql/mutation | Pass a Map/Object containing query, variables, operationName to execute a mutation |