Docs
Contents

GraphQL API

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:

Resources and Base Paths

Model NameDirectionCore FieldsDescription
GraphQLRequestRequest bodyquery (string), variables (object), operationName (string)Standard GraphQL POST JSON payload; raw query text such as application/graphql is also supported
GraphQLResponseResponse bodydata (object | null), errors (GraphQLError[])Standard GraphQL response envelope; on partial success, data and errors may coexist
GraphQLErrorError itemmessage (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 HeaderRequiredExample ValueDescription
X-Appwrite-ProjectYesenterprise-ai-hub-210Target project ID (e.g. the "Enterprise Intelligent Customer Service and Knowledge Hub" project in the demo environment)
X-Appwrite-KeyRequired 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-JWTOptional 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-FormatNo1.6.0Response compatibility format version header
Content-TypeYesapplication/json or application/graphqlJSON payload mode or plain GraphQL query text mode

Scope and Resource-Level Permission Evaluation

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 CategoryEndpoint PathIdempotencyRate LimitTypical Use Cases
Data query (Query)POST /v1/graphqlYes (only when executing query operations)60 requests/minuteAggregate 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/mutationNo (depends on the specific mutation operation)60 requests/minuteCreating teams, writing/updating business table row records, creating function executions, or updating user preference configurations

Endpoint List

Method + PathScopeIdempotencyPurpose
POST /graphqlgraphql + target domain read scopeYesExecute GraphQL query (Query) operations
POST /graphql/mutationgraphql + target domain write scopeNoExecute GraphQL mutation (Mutation) operations

Endpoint details

Query and Mutation Execution Mechanism

  1. Parse and Validate: After receiving the query string, the server parses it into an AST and validates field names, argument types, and nesting depth. The default maximum query depth (Max Query Depth) is 10 levels, and the single batch operation limit is constrained by the project quota to prevent malicious circular nested queries from exhausting the CPU.

  2. Variables Substitution: It is recommended to extract dynamic filter conditions (e.g. support ticket ID TK-20261022-001 within the project, pagination queries array) into the variables JSON object for passing, so that the server can reuse compiled query plans and completely avoid string concatenation injection risks.

  3. 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 data field of row records, or user prefs) 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:

ParameterLocationTypeRequiredDefault/enumDescription
querybodystringYes—GraphQL query document string (e.g. query ListSupportTeams(...) { ... }).
variablesbodyobjectNo{}Key-value pair object of query variables, strictly corresponding to the $varName variable declarations in the query document.
operationNamebodystringNonullWhen 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:

FieldTypeDescription
dataobject | nullThe structured result object trimmed according to the query selection set; null when top-level execution fails entirely
errorsarrayOptional 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):

curl -X POST "https://appbuild-sit.oceanbase.com/v1/graphql" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -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:

ParameterLocationTypeRequiredDefault/enumDescription
querybodystringYes—The GraphQL mutation document string (e.g., mutation CreateSupportTeam(...) { ... }).
variablesbodyobjectNo{}The mutation input variables object, corresponding to the $varName variable declarations in the mutation document.
operationNamebodystringNonullSpecifies 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):

curl -X POST "https://appbuild-sit.oceanbase.com/v1/graphql/mutation" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -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[]):

LayerHTTP status codeError type (type) or behaviorTrigger causeTroubleshooting and retry advice
Gateway authentication layer401 Unauthorizedgeneral_access_forbiddenX-Appwrite-Project or X-Appwrite-Key missing or mismatchedVerify that the project ID (e.g., enterprise-ai-hub-210) and the API Key belong to the same environment
Gateway permission layer401 Unauthorizedgeneral_unauthorized_scopeThe API Key does not have the graphql basic scope checkedIn the Console, under "Project Settings -> API Keys", check graphql and the corresponding business domain scopes for this Key
Gateway rate limiting layer429 Too Many Requestsgeneral_rate_limit_exceededExceeds the quota of 60 GraphQL calls per minuteRead the Retry-After response header and apply exponential backoff, or consolidate multiple scattered queries into a single multi-field GraphQL query
Query complexity boundary200 OK (errors[])Max query depth exceededQuery nesting depth exceeds the platform limit (default 10 levels)Split deeply nested selection sets and remove unnecessary circular relation references
Business resolver layer200 OK (errors[])errors[0].message + pathDownstream resource does not exist (404), unique key conflict (409), or missing sub-domain scopeBusiness 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.methodNode.js / Python / Java / Go Method nameHTTP method and pathDescription
Graphql.querygraphql.query({ query })POST /v1/graphqlPass a Map/Object containing query, variables, operationName to execute a query
Graphql.mutationgraphql.mutation({ query })POST /v1/graphql/mutationPass a Map/Object containing query, variables, operationName to execute a mutation