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
Methodsynchronous returns a pydantic model: accessed byfield name (
user.id,listed.total); themodel_typeparameter only types the businessdatapayload of documents / rows (dict by default).columns/indexesare a list of dicts; incremental column endpoints mostly return a 202 asynchronous task.update_rows/delete_rowsoperate on the whole table when no queries are supplied; always add anQueryfilter.Use
agentbase.query.Queryfor queries (isomorphic with Node) andagentbase.id.IDfor IDs; permissions can usePermission.read(Role.any())or a raw syntax string list passed directly.
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 Method | Injected HTTP header | Use 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-Project | Required, target project ID (e.g. the demo project enterprise-ai-hub-210). |
set_key(value) | X-Appwrite-Key | The primary server-side authentication method, skips RLS (hasRole), authorized with the minimal scopes. |
set_jwt(value) | X-Appwrite-JWT | Calls 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-Session | Loaded when the server forwards a browser login session Cookie. |
set_organization(value) | X-Appwrite-Organization | Specifies the organization context for organization-level query and governance APIs (e.g. 69c6d1aa00062e6bb60). |
set_locale(value) | X-Appwrite-Locale | Specifies 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 headers | Inject 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
Complete Python (Server / Console) call syntax: ../examples/python.md