Docs
Contents

Project API General Conventions (Authentication and Access)

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.

This document defines the common communication protocol and governance conventions for all project-level feature REST APIs in Agentbase: covering service and resource boundaries, the complete request header matrix, the API Key Scopes permission matrix, server/client authentication flows (API Key / Session / JWT / Gateway Key), request and response formats, pagination query grammar, rate limiting and idempotency mechanisms, the unified error envelope, and ready-to-run cURL call examples.

Service and resource boundaries

The Agentbase REST API is divided by responsibility into the "Project feature plane (Project API)", the "Agent and gateway data plane (AI Gateway / LLM Gateway / Agent Runtime)", and the "Console management plane (Console API)". This directory (apis/) focuses on access interfaces for all business features under a project; its core boundaries are as follows:

Resources and Base Paths

Authentication and Permissions

Complete Request Header Matrix

Header nameRequiredApplicable scenariosExample valueSemantic description
X-Appwrite-ProjectRequiredAll project-level APIsenterprise-ai-hub-210Identifies the Agentbase project ID the current request belongs to
X-Appwrite-KeyRequired for serverServer APIs / background tasks<APPBASE_API_KEY>Project-level API Key (issued in the Console under "Project Settings -> API Keys")
X-Appwrite-JWTOptional for clientAccessing on behalf of a user identityeyJhbGciOiJIUzI1NiIs...Short-lived user JWT token, used when the server or a BFF makes requests subject to $permissions on behalf of the end user
X-Appwrite-SessionOptional for clientSessions in cookie-less environments66a9d9b804d8e...Explicitly passes the user login session secret (equivalent to the a_session_<projectId> cookie)
AuthorizationOptional for gatewayAI Gateway / LLM GatewayBearer <GATEWAY_KEY>Bearer token; use the appropriate model gateway or AI Gateway tool credential for each endpoint
X-Appwrite-LocaleOptionalInternationalization and error messageszh-CNSpecifies the localization language for responses (following ISO 639-1 / BCP-47, see Locale API)
X-Appwrite-Response-FormatOptionalCross-version format compatibility1.6.0Specifies the backward-compatible serialization format version of the response body
If-Match / If-None-MatchOptionalOptimistic concurrency control (CAS)"v3" or "1"Used for conditional concurrent update validation of knowledge bases, memory systems, or configuration
Idempotency-KeyOptionalAsync writes and task submissionreq_20261022_001Idempotency key (up to 128 characters), preventing duplicate charges or duplicate inserts caused by network timeout retries

API Key Scopes Permission Matrix

When creating a project API Key, follow the principle of least privilege and select the required Scopes. The mapping of core Scopes required by each feature module is as follows:

Business moduleRead-only Scope (*.read)Write/manage Scope (*.write / specialized)Compatible aliases and special notes
Users and teams (Users / Teams)users.read, teams.readusers.write, teams.write, sessions.writeusers.write Can issue Custom Tokens (/users/{userId}/tokens)
Databases (Databases)databases.read, tables.read, columns.read, indexes.read, rows.readdatabases.write, tables.write, columns.write, indexes.write, rows.writeLegacy document model aliases: collections.read/write, attributes.read/write, documents.read/write
Storage and file tokens (Storage / Tokens)buckets.read, files.read, tokens.readbuckets.write, files.write, tokens.writeFile download/preview supports header-free access via ?token=<secret> when fileSecurity=true
Knowledge base and lexicons (Knowledge Base)knowledgebases.read, lexicons.readknowledgebases.write, lexicons.writeLexicons are independently governed by lexicons.read / lexicons.write
Memory system (Memory)memories.readmemories.write, memories.delete, memories.export, memories.shareCovers long-term memory, user profiles, context dreaming, and experience/skill distillation
Models and AI gateway (LLM Gateway / AI Gateway)llm-gateway.providers.read, llm-gateway.keys.read, aiGateway.readllm-gateway.providers.write, llm-gateway.keys.write, aiGateway.writeModel calls use llm-gateway.execute; AI Gateway tools use the corresponding gateway credential
Agent runtime (Agent Runtime)agent-runtime.read, projects.readagent-runtime.write, agent-runtime.projectThe project-level agent workbench (/v1/agent-runtime/project/*) uses agent-runtime.project; ordinary project keys do not provide projects.write
Functions and sites (Functions / Sites)functions.read, execution.read, sites.readfunctions.write, execution.write, sites.writePublic function execution and published preview/production domain access require no server-side API Key
Messaging and moderation (Messaging / Moderation)providers.read, topics.read, subscribers.read, messages.read, moderation.config.read, moderation.log.readproviders.write, topics.write, subscribers.write, messages.write, moderation.config.writeCovers email/SMS/push channels and text/image content safety moderation
Observability and auxiliary domains (Observability / Misc)observability.traces.read, observability.metrics.read, webhooks.read, locale.read, avatars.read, health.readobservability.ingest.write, webhooks.writeOTLP trace ingestion uses observability.ingest.write; observability.write is its compatibility alias. Select other scopes for the specific feature

Comparison of Session / JWT / OAuth2 and API Key authentication flows

  1. Server-side direct connection flow (API Key): The backend service attaches X-Appwrite-Project and X-Appwrite-Key to every request. If the Key is missing, forged, or does not match the project, 401 (general_access_forbidden) is returned; if the Key is valid but lacks the Scope declared for the current endpoint, 401 (general_unauthorized_scope) is returned.

  2. Server-issued Custom Token handed to client for login flow: The backend calls POST /v1/users/{userId}/tokens (see Users API) to generate a one-time short-lived secret and delivers it to the browser or app; the client uses the (userId, secret) to establish a user Session, then directly accesses table rows or storage files protected by $permissions.

  3. BFF proxy call flow (JWT): The frontend obtains a user JWT with a validity of 15 minutes via the Client SDK and passes it to the backend BFF with business requests; the BFF uses X-Appwrite-Project + X-Appwrite-JWT to access Agentbase, and the platform then performs resource-level permission checks under that end user's role (user:<id>, team:<id>, label:<name>).

Endpoint overview

The 24 functional module endpoints in this directory are uniformly mounted under /v1 by path prefix:

Functional categoryPath prefixCorresponding documentationCore responsibilities
Project management/v1/project/*overview/overview.mdProject environment variable management, online OceanBase table schema conversion (e.g., switching to Shared V2)
Identity and teams/v1/users/*, /v1/teams/*auth/users.md, auth/teams.mdUser lifecycle, labels, Mfa, Token issuance, team and member role management
Structured and document databases/v1/tablesdb/*, /v1/documentsdb/*, /v1/databases/*databases/overview.md, databases/permissions.mdDatabase/table/column/index management, row-level CRUD, cross-table distributed transactions, schema multi-versioning and rollback
File storage and short-link tokens/v1/storage/*, /v1/tokens/*storage.md, file-tokens.mdStorage bucket and file chunked upload, image scaling preview, short-lived file access Token issuance
Knowledge base and lexicons/v1/knowledgebases/*, /v1/lexicons/*knowledge-base/overview.md, knowledge-base/wiki.md, knowledge-base/versions.mdMulti-source document parsing and chunking, hybrid retrieval, lexicons (synonyms/expansion terms/stopwords), GraphRAG, RAPTOR, Wiki, and version archiving
Memory system/v1/memory/*memory/overview.mdLong-term factual memory, conversation reasoning ingestion, user profile extraction, Dreaming, and experience/skill distillation
Models and AI gateway/v1/llm-gateway/*, /v1/ai-gateway/*models-ai-gateway/llm-gateway.md, models-ai-gateway/ai-gateway.mdManaged model providers, policies, MCP, and A2A
Agent runtime/v1/agent-runtime/*agent-runtime.mdProject-level agent workbench configuration, lexicon binding, Preview/Published sessions (Threads) and streaming run (Runs) events
Observability and content safety/v1/traces, /v1/observability/*, /v1/moderation/*observability/overview.md, moderation.mdOpenTelemetry trace reporting, GenAI metrics aggregation, online evaluations, and image/text content moderation
Compute, sites, and notifications/v1/functions/*, /v1/sites/*, /v1/messaging/*functions.md, sites.md, messaging.mdServerless function deployment and synchronous/asynchronous execution, web site hosting, multi-channel message delivery
Platform auxiliary tools/v1/webhooks/*, /v1/graphql*, /v1/avatars/*, /v1/locale/*, /v1/health/*misc/webhooks.md, misc/graphql.md, misc/avatars.md, misc/locale.md, misc/health.mdEvent callback subscriptions, GraphQL queries, QR codes/initials avatars/webpage screenshots, internationalization dictionaries, and instance health checks

Endpoint List

This page covers global common protocol specifications and does not declare proprietary business endpoints of its own; for the complete list of "HTTP method + path" for each business module, please consult the corresponding functional documentation in the table above.

Endpoint details

Request and response lifecycle

  1. Protocol and encoding: HTTPS (TLS 1.2+) is mandatory across all lines; the character set for requests and responses is uniformly UTF-8.

  2. Timestamp convention: All date-time fields (such as $createdAt, $updatedAt, expire, scheduledAt) use the standard ISO 8601 UTC format (for example, 2026-10-22T08:30:00.000+00:00); only /v1/health/time and OTLP nanosecond timestamps use Unix timestamps.

  3. Asynchronous task pattern (202 Accepted): For time-consuming background computations (such as knowledge base document parsing and building, large-batch memory extraction, asynchronous function execution, Agent Run creation, and table schema conversion tasks), the creation endpoint immediately returns 202 Accepted along with a task object (containing status: "pending" / "processing" and the task ID); callers can obtain the final execution result by polling the detail endpoint, subscribing to the SSE event stream, or registering a Webhook.

Request and response formats

Memory business deletion requests use a JSON body, and lists mainly use limit/cursor, which differs from the common filtering conventions below; refer to Memory API for specifics.

Requests and Responses

Standard list response vs. single resource response

Single resource response structure (using a typical resource with system metadata as an example):

Metadata fieldTypeDescription
$idstringUnique resource identifier
$createdAtstringCreation time (ISO 8601)
$updatedAtstringLast update time (ISO 8601)
$permissionsstring[]Array of resource-level permission strings (e.g., ["read(\"any\")", "update(\"team:dev/owner\")"])

List resource response structure:

FieldTypeDescription
totalintegerTotal number of records matching the filter; always 0 when total=false is passed in the query parameters
<resources>[]arrayArray of resource objects within the current pagination window (field name varies by module, e.g., users, rows, documents, buckets)

Unified error model

All non-2xx responses uniformly use the following JSON envelope structure:

{
  "message": "Not found",
  "code": 404,
  "type": "not_found",
  "version": "2.10.0",
  "requestId": "req_9f8e7d6c5b4a3210"
}

Errors and boundaries

HTTP status codeTypical type Error codeTrigger reasonRetriableHandling recommendation
400 Bad Requestgeneral_argument_invalid / general_query_invalidRequest body field type mismatch, out-of-range enum value, or queries[] syntax errorNoValidate request parameter formats and field constraints, then fix and retry
401 Unauthorizedgeneral_access_forbiddenX-Appwrite-Key Missing, invalid, or mismatched with X-Appwrite-ProjectNoCheck the project ID and API Key in environment variables
401 Unauthorizedgeneral_unauthorized_scopeAPI Key is valid but not granted the Scope required by the current endpointNoCheck the corresponding Scope on the API Keys page in the Console
403 Forbiddengeneral_resource_blocked / project_database_read_onlyResource is banned, or the project is in a read-only freeze window during schema mode cutover (Cutover)DependsIf it is a schema mode cutover freeze window, wait for the Cutover to complete and retry
404 Not Found*_not_foundTarget resource ID does not exist, or the client identity lacks read permission (anti-enumeration covert return of 404)NoVerify the resource ID in the path and resource-level $permissions
409 Conflictgeneral_conflict / *_already_existsDuplicate custom resource ID, attempt to delete a lexicon still referenced, or optimistic lock version conflictNoQuery the existing resource state or refresh to the latest version number before resubmitting
429 Too Many Requestsgeneral_rate_limit_exceededTriggered the account/project/caller token bucket rate limitYesRead the response header Retry-After (seconds) or X-RateLimit-Reset and retry with backoff
503 Service Unavailablegeneral_service_unavailableUpstream dependency (such as an external model provider or queue) is temporarily busyYesRetry using an exponential backoff strategy with random jitter (Jitter)

Pagination and Queries

List endpoints accept a queries array, where each element is a structured query string (constructed by the Query builder in Server SDKs; when making direct HTTP calls, you can pass a JSON-serialized query description or functional syntax):

Rate Limiting and Idempotency

Complete Call Examples

The following examples demonstrate standard HTTP call patterns based on the showcase project enterprise-ai-hub-210 (enterprise intelligent customer service and knowledge platform): two-header authentication, array-style pagination queries, and total=false skip counting.

List customer service agent accounts in active status within the project (with pagination and filtering; queries[] is in array form):

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable \
  '<APPBASE_ENDPOINT_WITH_V1>/users?queries[]=limit(25)&queries[]=offset(0)&queries[]=equal("status",true)&total=false' \
  -H "X-Appwrite-Project: <APPBASE_PROJECT_ID>" \
  --header @-
)

Create a resource (JSON request body; using the creation of a tier-two technical support team as an example):

(
  set +x
  set -o pipefail
  : "${APPBASE_API_KEY:?Set APPBASE_API_KEY}"
: "${APPBASE_ENDPOINT:?Set APPBASE_ENDPOINT to the target API endpoint including /v1}"
APPBASE_ENDPOINT="${APPBASE_ENDPOINT%/}"
: "${APPBASE_PROJECT_ID:?Set APPBASE_PROJECT_ID for the target environment}"
builtin printf 'X-Appwrite-Key: %s\n' "$APPBASE_API_KEY" | curl --disable -X POST "${APPBASE_ENDPOINT}/teams" \
  -H "X-Appwrite-Project: ${APPBASE_PROJECT_ID}" \
  --header @- \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "unique()",
    "name": "OceanBase 向量检索专家支持组",
    "roles": ["owner", "engineer"]
  }'
)

A successful response is 201 Created + resource JSON; a list response looks like {"total": 0, "teams": [...]} (when total=false, total is always 0).

Typical error response (Key missing or invalid, 401):

{
  "message": "Project is not accessible in this region or API key is invalid.",
  "code": 401,
  "type": "general_access_forbidden",
  "version": "2.10.0"
}

Key is valid but missing the required Scope (401):

{
  "message": "The current API key does not have the required scope (teams.write) to perform this action.",
  "code": 401,
  "type": "general_unauthorized_scope",
  "version": "2.10.0"
}

Rate limit exceeded (429, carrying the Retry-After response header):

{
  "message": "Too many requests",
  "code": 429,
  "type": "general_rate_limit_exceeded",
  "version": "2.10.0"
}

When troubleshooting, it is recommended to check four places at once: the HTTP status code, the error type, the response headers X-RateLimit-Remaining / Retry-After, and the requestId in the response (which can be used for request-level search in observability platforms).

Correspondence with the Server SDK

All Server SDKs (agentbase-node-sdk@2.10.0, agentbase-python-sdk==2.10.0, and the Java / Go Server SDKs) share the conventions on this page; HTTP-level differences only appear in specific endpoints and business parameters, while authentication headers, the error model, and pagination and rate limiting semantics are fully consistent.

Server SDK ServiceAPI Reference DocumentationCore Responsibility Description
Usersauth/users.mdUser lifecycle, labels, sessions, MFA, and Token issuance
Teamsauth/teams.mdTeam and member role management
TablesDB / DocumentsDB / Databasesdatabases/overview.mdStructured tables, collections, row/document CRUD, transactions, and Schema versions
Storagestorage.mdStorage buckets and file upload, preview, and download
Tokensfile-tokens.mdShort-lived access token management for stored files
Functionsfunctions.mdServerless functions, deployment packages, environment variables, and execution records
Projectoverview/overview.mdProject global variables and OceanBase schema mode cutover
Messagingmessaging.mdEmail/SMS/push providers, topics, and message sending
Sitessites.mdStatic and SSR site builds, deployments, and preview domains
Memorymemory/overview.mdLong-term memory, user profiles, context dreaming, and skill distillation
KnowledgeBases / Lexiconsknowledge-base/overview.mdKnowledge base document ingestion, hybrid retrieval, lexicons, Wiki, and version archiving
LlmGatewaymodels-ai-gateway/llm-gateway.mdModel providers, quotas, and base model invocation
AiGatewaymodels-ai-gateway/ai-gateway.mdPolicies, MCP, and A2A
AgentRuntimeagent-runtime.mdProject-level agent workbench, Draft preview, and Published runs
Observabilityobservability/overview.mdOTLP trace reporting, metrics, and evaluation runs
Moderationmoderation.mdAutomatic content moderation for database text and storage bucket images
Webhooks / Graphql / Avatars / Locale / Healthmisc/webhooks.md etc.Webhook subscriptions, GraphQL, graphical tools, internationalization dictionaries, and health checks

For the permission string grammar and semantics on each resource, see permissions.