Docs
Contents

Server SDK(Python)

Before running the examples, replace <APPBASE_ENDPOINT_WITH_V1>, <APPBASE_CONSOLE_ORIGIN>, and <APPBASE_CONSOLE_HOST> where used with values for the intended environment, and verify that the project and credentials belong to that environment.

Python backends / admin scripts / data pipelines call the Server SDK (agentbase package, snake_case) with aproject API Key. API Key requestsskip row-level permission checks (hasRole) and must be stored only on controlled servers. For the Node / Java / Go faces, see nodejs.md / java.md / go.md in the same directory.

Artifacts and installation

Requires Python 3.9+, with runtime dependencies requests and pydantic>=2,<3. The artifactis not published to PyPI: extract the wheel (including the Console package) from the agentbase-sdks release ZIP and pip install it; for full commands see ../integration.md "Python notes" and ../examples/python.md "Obtaining and installing". Do not install the open-source appwrite package as a substitute (it lacks the TablesDB / Knowledge Bases and other surfaces).

Initialization

The agentbase package's __init__ is empty; all symbols are imported per module:

The Python Server SDK 2.12.0 default transport can forward the project API key across hosts when redirected. Use a direct HTTP request with redirects disabled against the verified server endpoint.

import os

import requests

endpoint = os.environ['APPBASE_ENDPOINT'].rstrip('/')
response = requests.get(
    endpoint + '/tablesdb',
    headers={
        'X-Appwrite-Project': os.environ['APPBASE_PROJECT_ID'],
        'X-Appwrite-Key': os.environ['APPBASE_API_KEY'],
    },
    allow_redirects=False,
    timeout=10,
)
if not 200 <= response.status_code < 300:
    raise RuntimeError(f'Agentbase request failed: HTTP {response.status_code}')
databases = response.json()

Other configuration (all return Client via chaining): set_organization(value) (organization-level queries), set_jwt(value) / set_session(value) (only for controlled flows where the endpoint explicitly requires user identity), set_self_signed(status), add_header(key, value).

5-minute quickstart

See the database API to create a database and table, then write and query rows. Check each response before proceeding.

Calling conventions

Client configuration, cursor pagination, and file upload in practice

agentbase.client.Client provides complete chainable configuration methods, supporting custom timeouts, TLS verification, locale languages, and custom request headers:

Client MethodInjected HTTP headerUse cases and security constraints
set_endpoint(endpoint)— (request base URL)Required, in the form https://appbuild-sit.oceanbase.com/v1 or https://appbuild.oceanbase.com/v1.
set_project(value)X-Appwrite-ProjectRequired, target project ID (e.g. the demo project enterprise-ai-hub-210).
set_key(value)X-Appwrite-KeyThe primary server-side authentication method, skips RLS (hasRole), authorized with the minimal scopes.
set_jwt(value)X-Appwrite-JWTCalls data-plane APIs on behalf of a specific logged-in user (bound by that user's RLS row-level permissions).
set_session(value)X-Appwrite-SessionLoaded when the server forwards a browser login session Cookie.
set_organization(value)X-Appwrite-OrganizationSpecifies the organization context for organization-level query and governance APIs (e.g. 69c6d1aa00062e6bb60).
set_locale(value)X-Appwrite-LocaleSpecifies the language for internationalized responses (e.g. zh-CN).
set_self_signed(status)— (TLS verification toggle)Use only for private test instances with self-signed certificates; keep False in production.
add_header(key, value)Custom request headersInject distributed tracing headers (traceparent) or custom idempotency identifiers.

Cursor pagination, file upload, and async task polling templates

Use the last row ID as the next cursor and give asynchronous jobs a deadline. See the Storage API and document ingestion. Example locator: subProductId = finance.

Using together with the Console SDK (agentbase_console)

The Python delivery package ZIP includes both the server-side data-plane wheel (agentbase) and the management-plane wheel (agentbase_console). Both can be imported in the same Python process (namespaces fully isolated): use agentbase_console to perform organization/project creation and API Key issuance, then use agentbase to perform data-plane reads and writes for business tables, storage, knowledge bases, and memory (see ../console-sdk/python.md).

Feature surface navigation

The service plane is isomorphic with the Node plane (snake_case); for the full mapping see nodejs.md "Feature plane navigation"; feature pages: Databases, Storage, Functions, Sites, Users, Teams, Messaging, memory, knowledge base (call surface available from 15.4.0), LLM Gateway, AI Gateway, observability, moderation, cross-cutting services.

No Sql service (SQL uses the HTTP form or the Console SDK, see ../databases/sql-proxy.md); no Realtime (client-side capability).

Error Handling

Use the HTTP status and the response type to identify failures. If a request redirects, verify the configured server endpoint before trying again.

Example Guide