Databases API
Full lifecycle interfaces for tabular databases: CRUD and batch operations on databases, tables/collections, columns/attributes, indexes, and rows/documents, transactions, row aggregation, plus Schema versions and rollback. This domain covers three coexisting service surfaces:
TablesDB(/tablesdb): the main TablesDB surface with strong schema (table → column → row).DocumentsDB(/documentsdb): the document-oriented surface, where documents are stored directly under collections and column definitions are optional.Databases(/databases): the legacy compatibility surface (collection / attribute / document terminology), semantically isomorphic to TablesDB.
DocumentsDB and the legacy Databases lack the /aggregation (row aggregation) and /schema/versions (Schema versions) endpoints — these two capabilities exist only on the TablesDB surface.
Service and resource boundaries
The Databases API is built on the underlying OceanBase distributed storage engine (such as the Shared V2 table pool mode and business database enterprise_biz_db of showcase project enterprise-ai-hub-210), and uniformly exposes three major access surfaces: a strong-schema tabular model (TablesDB), a document model without fixed column constraints (DocumentsDB), and a legacy compatibility model (Databases). It supports single/batch CRUD, atomic column increments/decrements, row-level aggregate statistics, cross-table ACID transactions, and online Schema version commits with one-click rollback.
Resources and Base Paths
Base URL:
https://<your-endpoint>/v1; three prefixes:/tablesdb,/documentsdb,/databases.Hierarchy: database
{databaseId}→ table{tableId}(collection{collectionId}) → row{rowId}(document{documentId}).Unified ID constraints: custom IDs use a-z, A-Z, 0-9,
.,-,_, must not start with a special character, and are at most 36 characters long.
Authentication and Permissions
For authentication and request header conventions, see Common Conventions. Scopes in this domain:
| Scope | Coverage |
|---|---|
databases.read / databases.write | Database-level and Schema version operations |
tables.read / tables.write (compatible with collections.read / collections.write) | Table/collection, column/attribute, and index operations |
rows.read / rows.write (compatible with documents.read / documents.write) | Row/document reads and writes, and transactions |
The scope arrays are legacy/new naming-compatible aliases; a Key holding either one suffices. For the semantics of resource-level permissions (rowSecurity / documentSecurity and row/document $permissions), see permissions; API Key access is not constrained by resource-level permissions.
Endpoint overview
The database module contains 173 HTTP endpoints in total: TablesDB (/v1/tablesdb/*) provides 74 endpoints (covering databases, tables, 17 column types, indexes, row CRUD, aggregation, transactions, and Schema versions), DocumentsDB (/v1/documentsdb/*) provides 31 endpoints, and the legacy Databases (/v1/databases/*) provides 68 endpoints.
Endpoint List
TablesDB (/tablesdb, 74 endpoints)
| Method + path | Purpose |
|---|---|
GET /tablesdb | List databases |
POST /tablesdb | Create database |
GET /tablesdb/{databaseId} | Get database |
PUT /tablesdb/{databaseId} | Update database name/enabled status |
DELETE /tablesdb/{databaseId} | Delete database |
GET /tablesdb/{databaseId}/tables | List tables |
POST /tablesdb/{databaseId}/tables | Create table (may include full columns/indexes definitions) |
GET /tablesdb/{databaseId}/tables/{tableId} | Get table |
PUT /tablesdb/{databaseId}/tables/{tableId} | Update table (includes full-structure submission) |
DELETE /tablesdb/{databaseId}/tables/{tableId} | Delete table |
GET /tablesdb/{databaseId}/tables/{tableId}/columns | List columns |
POST /tablesdb/{databaseId}/tables/{tableId}/columns/{type} | Create column (type ∈ 17 types, see below) |
GET /tablesdb/{databaseId}/tables/{tableId}/columns/{key} | Get column |
PATCH /tablesdb/{databaseId}/tables/{tableId}/columns/{type}/{key} | Update column |
PATCH /tablesdb/{databaseId}/tables/{tableId}/columns/{key}/comment | Update column label (display name) |
PATCH /tablesdb/{databaseId}/tables/{tableId}/columns/{key}/relationship | Update relationship column |
DELETE /tablesdb/{databaseId}/tables/{tableId}/columns/{key} | Delete column |
GET /tablesdb/{databaseId}/tables/{tableId}/indexes | List indexes |
POST /tablesdb/{databaseId}/tables/{tableId}/indexes | Create index |
GET /tablesdb/{databaseId}/tables/{tableId}/indexes/{key} | Get index |
DELETE /tablesdb/{databaseId}/tables/{tableId}/indexes/{key} | Delete index |
GET /tablesdb/{databaseId}/tables/{tableId}/rows | List rows (query/pagination/cache TTL) |
POST /tablesdb/{databaseId}/tables/{tableId}/rows | Create row (single body) or create rows in batch (createRows) |
GET /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId} | Get row |
PUT /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId} | Upsert row |
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId} | Update row |
DELETE /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId} | Delete row |
PUT /tablesdb/{databaseId}/tables/{tableId}/rows | Upsert rows in batch |
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows | Update rows in batch by query |
DELETE /tablesdb/{databaseId}/tables/{tableId}/rows | Delete rows in batch by query |
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/increment | Increment column value |
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/decrement | Decrement column value |
GET /tablesdb/{databaseId}/tables/{tableId}/aggregation | Aggregate rows (count/sum/avg/min/max) |
GET /tablesdb/transactions | List transactions |
POST /tablesdb/transactions | Create transaction |
GET /tablesdb/transactions/{transactionId} | Get transaction |
PATCH /tablesdb/transactions/{transactionId} | Commit/rollback transaction |
POST /tablesdb/transactions/{transactionId}/operations | Stage transaction operations in batch |
DELETE /tablesdb/transactions/{transactionId} | Delete transaction |
GET /tablesdb/{databaseId}/schema/versions | List Schema versions |
POST /tablesdb/{databaseId}/schema/versions | Submit Schema version |
GET /tablesdb/{databaseId}/schema/versions/{versionId} | Get Schema version |
POST /tablesdb/{databaseId}/schema/rollback/{versionId} | Roll back to a specific Schema version |
DocumentsDB (/documentsdb, 31 endpoints) and legacy Databases (/databases, 68 endpoints)
DocumentsDB: database surface (5 + transactions 6 + per-database read/update/delete) and collection surface (20: collections 5, single/batch document CRUD 11, indexes 4).
Legacy Databases: database and transaction surfaces are isomorphic (5 + 6 + per-database read/update/delete); collection surface has 57 endpoints: collection CRUD (5), the
/attributes/*attribute endpoint groups (37: create and update endpoints for each of the 17 types + attribute list and per-item read/delete), indexes (4), and single/batch document CRUD withincrement/decrement(11).
The endpoint shapes of both surfaces are fully isomorphic with TablesDB; terminology mapping: table ↔ collection, row ↔ document, column ↔ attribute. There are only two differences: no /aggregation and /schema/*; in the legacy version attributes and indexes are separate endpoint groups (POST .../attributes/{type}, POST .../indexes), while the collection-level attributes array in DocumentsDB is submitted together when creating/updating a collection. See the three sections below for the complete per-endpoint specifications.
Endpoint details
Cross-table transaction state machine: create a transaction via
POST /v1/tablesdb/transactions, stage multi-table write operations withPOST .../transactions/{transactionId}/operations, and finally passcommitorrollbacktoPATCH .../transactions/{transactionId}to commit or roll back atomically.Multi-version Schema governance: after modifying column definitions or indexes on the
TablesDBsurface, callPOST /v1/tablesdb/{databaseId}/schema/versionsto solidify a snapshot of the current structure, and roll back viaPOST .../schema/rollback/{versionId}when needed.
Example conventions
The per-endpoint examples from this section onward share the following conventions; replace the example variable values to copy and run them directly:
Base URL:
https://<your-endpoint>/v1; authentication uses two request headers:X-Appwrite-Project: <YOUR_PROJECT_ID>andX-Appwrite-Key: <YOUR_API_KEY>; write requests additionally includeContent-Type: application/json.Demo values: TablesDB uses database
movie-db+ tablefilms, DocumentsDB usesnotes-db+notes, and legacy Databases usesshop-db+orders; all are demo data, not real business values.The
queriesof list endpoints is a repeatable query parameter whose elements are Query method strings. GET requests pass them viacurl -G+--data-urlencode:# Query.equal('genre','animation') → --data-urlencode 'queries[]=equal("genre","animation")' # Query.limit(25) → --data-urlencode 'queries[]=limit(25)'Others such as
orderDesc("$createdAt")andcursorAfter("…")work the same way; at most 100 entries per endpoint.The
datakeys in the row/document CRUD examples correspond to the columns/attributes of each surface's demo table (e.g.title/year/genre/rating/watchedoffilms).
Requests and Responses
Database
POST /tablesdb: bodydatabaseId(required),name(required, max 128),enabled(optional, defaults to true). Whenenabled=falseis set, the database is not accessible to users, but server-side services holding an API key can still read and write it, and the data is not lost. Returns201+database($id,name,enabled,type,$createdAt,$updatedAt).GET /tablesdb:queries(can filtername),search,total; returnsdatabaseList.PUT /tablesdb/{databaseId}:nameandenabledare both optional; returnsdatabase.DELETE /tablesdb/{databaseId}: returns204.
Tables and collections
POST /tablesdb/{databaseId}/tables:tableId+nameare required; optionalpermissions(array of permission strings, no user roles granted by default),rowSecurity(defaults to false),enabled,columns(full definitions array to create columns along with the table),indexes,comment(display name, up to 256 Unicode characters). Returns201+table($id,databaseId,name,rowSecurity,enabled,columns,indexes,bytesMax,bytesUsed, etc.).PUT .../tables/{tableId}:name,permissions,rowSecurity,enabled,columns,indexes,skipOnEmpty,comment.columnsis a full-structure submission: includingpreviousKeyallows renaming without dropping columns; an empty array combined withskipOnEmpty=falsemeans clearing all user-defined structures. Returnstable.Collections (both documentsdb / databases surfaces):
collectionId+nameare required, the rest is isomorphic (documentSecuritycorresponds torowSecurity). Returnscollection.List tables/collections:
queries(can filtername),search,total; returnstableList/collectionList.
Columns (17 types)
POST .../columns/{type} creates; PATCH .../columns/{type}/{key} updates; GET .../columns/{key} and DELETE .../columns/{key} read/delete. The create response is 202 (async column creation), the update response is 200. Column types and their specific parameters:
| type | Specific parameters (besides key and required) |
|---|---|
string | size (required, character count), default, array, encrypt (not queryable when encrypted) |
varchar | size (required, max 16381), default, array, encrypt |
text / mediumtext / longtext | default、array、encrypt |
email / url / ip | default、array |
integer | min、max、default、array |
float | min、max、default、array |
boolean | default、array |
datetime | default(ISO 8601)、array |
enum | elements (required, array of enum values), default, array |
point | default([longitude, latitude]) |
line | default (two-dimensional array of coordinate pairs) |
polygon | default (three-dimensional array of rings, first ring is the outer boundary) |
relationship | type (required: oneToOne/manyToOne/manyToMany/oneToMany), twoWay, twoWayKey, onDelete (cascade/restrict/setNull); no required |
The generic optional array denotes an array column. Common update endpoint parameters: required (required), default (required), newKey (rename). Relationship column updates go through a separate endpoint (onDelete, newKey). PATCH .../columns/{key}/comment: body comment (required; null or blank clears it), changes only the display name, usually with zero DDL.
Starting with 2.7.0, the JsonTable backend allows relaxing a required constraint in isolation (appbase PR 541): when only required is changed from true to false with name/type/size/signed/array all unchanged, the update goes straight to the adapter layer and takes effect atomically within a single transaction without rebuilding the index; the relaxation is rejected (Conflict) if submitted mixed with default, format, formatOptions, filters, or a rename/type/size change, and tightening required from false to true is also unsupported. The REST endpoints and parameter surface are unchanged; what changes is the server's acceptance boundary for such updates.
The legacy attribute endpoints (/databases/.../attributes/{type}) have parameters fully isomorphic to columns; the returned model is named attribute*.
Indexes
POST .../indexes:key(required),type(required:key/fulltext/unique/spatial),columns/attributes(required, up to 100 entries of 32 characters each),orders(optional, array ofASC/DESC),lengths(optional). Response:202+ the index model (columnIndexfor TablesDB,indexfor the rest).List:
queries(can filterkey,type,status),total;GET .../indexes/{key},DELETE .../indexes/{key}.
Rows / documents
POST .../rows: single form bodyrowId,data,permissions,transactionId(all optional;datais an object of column values); the batch form on the same endpoint (SDKcreateRows) takes a body ofrows(required) +transactionId. Returns201+roworrowList.GET .../rows:queries(query/filter/sort/paginate),transactionId(read uncommitted changes within a transaction),total,ttl(cache TTL for select queries, 0–86400 seconds, requires cache enabled on the instance); returnsrowList(total+rows[]).rowincludes$id,$sequence,$tableId,$databaseId,$createdAt,$updatedAt,$permissionsand the data columns.GET .../rows/{rowId}:queries,transactionId; returnsrow.PUT .../rows/{rowId}(upsert): updates if it exists, creates otherwise; bodydata(must include all required columns),permissions. Returns201+row.PATCH .../rows/{rowId}:datacontains only the column values to update,permissionsis optional; returnsrow.DELETE .../rows/{rowId}: bodytransactionIdis optional; returns204.Batch:
PUT .../rows(rowsrequired, may be a partial set of rows) →201+rowList;PATCH .../rows(data+queries) andDELETE .../rows(queries) →rowList(returns the affected rows).PATCH .../rows/{rowId}/{column}/increment|decrement:value(defaults to 1),max/min(throws on out-of-range),transactionId; returnsrow. Numeric columns only.Documents (both documentsdb / databases surfaces): isomorphic,
documentId/document/documentList; batch updates usedata+queries.
Aggregation (TablesDB only)
GET /tablesdb/{databaseId}/tables/{tableId}/aggregation:
| Parameter | Location | Required | Description |
|---|---|---|---|
select | query | Yes | Aggregation expressions and grouping columns, supporting count/sum/avg/min/max with AS aliases; plain columns must appear in groupBy |
groupBy | query | No | Grouping columns, up to 5 scalar columns |
queries | query | No | Filters the query only; pagination, sorting, cursors, and Query.select are not supported (they will be rejected) |
transactionId | query | No | Read uncommitted changes within a transaction |
Returns 200 + rowAggregation (total + aggregated result rows).
Transactions
POST /tablesdb/transactions: bodyttl(optional, seconds); returns201+transaction($id,status,operations,expiresAt).POST /tablesdb/transactions/{transactionId}/operations: bodyoperations(staging operation array: create/update/delete, read, upsert, incremental), can be appended across multiple calls; returns201+transaction.PATCH /tablesdb/transactions/{transactionId}:commit=truecommit orrollback=truerollback (choose one); returnstransaction.GET .../transactions,GET .../transactions/{transactionId},DELETE .../transactions/{transactionId}: list/details/delete.Both row/document read-write endpoints can pass
transactionIdto attach operations to a transaction; after the transaction expires (TTL), uncommitted operations are voided. documentsdb / databases / vectorsdb each have an isomorphic set of transaction endpoints.
Schema versions and rollback (TablesDB only)
POST /tablesdb/{databaseId}/schema/versions: bodyschema(required, complete structure JSON including thetablesarray, not a diff patch),mode(optional:migration(default, diffs against the active version and executes the migration) /baseline(adopts the current physical structure as the first active version without executing DDL)). Resubmitting the sameschemaHashreuses the existing version. Returns201(new version) or200(reused) +schemaVersion.schemaVersionmodel:$id,databaseId,schemaJson,schemaVersion,schemaHash,status,migrationPlanJson,stepsTotal,stepsCompleted,errorMessage,lastHeartbeatAt,deprecatedColumns.statuslifecycle: processing (pending/running/applying) →active/failed/deprecated; only one in-flight version is allowed per database at a time, and duplicate submissions return409.GET .../schema/versions:queries(can filter/sort byschemaVersion,status,databaseId,schemaHash),total; sorted by version number in descending order.POST /tablesdb/{databaseId}/schema/rollback/{versionId}: rolls back to a historical version; only switches structural visibility (recomputes column visibility), does not execute physical DDL or revert business data. Returns200+schemaVersion.Pre-activation validation: after applying the plan, the migration Worker re-reads the actual tables/columns/indexes; the physical structure must match the target snapshot before activation. If materialization is incomplete, it is flagged
failedand the original active version is retained. Callers should simply poll for the version's terminal state and must not replay the DDL themselves.
TablesDB per-endpoint specification (/tablesdb, 74 endpoints)
Database
database model fields:
| field | description |
|---|---|
$id | database ID |
name | name (≤128 characters) |
$createdAt / $updatedAt | creation/update time (ISO 8601) |
enabled | enabled state; disabling only blocks user-side access, API Keys can still read and write, no data loss |
type | database type: legacy / tablesdb / documentsdb / vectorsdb |
List response databaseList: total (total match count) + databases[].
GET /v1/tablesdb
Lists the databases of the current project with pagination, supporting queries filtering and search search.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
search | query | string | No | Keyword search, up to 256 characters. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/tablesdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Films")' \
--data-urlencode 'queries[]=limit(50)'Output: 200 + Models.DatabaseList.
Response example
{
"total": 1,
"databases": [
{
"$id": "movie-db",
"name": "Movies",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "tablesdb"
}
]
}POST /v1/tablesdb
Create a database.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | body | string | Yes | Unique database ID. | |
name | body | string | Yes | Name, up to 128 characters. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"databaseId": "movie-db", "name": "Movies", "enabled": true}'Output: 201 + Models.Database.
Response example
{
"$id": "movie-db",
"name": "Movies",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "tablesdb"
}GET /v1/tablesdb/{databaseId}
Get database details by ID.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. |
Call example
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Database.
Response example: isomorphic to the Models.Database example already shown above in the same group.
PUT /v1/tablesdb/{databaseId}
Update the database name and enabled state.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
name | body | string | No | Name, up to 128 characters. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/tablesdb/movie-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Films", "enabled": true}'Output: 200 + Models.Database.
Response example: isomorphic to the Models.Database example already shown above in the same group.
DELETE /v1/tablesdb/{databaseId}
Delete a database by ID.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Tables (table)
table model fields:
| field | description |
|---|---|
$id | table ID |
databaseId | parent database ID |
name | name (≤128 characters) |
comment | display name (≤256 Unicode characters, may be empty) |
$permissions | array of table-level permission strings |
enabled | enabled state; disabling only blocks user-side access |
rowSecurity | whether row-level permissions are enabled |
columns[] | column definition array (column* model, see the "Columns" section) |
indexes[] | index array (columnIndex model, see the "Indexes" section) |
bytesMax / bytesUsed | table capacity quota and bytes used |
List response tableList: total + tables[].
GET /v1/tablesdb/{databaseId}/tables
Lists tables under a database, supporting queries filtering and search search.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
search | query | string | No | Keyword search, up to 256 characters. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Films")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.TableList.
Response example
{
"total": 1,
"tables": [
{
"$id": "films",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "movie-db",
"name": "Films",
"comment": "影片库",
"enabled": true,
"rowSecurity": true,
"bytesMax": 52428800,
"bytesUsed": 20480,
"columns": [
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
},
{
"key": "year",
"comment": "Release year",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"signed": true,
"min": 1900,
"max": 2100,
"default": 2000
}
],
"indexes": [
{
"$id": "idx_genre",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_genre",
"type": "key",
"status": "available",
"error": "",
"columns": [
"genre"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}
]
}POST /v1/tablesdb/{databaseId}/tables
Create a table; the request body may carry complete columns/indexes definitions.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | body | string | Yes | Unique table ID. | |
name | body | string | Yes | Name, up to 128 characters. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
rowSecurity | body | boolean | No | Whether to enable row-level permissions; once enabled, accessing a single row requires holding either row-level or table-level permissions. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. | |
columns | body | object[] | No | Column definition array for creating columns along with the table (key and type required; type ∈ string/varchar/text/mediumtext/longtext/integer/double/boolean/datetime/point/linestring/polygon, enums use type=string + format=enum + elements). Relationship columns must go through a dedicated endpoint; including previousKey allows renaming without deleting the column. | |
indexes | body | object[] | No | Definition array for creating indexes along with the table/collection (key, type, attributes required; orders, lengths optional). | |
comment | body | string | No | Display name/comment, up to 256 Unicode characters; leading and trailing whitespace is trimmed, null or whitespace clears the comment. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"tableId": "films", "name": "Films", "permissions": ["read(\"any\")"], "rowSecurity": true, "columns": [{"key": "title", "type": "string", "size": 128, "required": true}, {"key": "year", "type": "integer"}, {"key": "genre", "type": "string", "size": 16, "format": "enum", "elements": ["sci-fi", "drama", "animation"]}, {"key": "rating", "type": "double", "required": false}], "indexes": [{"key": "idx_title", "type": "fulltext", "attributes": ["title"]}], "comment": "影片库"}'Output: 201 + Models.Table.
Response example
{
"$id": "films",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "movie-db",
"name": "Films",
"comment": "影片库",
"enabled": true,
"rowSecurity": true,
"bytesMax": 52428800,
"bytesUsed": 20480,
"columns": [
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
},
{
"key": "year",
"comment": "Release year",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"signed": true,
"min": 1900,
"max": 2100,
"default": 2000
}
],
"indexes": [
{
"$id": "idx_genre",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_genre",
"type": "key",
"status": "available",
"error": "",
"columns": [
"genre"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/tablesdb/{databaseId}/tables/{tableId}
Get table details (including column and index definitions and capacity information).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. |
Call example
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Table.
Response example: isomorphic to the Models.Table example already shown above in the same group.
PUT /v1/tablesdb/{databaseId}/tables/{tableId}
Update table attributes, or submit the full table structure (columns/indexes arrays).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
name | body | string | No | Name, up to 128 characters. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
rowSecurity | body | boolean | No | Whether to enable row-level permissions; once enabled, accessing a single row requires holding either row-level or table-level permissions. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. | |
columns | body | object[] | No | Column definition array for creating columns along with the table (key and type required; type ∈ string/varchar/text/mediumtext/longtext/integer/double/boolean/datetime/point/linestring/polygon, enums use type=string + format=enum + elements). Relationship columns must go through a dedicated endpoint; including previousKey allows renaming without deleting the column. | |
indexes | body | object[] | No | Definition array for creating indexes along with the table/collection (key, type, attributes required; orders, lengths optional). | |
skipOnEmpty | body | boolean | No | When set to true, empty columns/indexes arrays are ignored; when false (default), empty arrays mean clearing all user-defined structure. | |
comment | body | string | No | Display name/comment, up to 256 Unicode characters; leading and trailing whitespace is trimmed, null or whitespace clears the comment. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Films", "enabled": true, "comment": "影片库"}'Output: 200 + Models.Table.
Response example: isomorphic to the Models.Table example already shown above in the same group.
DELETE /v1/tablesdb/{databaseId}/tables/{tableId}
Delete a table.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Columns (column, 17 types)
Common fields of the TablesDB column model (Models.ColumnString … Models.ColumnRelationship):
| field | description |
|---|---|
key | column key |
comment | display name/comment |
type | type identifier (the type of a enum column is still string, distinguished by format: "enum" + elements) |
status | available / processing / deleting / stuck / failed |
error | failure reason (empty string if no error) |
required / array | required / whether an array column |
$createdAt / $updatedAt | creation/update time |
Lifecycle notes:
Creation returns
202(asynchronous DDL);statusgoes fromprocessing→available(orfailed); pollGET …/{key}untilavailablebefore writing data that depends on the column.Update endpoints (
PATCH …/{type}/{key}) return200synchronously; common parameters arerequired,default,newKey(rename), and each type has its own specific parameters (see each endpoint's table).defaultandrequiredare mutually exclusive; before changingrequired, ensure all existing rows have values.
GET /v1/tablesdb/{databaseId}/tables/{tableId}/columns
List all columns of a table (including column creation progress status).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(100)'Output: 200 + Models.ColumnList.
Response example
{
"total": 2,
"columns": [
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
},
{
"key": "year",
"comment": "Release year",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"signed": true,
"min": 1900,
"max": 2100,
"default": 2000
}
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/boolean
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | boolean | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/boolean" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "watched", "required": false, "default": false}'Output: 202 + Models.ColumnBoolean; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "watched",
"comment": "Watched flag",
"type": "boolean",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/datetime
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/datetime" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "releaseDate", "required": false, "default": "1970-01-01T00:00:00.000+00:00"}'Output: 202 + Models.ColumnDatetime; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "releaseDate",
"comment": "Release date",
"type": "datetime",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "datetime",
"default": "1970-01-01T00:00:00.000+00:00"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/email
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/email" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "contactEmail", "required": false}'Output: 202 + Models.ColumnEmail; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "contactEmail",
"comment": "Contact email",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"format": "email",
"default": "default@example.com"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/enum
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
elements | body | string[] | Yes | Array of enum values (non-empty string array); default must be taken from it. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/enum" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "genre", "elements": ["sci-fi", "drama", "animation"], "required": false, "default": "drama"}'Output: 202 + Models.ColumnEnum; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "genre",
"comment": "Genre",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 16,
"elements": [
"sci-fi",
"drama",
"animation"
],
"format": "enum",
"default": "drama"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/float
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
min | body | number | No | Minimum lower bound. | |
max | body | number | No | Maximum upper bound. | |
default | body | number | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/float" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "rating", "min": 0, "max": 10, "required": false, "default": 0}'Output: 202 + Models.ColumnFloat; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "rating",
"comment": "Rating 0-10",
"type": "double",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 0,
"max": 10,
"default": 0
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/integer
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
min | body | integer | No | Minimum lower bound. | |
max | body | integer | No | Maximum upper bound. | |
default | body | integer | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/integer" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "year", "min": 1900, "max": 2100, "required": false, "default": 2000}'Output: 202 + Models.ColumnInteger; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "year",
"comment": "Release year",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"signed": true,
"min": 1900,
"max": 2100,
"default": 2000
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/ip
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/ip" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "originIp", "required": false}'Output: 202 + Models.ColumnIp; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "originIp",
"comment": "Origin IP",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32,
"format": "ip",
"default": "192.0.2.0"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/line
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/line" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "route", "required": false}'Output: 202 + Models.ColumnLine; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "route",
"comment": "Route line",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
[
116.4,
39.9
],
[
116.5,
40.0
]
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/longtext
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/longtext" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "plot", "required": false}'Output: 202 + Models.ColumnLongtext; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "plot",
"comment": "Full plot",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 2147483647,
"default": "default",
"encrypt": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/mediumtext
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/mediumtext" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "notes", "required": false}'Output: 202 + Models.ColumnMediumtext; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "notes",
"comment": "Internal notes",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 16777215,
"default": "default",
"encrypt": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/point
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/point" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "origin", "required": false}'Output: 202 + Models.ColumnPoint; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "origin",
"comment": "Origin coordinate",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
116.4,
39.9
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/polygon
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/polygon" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "area", "required": false}'Output: 202 + Models.ColumnPolygon; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "area",
"comment": "Coverage area",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
[
[
116.4,
39.9
],
[
116.5,
39.9
],
[
116.5,
40.0
],
[
116.4,
39.9
]
]
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/relationship
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
relatedTableId | body | string | Yes | ID of the related table. Once a relationship column is created, the opposite-side table cannot be changed. | |
type | body | string | Yes | Enum oneToOne / manyToOne / manyToMany / oneToMany | Relationship type: oneToOne / manyToOne / manyToMany / oneToMany. |
twoWay | body | boolean | No | Whether the relationship is two-way. For two-way relationships, twoWayKey must be provided. | |
key | body | string | No | Column/attribute key. Character constraints are the same as for resource IDs; must be unique within the table/collection. | |
twoWayKey | body | string | No | The reverse column key on the opposite-side table/collection for a two-way relationship. | |
onDelete | body | string | No | Enum cascade / restrict / setNull | Constraint when related rows are deleted: cascade (cascade delete) / restrict (block deletion) / setNull (set null). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/relationship" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "studio", "relatedTableId": "studios", "type": "manyToOne", "onDelete": "restrict"}'Output: 202 + Models.ColumnRelationship; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "studio",
"comment": "Studio relation",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"relatedTable": "studios",
"relationType": "manyToOne",
"twoWay": false,
"twoWayKey": "",
"onDelete": "restrict",
"side": "parent|child"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/string
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
size | body | integer | Yes | Maximum number of characters. Required at creation for string/varchar; varchar maximum is 16381. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/string" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "title", "size": 128, "required": true}'Output: 202 + Models.ColumnString; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/text
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/text" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "synopsis", "required": false}'Output: 202 + Models.ColumnText; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "synopsis",
"comment": "Synopsis",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 65535,
"default": "default",
"encrypt": false
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/url
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/url" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "trailerUrl", "required": false}'Output: 202 + Models.ColumnUrl; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "trailerUrl",
"comment": "Trailer URL",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"format": "url",
"default": "https://example.com"
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/columns/varchar
Create a column (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
size | body | integer | Yes | Maximum number of characters. Required at creation for string/varchar; varchar maximum is 16381. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/varchar" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "code", "size": 32, "required": false, "default": "NEW"}'Output: 202 + Models.ColumnVarchar; for asynchronous column creation: status starts at processing, poll GET …/columns/{key} until available before writing.
Response example
{
"key": "code",
"comment": "Short code",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32,
"default": "NEW",
"encrypt": false
}PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/boolean/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | boolean | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/boolean/watched" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": false, "required": false}'Output: 200 + Models.ColumnBoolean; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnBoolean example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/datetime/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/datetime/releaseDate" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": "1970-01-01T00:00:00.000+00:00", "required": false}'Output: 200 + Models.ColumnDatetime; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnDatetime example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/email/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/email/contactEmail" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.ColumnEmail; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnEmail example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/enum/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
elements | body | string[] | Yes | Array of enum values (non-empty string array); default must be taken from it. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/enum/genre" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"elements": ["sci-fi", "drama", "animation", "documentary"], "default": "drama", "required": false}'Output: 200 + Models.ColumnEnum; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnEnum example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/float/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
min | body | number | No | Minimum lower bound. | |
max | body | number | No | Maximum upper bound. | |
default | body | number | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/float/rating" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"min": 0, "max": 10, "required": false}'Output: 200 + Models.ColumnFloat; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnFloat example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/integer/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
min | body | integer | No | Minimum lower bound. | |
max | body | integer | No | Maximum upper bound. | |
default | body | integer | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/integer/year" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"min": 1900, "max": 2100, "required": false}'Output: 200 + Models.ColumnInteger; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnInteger example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/ip/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/ip/originIp" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.ColumnIp; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnIp example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/line/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/line/route" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'Output: 200 + Models.ColumnLine; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnLine example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/longtext/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/longtext/plot" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.ColumnLongtext; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnLongtext example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/mediumtext/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/mediumtext/notes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.ColumnMediumtext; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnMediumtext example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/point/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/point/origin" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'Output: 200 + Models.ColumnPoint; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnPoint example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/polygon/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/polygon/area" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'Output: 200 + Models.ColumnPolygon; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnPolygon example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/string/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
size | body | integer | No | Maximum number of characters. Required at creation for string/varchar; varchar maximum is 16381. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/string/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"size": 256, "required": false}'Output: 200 + Models.ColumnString; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnString example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/text/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/text/synopsis" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.ColumnText; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnText example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/url/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/url/trailerUrl" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.ColumnUrl; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnUrl example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/varchar/{key}
Update a column (required flag, default value, bounds; use newKey to rename).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
size | body | integer | No | Maximum number of characters. Required at creation for string/varchar; varchar maximum is 16381. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/varchar/code" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"size": 64, "required": false}'Output: 200 + Models.ColumnVarchar; updates synchronously and returns the updated column model.
Response example: isomorphic to the Models.ColumnVarchar example already shown above in the same group.
GET /v1/tablesdb/{databaseId}/tables/{tableId}/columns/{key}
Get the definition and status of a single column.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + any Models.Column* type model; the response is any column* / attribute* type model (using string as an example).
Response example (using string type as an example)
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/{key}/comment
Update the column comment (display name); only changes metadata, usually zero DDL.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
comment | body | string | Yes | Display name/comment, up to 256 Unicode characters; leading and trailing whitespace is trimmed, and null or whitespace clears the comment. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/title/comment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"comment": "影片库"}'Output: 200 + any Models.Column* type model; the response is the complete updated model of the column (using string as an example).
Response example (using string type as an example)
{
"key": "title",
"comment": "Movie title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/columns/{key}/relationship
Update the relationship column's delete constraint (onDelete) or rename it (newKey).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
onDelete | body | string | No | Enum cascade / restrict / setNull | Constraint when related rows are deleted: cascade (cascade delete) / restrict (block deletion) / setNull (set null). |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/studio/relationship" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"onDelete": "cascade"}'Output: 200 + Models.ColumnRelationship.
Response example: isomorphic to the Models.ColumnRelationship example already shown above in the same group.
DELETE /v1/tablesdb/{databaseId}/tables/{tableId}/columns/{key}
Delete a column (asynchronous).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/columns/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; asynchronous deletion; no response body.
Indexes (index)
columnIndex model fields:
| field | description |
|---|---|
$id | Index ID |
key | Index key |
type | key / fulltext / unique / spatial |
status | available / processing / deleting / stuck / failed |
error | Failure reason |
columns[] | Array of column keys participating in the index |
lengths[] | Prefix length of each column (positionally matched with columns) |
orders[] | Sort direction of each column, ASC/DESC (positionally matched with columns) |
Creation/deletion is asynchronous (202); poll GET …/indexes/{key} until status=available. List responses are total + indexes[].
GET /v1/tablesdb/{databaseId}/tables/{tableId}/indexes
List table indexes (filterable by key/type/status).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("type","key")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.ColumnIndexList.
Response example
{
"total": 1,
"indexes": [
{
"$id": "idx_genre",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_genre",
"type": "key",
"status": "available",
"error": "",
"columns": [
"genre"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/tablesdb/{databaseId}/tables/{tableId}/indexes/{key}
Get the index definition and status.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/indexes/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.ColumnIndex.
Response example: isomorphic to the Models.ColumnIndex example already shown above in the same group.
POST /v1/tablesdb/{databaseId}/tables/{tableId}/indexes
Create an index (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
type | body | string | Yes | Enum key / fulltext / unique / spatial | Index type: key (regular) / fulltext (fulltext) / unique (unique) / spatial (spatial). |
columns | body | string[] | Yes | Array of column keys participating in the index; orders/lengths correspond to it positionally. | |
orders | body | string[] | No | Sort direction of each indexed column: ASC / DESC (positionally matched with columns). | |
lengths | body | integer[] | No | Prefix length of each indexed column (integer array, positionally matched with columns). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "idx_genre", "type": "key", "columns": ["genre"], "orders": ["ASC"]}'Output: 202 + Models.ColumnIndex; index creation is asynchronous: poll GET …/indexes/{key} until available.
Response example
{
"$id": "idx_genre",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_genre",
"type": "key",
"status": "available",
"error": "",
"columns": [
"genre"
],
"lengths": [],
"orders": [
"ASC"
]
}DELETE /v1/tablesdb/{databaseId}/tables/{tableId}/indexes/{key}
Delete an index.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/indexes/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Rows (row)
Row model fields:
| field | description |
|---|---|
$id | Row ID |
$sequence | Row sequence number (monotonically increasing within the same table) |
$tableId | ID of the owning table |
$databaseId | parent database ID |
$createdAt / $updatedAt | creation/update time |
$permissions | Array of row-level permission strings |
All keys other than system fields are data columns (key = column key; value type depends on the column definition and array). List responses are rowList: total + rows[]; the query parameter total=false skips counting, and ttl (0–86400 seconds) enables response caching for select queries (requires the instance to have caching enabled).
GET /v1/tablesdb/{databaseId}/tables/{tableId}/rows
Query rows: filtering/sorting/pagination, supports uncommitted changes within a read transaction and cache TTL.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | query | string | No | Transaction ID. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
ttl | query | integer | No | Default 0 | Response cache TTL for select queries (0–86400 seconds); requires the instance to have caching enabled; 0 means no caching. |
Call example
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("genre","animation")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.RowList.
Response example
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}POST /v1/tablesdb/{databaseId}/tables/{tableId}/rows
Create rows; the same endpoint hosts both the single-row (createRow) and batch (createRows) SDK methods. (SDK: tablesDB.createRow / tablesDB.createRows)
Input (createRow, single)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rowId | body | string | Yes | Unique row ID. Custom or generated by ID.unique(); characters a-z, A-Z, 0-9, ., -, _; must not start with a special character; up to 36 characters. | |
data | body | object | Yes | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID: attaches this write to a transaction. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}, "rowId": "snow-white"}'Output: 201 + Models.Row (fields as described at the beginning of this group).
Response example
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
}Input (createRows, batch)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rows | body | object[] | Yes | Array of row data objects, which may contain partial fields (used with batch upsert). | |
transactionId | body | string | No | Transaction ID: attaches the batch write to a transaction. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"rows": [{"rowId": "snow-white", "data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}}, {"rowId": "bambi", "data": {"title": "Bambi", "year": 1942, "genre": "animation", "rating": 7.3, "watched": false}}]}'Output: 201 + Models.RowList (total + array; pagination structure as described at the beginning of this group).
Response example
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}PUT /v1/tablesdb/{databaseId}/tables/{tableId}/rows
Batch upsert rows (the rows array may contain partial rows). (SDK: tablesDB.upsertRows)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rows | body | object[] | Yes | Array of row data objects, which may contain partial fields (used with batch upsert). | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"rows": [{"rowId": "snow-white", "data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}}, {"rowId": "bambi", "data": {"title": "Bambi", "year": 1942, "genre": "animation", "rating": 7.3, "watched": false}}]}'Output: 201 + Models.RowList.
Response example
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/rows
Batch update rows by queries and return the affected rows.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
queries | body | string[] | No | Array of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"rating": 8.4}, "queries": ["equal(\"watched\",false)"]}'Output: 200 + Models.RowList.
Response example
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}DELETE /v1/tablesdb/{databaseId}/tables/{tableId}/rows
Batch delete rows by queries and return the affected rows.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
queries | body | string[] | No | Array of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"queries": ["lessThan(\"rating\",5)"]}'Output: 200 + Models.RowList.
Response example
{
"total": 2,
"rows": [
{
"$id": "snow-white",
"$sequence": "1",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Snow White and the Seven Dwarfs",
"year": 1937,
"genre": "animation",
"rating": 7.9,
"watched": true
},
{
"$id": "bambi",
"$sequence": "2",
"$tableId": "films",
"$databaseId": "movie-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Bambi",
"year": 1942,
"genre": "animation",
"rating": 7.3,
"watched": false
}
]
}GET /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}
Get a single row by ID.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rowId | path | string | Yes | Unique row ID. Custom or generated by ID.unique(); characters a-z, A-Z, 0-9, ., -, _; must not start with a special character; up to 36 characters. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | query | string | No | Transaction ID. |
Call example
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Row.
Response example: isomorphic to the Models.Row example already shown above in the same group.
PUT /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}
Upsert a row: update if it exists, create if it does not. (SDK: tablesDB.upsertRow)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rowId | path | string | Yes | Unique row ID. Custom or generated by ID.unique(); characters a-z, A-Z, 0-9, ., -, _; must not start with a special character; up to 36 characters. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}, "permissions": ["read(\"any\")"]}'Output: 201 + Models.Row.
Response example: isomorphic to the Models.Row example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}
Partially update a row (data contains only the columns to update).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rowId | path | string | Yes | Unique row ID. Custom or generated by ID.unique(); characters a-z, A-Z, 0-9, ., -, _; must not start with a special character; up to 36 characters. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"rating": 8.4}}'Output: 200 + Models.Row.
Response example: isomorphic to the Models.Row example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/decrement
Atomically decrement a numeric column (with an optional lower bound min).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rowId | path | string | Yes | Unique row ID. Custom or generated by ID.unique(); characters a-z, A-Z, 0-9, ., -, _; must not start with a special character; up to 36 characters. | |
column | path | string | Yes | Column key (path parameter). | |
value | body | number | No | Increment value (number), default 1. | |
min | body | number | No | Lower bound for the decrement; an out-of-bounds value raises an error and is not written. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white/rating/decrement" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 1, "min": 0}'Output: 200 + Models.Row; returns the complete row after decrementing.
Response example: isomorphic to the Models.Row example already shown above in the same group.
PATCH /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/increment
Atomically increment a numeric column (with an optional upper bound max).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rowId | path | string | Yes | Unique row ID. Custom or generated by ID.unique(); characters a-z, A-Z, 0-9, ., -, _; must not start with a special character; up to 36 characters. | |
column | path | string | Yes | Column key (path parameter). | |
value | body | number | No | Increment value (number), default 1. | |
max | body | number | No | Upper bound for the increment; an out-of-bounds value raises an error and is not written. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white/rating/increment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 1, "max": 10}'Output: 200 + Models.Row; returns the complete row after incrementing.
Response example: isomorphic to the Models.Row example already shown above in the same group.
DELETE /v1/tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}
Delete a row; can be attached to a transaction.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
rowId | path | string | Yes | Unique row ID. Custom or generated by ID.unique(); characters a-z, A-Z, 0-9, ., -, _; must not start with a special character; up to 36 characters. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/rows/snow-white" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Aggregation (TablesDB only)
Response rowAggregation: total (number of groups) + rows[], where elements are { "group": {分组列值}, "values": {聚合值} } with keys from aliases in select/groupBy. Only filter-type queries is supported; pagination, sorting, cursors, and Query.select will be rejected.
GET /v1/tablesdb/{databaseId}/tables/{tableId}/aggregation
Row aggregate statistics (count/sum/avg/min/max, optionally grouped by column).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
tableId | path | string | Yes | Unique table ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
groupBy | query | string[] | No | Grouping columns, up to 5 scalar columns. | |
select | query | string[] | Yes | Aggregate expressions and grouping columns. Supports count/sum/avg/min/max with AS aliases; ordinary columns must also appear in groupBy. | |
transactionId | query | string | No | Transaction ID. |
Call example
curl -G \
"https://<your-endpoint>/v1/tablesdb/movie-db/tables/films/aggregation" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'select[]=count(*) AS totalRows' \
--data-urlencode 'select[]=genre' \
--data-urlencode 'groupBy[]=genre'Output: 200 + Models.RowAggregation.
Response example
{
"total": 1,
"rows": [
{
"group": {
"genre": "animation"
},
"values": {
"totalRows": 2
}
}
]
}Transactions (transaction)
transaction model fields:
| field | description |
|---|---|
$id | Transaction ID, used by row/document endpoints to pass transactionId |
$createdAt / $updatedAt | creation/update time |
status | pending → committing → committed / rolled_back / failed |
operations | Number of staged operations |
expiresAt | Expiration time; uncommitted operations are voided after expiration |
Element structure of POST …/operations for operations[] (databaseId, action, and tableId are required; data is the operation payload):
| action | additional required | description |
|---|---|---|
create / update / upsert / increment / decrement | rowId, data | single-row operation; data is an object of column values |
delete | rowId | deletes a single row |
bulkCreate / bulkUpdate / bulkUpsert / bulkDelete | data | batch operations; data is an array of objects |
Operations are appended across multiple calls and take no effect until commit; the row/document read-write endpoints can also take transactionId directly to attach a single operation to a transaction.
GET /v1/tablesdb/transactions
List transactions with pagination.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. |
Call example
curl -G \
"https://<your-endpoint>/v1/tablesdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(10)'Output: 200 + Models.TransactionList.
Response example
{
"total": 1,
"transactions": [
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 2,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}
]
}POST /v1/tablesdb/transactions
Create a transaction and return the transaction ID; the optional ttl controls its validity period.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
ttl | body | integer | No | Transaction validity period in seconds; unstaged operations expire and become void after this. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"ttl": 60}'Output: 201 + Models.Transaction.
Response example
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 0,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}GET /v1/tablesdb/transactions/{transactionId}
Get transaction status and staged operation counts.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. |
Call example
curl \
"https://<your-endpoint>/v1/tablesdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
POST /v1/tablesdb/transactions/{transactionId}/operations
Batch-stage operations into a transaction; can be called multiple times to append.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. | |
operations | body | object[] | No | Array of staged operations; element structure is shown at the start of this group; can be appended across multiple calls. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/transactions/259125845563242502/operations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"operations": [{"databaseId": "movie-db", "tableId": "films", "rowId": "snow-white", "action": "create", "data": {"title": "Snow White and the Seven Dwarfs", "year": 1937, "genre": "animation", "rating": 7.9, "watched": true}}, {"databaseId": "movie-db", "tableId": "films", "rowId": "bambi", "action": "delete"}]}'Output: 201 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
PATCH /v1/tablesdb/transactions/{transactionId}
Commit (commit=true) or roll back (rollback=true) the transaction; only one of the two may be chosen.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. | |
commit | body | boolean | No | Set to true to commit the transaction (mutually exclusive with rollback). | |
rollback | body | boolean | No | Set to true to roll back the transaction (mutually exclusive with commit). |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/tablesdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"commit": true}'Output: 200 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
DELETE /v1/tablesdb/transactions/{transactionId}
Delete the transaction (discarding its staged operations).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/tablesdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Schema versions and rollback (TablesDB only)
schemaVersion model fields:
| field | description |
|---|---|
$id | Version record ID |
databaseId | parent database ID |
schemaVersion | Monotonically increasing version number |
schemaJson | The complete structure JSON at commit time (snapshot) |
schemaHash | SHA-256 of the structure specification JSON, used for idempotency |
status | pending / running / applying → active / failed; becomes deprecated after being superseded by a new version |
migrationPlanJson | Migration plan (grouped by additive / compatible / destructive) |
stepsTotal / stepsCompleted | Total number of DDL steps / completed count |
errorMessage | Failure reason |
lastHeartbeatAt | Latest migration Worker heartbeat |
deprecatedColumns | Columns deprecated in this migration |
Only one in-flight version is allowed at a time per database (duplicate submissions return 409); after the migration Worker applies the plan, it re-reads the actual structure to verify, setting active only if consistent; otherwise it sets failed and keeps the original active version. Callers can poll GET …/schema/versions/{versionId} until a terminal state and must not replay the DDL themselves.
GET /v1/tablesdb/{databaseId}/schema/versions
List Schema versions (by version number in descending order by default).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/schema/versions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.SchemaVersionList.
Response example
{
"total": 1,
"schemaVersions": [
{
"$id": "5e5ea5c16897e",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"databaseId": "movie-db",
"schemaJson": "{\"tables\":[{\"id\":\"films\",\"columns\":[{\"key\":\"title\",\"type\":\"string\",\"size\":128,\"required\":true},{\"key\":\"year\",\"type\":\"integer\"}],\"indexes\":[{\"key\":\"idx_title\",\"type\":\"fulltext\",\"attributes\":[\"title\"]}]}]}",
"schemaVersion": 1,
"schemaHash": "a3f1c2d4e5b607189accd3f2b1a04e55",
"status": "active",
"migrationPlanJson": "{\"additive\":[],\"compatible\":[],\"destructive\":[]}",
"stepsTotal": 2,
"stepsCompleted": 2,
"errorMessage": "",
"lastHeartbeatAt": "2026-01-12T08:00:00.000+00:00",
"deprecatedColumns": []
}
]
}GET /v1/tablesdb/{databaseId}/schema/versions/{versionId}
Query Schema version status and migration progress.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
versionId | path | string | Yes | Target Schema version ID. |
Call example
curl \
"https://<your-endpoint>/v1/tablesdb/movie-db/schema/versions/1" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.SchemaVersion.
Response example: isomorphic to the Models.SchemaVersion example already shown above in the same group.
POST /v1/tablesdb/{databaseId}/schema/rollback/{versionId}
Roll back to a specified Schema version (only switches structure visibility; performs no physical DDL and deletes no data).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
versionId | path | string | Yes | Target Schema version ID. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/schema/rollback/1" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.SchemaVersion.
Response example: isomorphic to the Models.SchemaVersion example already shown above in the same group.
POST /v1/tablesdb/{databaseId}/schema/versions
Submit the complete Schema: generates a migration plan and executes it; identical schemaHash is idempotently reused as the existing version.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
schema | body | object | Yes | Complete structure definition JSON object, including the tables array (a full database snapshot, not a diff patch). | |
mode | body | string | No | enum migration / baseline | migration (default: diffs against the active version and executes the migration) or baseline (adopts the current physical structure as the first active version without executing DDL). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/tablesdb/movie-db/schema/versions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"schema": {"tables": [{"id": "films", "columns": [{"key": "title", "type": "string", "size": 128, "required": true}, {"key": "year", "type": "integer"}], "indexes": [{"key": "idx_title", "type": "fulltext", "attributes": ["title"]}]}]}, "mode": "migration"}'Output: 201 (new version) / 200 (idempotent reuse when schemaHash is identical) + Models.SchemaVersion.
Response example
{
"$id": "5e5ea5c16897e",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"databaseId": "movie-db",
"schemaJson": "{\"tables\":[{\"id\":\"films\",\"columns\":[{\"key\":\"title\",\"type\":\"string\",\"size\":128,\"required\":true},{\"key\":\"year\",\"type\":\"integer\"}],\"indexes\":[{\"key\":\"idx_title\",\"type\":\"fulltext\",\"attributes\":[\"title\"]}]}]}",
"schemaVersion": 1,
"schemaHash": "a3f1c2d4e5b607189accd3f2b1a04e55",
"status": "active",
"migrationPlanJson": "{\"additive\":[],\"compatible\":[],\"destructive\":[]}",
"stepsTotal": 2,
"stepsCompleted": 2,
"errorMessage": "",
"lastHeartbeatAt": "2026-01-12T08:00:00.000+00:00",
"deprecatedColumns": []
}DocumentsDB per-endpoint specification (/documentsdb, 31 endpoints)
Database
database model fields:
| field | description |
|---|---|
$id | database ID |
name | name (≤128 characters) |
$createdAt / $updatedAt | creation/update time (ISO 8601) |
enabled | enabled state; disabling only blocks user-side access, API Keys can still read and write, no data loss |
type | database type: legacy / tablesdb / documentsdb / vectorsdb |
List response databaseList: total (total match count) + databases[].
GET /v1/documentsdb
Lists the databases of the current project with pagination, supporting queries filtering and search search.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
search | query | string | No | Keyword search, up to 256 characters. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/documentsdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Notes")' \
--data-urlencode 'queries[]=limit(50)'Output: 200 + Models.DatabaseList.
Response example
{
"total": 1,
"databases": [
{
"$id": "notes-db",
"name": "Notes",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "documentsdb"
}
]
}POST /v1/documentsdb
Create a database.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | body | string | Yes | Unique database ID. | |
name | body | string | Yes | Name, up to 128 characters. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/documentsdb" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"databaseId": "notes-db", "name": "Notes", "enabled": true}'Output: 201 + Models.Database.
Response example
{
"$id": "notes-db",
"name": "Notes",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "documentsdb"
}GET /v1/documentsdb/{databaseId}
Get database details by ID.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. |
Call example
curl \
"https://<your-endpoint>/v1/documentsdb/notes-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Database.
Response example: isomorphic to the Models.Database example already shown above in the same group.
PUT /v1/documentsdb/{databaseId}
Update the database name and enabled state.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
name | body | string | Yes | Name, up to 128 characters. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/documentsdb/notes-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Notes", "enabled": true}'Output: 200 + Models.Database.
Response example: isomorphic to the Models.Database example already shown above in the same group.
DELETE /v1/documentsdb/{databaseId}
Delete a database by ID.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Collections (collection)
collection model fields:
| field | description |
|---|---|
$id | Collection ID |
databaseId | parent database ID |
name | name (≤128 characters) |
$permissions | Array of collection-level permission strings |
enabled | enabled state; disabling only blocks user-side access |
documentSecurity | Whether document-level permissions are enabled |
attributes[] | Array of attribute definitions (attribute* model; see the Attributes section) |
indexes[] | index array (index model, see the "Indexes" section) |
bytesMax / bytesUsed | Capacity quota and used bytes |
List response collectionList: total + collections[].
GET /v1/documentsdb/{databaseId}/collections
List collections in the database, supporting queries filtering and search search.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
search | query | string | No | Keyword search, up to 256 characters. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Notes")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.CollectionList.
Response example
{
"total": 1,
"collections": [
{
"$id": "notes",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "notes-db",
"name": "Notes",
"enabled": true,
"documentSecurity": false,
"bytesMax": 52428800,
"bytesUsed": 20480,
"attributes": [
{
"key": "title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 256,
"encrypt": false
},
{
"key": "color",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"amber",
"ivory",
"sage"
],
"format": "enum",
"size": 16
},
{
"key": "labels",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": true,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32
}
],
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}
]
}POST /v1/documentsdb/{databaseId}/collections
Create a collection; the request body may carry the complete attributes/indexes definitions.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | body | string | Yes | Collection unique ID. | |
name | body | string | Yes | Name, up to 128 characters. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
documentSecurity | body | boolean | No | Whether document-level permissions are enabled; once enabled, accessing a single document requires holding either a document-level or a collection-level permission. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. | |
attributes | body | object[] | No | Array of attribute definitions created together with the collection; fields are the same as TablesDB's columns (key and type required, etc.). | |
indexes | body | object[] | No | Definition array for creating indexes along with the table/collection (key, type, attributes required; orders, lengths optional). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"collectionId": "notes", "name": "Notes", "documentSecurity": false, "attributes": [{"key": "title", "type": "string", "size": 256, "required": true}, {"key": "color", "type": "string", "size": 16, "format": "enum", "elements": ["amber", "ivory", "sage"]}, {"key": "labels", "type": "string", "size": 32, "array": true}], "indexes": [{"key": "idx_title", "type": "fulltext", "attributes": ["title"]}]}'Output: 201 + Models.Collection.
Response example
{
"$id": "notes",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "notes-db",
"name": "Notes",
"enabled": true,
"documentSecurity": false,
"bytesMax": 52428800,
"bytesUsed": 20480,
"attributes": [
{
"key": "title",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 256,
"encrypt": false
},
{
"key": "color",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"amber",
"ivory",
"sage"
],
"format": "enum",
"size": 16
},
{
"key": "labels",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": true,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32
}
],
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/documentsdb/{databaseId}/collections/{collectionId}
Get collection details (including attribute and index definitions).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. |
Call example
curl \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Collection.
Response example: isomorphic to the Models.Collection example already shown above in the same group.
PUT /v1/documentsdb/{databaseId}/collections/{collectionId}
Update collection attributes, or submit the whole collection structure (attributes/indexes arrays).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
name | body | string | Yes | Name, up to 128 characters. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
documentSecurity | body | boolean | No | Whether document-level permissions are enabled; once enabled, accessing a single document requires holding either a document-level or a collection-level permission. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Notes", "enabled": true}'Output: 200 + Models.Collection.
Response example: isomorphic to the Models.Collection example already shown above in the same group.
DELETE /v1/documentsdb/{databaseId}/collections/{collectionId}
Delete the collection.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Indexes (index)
index model fields:
| field | description |
|---|---|
$id | Index ID |
key | Index key |
type | key / fulltext / unique / spatial |
status | available / processing / deleting / stuck / failed |
error | Failure reason |
attributes[] | Array of attribute keys participating in the index |
lengths[] | Prefix lengths per column (positionally aligned with the attributes) |
orders[] | Sort direction per column ASC/DESC (positionally aligned with the attributes) |
Creation/deletion is asynchronous (202); poll GET …/indexes/{key} until status=available. List responses are total + indexes[].
GET /v1/documentsdb/{databaseId}/collections/{collectionId}/indexes
List collection indexes (filterable by key/type/status).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("type","key")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.IndexList.
Response example
{
"total": 1,
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/documentsdb/{databaseId}/collections/{collectionId}/indexes/{key}
Get the index definition and status.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/indexes/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Index.
Response example: isomorphic to the Models.Index example already shown above in the same group.
POST /v1/documentsdb/{databaseId}/collections/{collectionId}/indexes
Create an index (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
type | body | string | Yes | Enum key / fulltext / unique / spatial | Index type: key (regular) / fulltext (fulltext) / unique (unique) / spatial (spatial). |
attributes | body | string[] | Yes | Array of attribute keys participating in the index; orders/lengths are positionally aligned with it. | |
orders | body | string[] | No | Sort direction of each indexed column: ASC / DESC (positionally matched with columns). | |
lengths | body | integer[] | No | Prefix length of each indexed column (integer array, positionally matched with columns). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "idx_status", "type": "key", "attributes": ["status"], "orders": ["ASC"]}'Output: 202 + Models.Index; index creation is asynchronous: poll GET …/indexes/{key} until available.
Response example
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}DELETE /v1/documentsdb/{databaseId}/collections/{collectionId}/indexes/{key}
Delete an index.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/indexes/title" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Documents (document)
Document model fields:
| field | description |
|---|---|
$id | Document ID |
$sequence | Document sequence number (monotonically increasing within the same collection) |
$collectionId | Owning collection ID |
$databaseId | parent database ID |
$createdAt / $updatedAt | creation/update time |
$permissions | Array of document-level permission strings |
All keys other than system fields are data attributes (key = attribute key). List responses documentList: total + documents[]; the query parameter total=false skips counting, and ttl (0–86400 seconds) enables response caching for select queries (requires the instance to have it enabled).
GET /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
Query documents: filtering/sorting/pagination, with support for reading uncommitted changes within a transaction and a cache TTL.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | query | string | No | Transaction ID. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
ttl | query | integer | No | Default 0 | Response cache TTL for select queries (0–86400 seconds); requires the instance to have caching enabled; 0 means no caching. |
Call example
curl -G \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("color","amber")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.DocumentList.
Response example
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}POST /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
Create documents; a single endpoint carries both the single (createDocument) and batch (createDocuments) SDK methods. (SDK: documentsDB.createDocument / documentsDB.createDocuments)
Input (createDocument, single)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | body | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
data | body | object | Yes | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID: attaches this write to a transaction. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}, "documentId": "note-101"}'Output: 201 + Models.Document (fields as described at the beginning of this group).
Response example
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
}Input (createDocuments, batch)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documents | body | object[] | Yes | Array of document data objects, which may contain partial fields (for batch upsert). | |
transactionId | body | string | No | Transaction ID: attaches the batch write to a transaction. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"documents": [{"documentId": "note-101", "data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}}, {"documentId": "note-102", "data": {"title": "Reading list", "body": "Finish the schema migration runbook.", "color": "sage", "wordCount": 90, "labels": ["work"]}}]}'Output: 201 + Models.DocumentList (total + array; pagination structure as described at the beginning of this group).
Response example
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}PUT /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
Batch upsert documents (the documents array may contain partial fields). (SDK: documentsDB.upsertDocuments)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documents | body | object[] | Yes | Array of document data objects, which may contain partial fields (for batch upsert). | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"documents": [{"documentId": "note-101", "data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}}, {"documentId": "note-102", "data": {"title": "Reading list", "body": "Finish the schema migration runbook.", "color": "sage", "wordCount": 90, "labels": ["work"]}}]}'Output: 201 + Models.DocumentList.
Response example
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
Batch update documents by queries and return the affected documents.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
queries | body | string[] | No | Array of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"pinned": true}, "queries": ["equal(\"color\",amber)"]}'Output: 200 + Models.DocumentList.
Response example
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}DELETE /v1/documentsdb/{databaseId}/collections/{collectionId}/documents
Batch delete documents by queries and return the affected documents.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
queries | body | string[] | No | Array of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"queries": ["lessThan(\"wordCount\",100)"]}'Output: 200 + Models.DocumentList.
Response example
{
"total": 2,
"documents": [
{
"$id": "note-101",
"$sequence": "1",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Weekly plan",
"body": "Finish the schema migration runbook.",
"color": "amber",
"wordCount": 250,
"labels": [
"work"
]
},
{
"$id": "note-102",
"$sequence": "2",
"$collectionId": "notes",
"$databaseId": "notes-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"title": "Reading list",
"body": "Finish the schema migration runbook.",
"color": "sage",
"wordCount": 90,
"labels": [
"work"
]
}
]
}GET /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}
Get a single document by ID.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | query | string | No | Transaction ID. |
Call example
curl \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Document.
Response example: isomorphic to the Models.Document example already shown above in the same group.
PUT /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}
Upsert a document: update if it exists, create if it does not. (SDK: documentsDB.upsertDocument)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}, "permissions": ["read(\"any\")"]}'Output: 201 + Models.Document.
Response example: isomorphic to the Models.Document example already shown above in the same group.
PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}
Partially update a document (data contains only the attributes to update).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"wordCount": 300}}'Output: 200 + Models.Document.
Response example: isomorphic to the Models.Document example already shown above in the same group.
PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/decrement
Atomically decrement a numeric attribute (with an optional lower bound min).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
attribute | path | string | Yes | Attribute key (path parameter). | |
value | body | number | No | Increment value (number), default 1. | |
min | body | number | No | Lower bound for the decrement; an out-of-bounds value raises an error and is not written. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101/wordCount/decrement" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 100, "min": 0}'Output: 200 + Models.Document; returns the complete document after decrement.
Response example: isomorphic to the Models.Document example already shown above in the same group.
PATCH /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/increment
Atomically increment a numeric attribute (with an optional upper bound max).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
attribute | path | string | Yes | Attribute key (path parameter). | |
value | body | number | No | Increment value (number), default 1. | |
max | body | number | No | Upper bound for the increment; an out-of-bounds value raises an error and is not written. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101/wordCount/increment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 100, "max": 10000}'Output: 200 + Models.Document; returns the complete document after increment.
Response example: isomorphic to the Models.Document example already shown above in the same group.
DELETE /v1/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}
Delete a document; can be attached to a transaction.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/notes-db/collections/notes/documents/note-101" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Transactions (transaction)
transaction model fields:
| field | description |
|---|---|
$id | Transaction ID, used by row/document endpoints to pass transactionId |
$createdAt / $updatedAt | creation/update time |
status | pending → committing → committed / rolled_back / failed |
operations | Number of staged operations |
expiresAt | Expiration time; uncommitted operations are voided after expiration |
Element structure of POST …/operations for operations[] (databaseId, action, and collectionId are required; data is the operation payload):
| action | additional required | description |
|---|---|---|
create / update / upsert / increment / decrement | documentId, data | single-document operation; data is an object of column values |
delete | documentId | deletes a single document |
bulkCreate / bulkUpdate / bulkUpsert / bulkDelete | data | batch operations; data is an array of objects |
Operations are appended across multiple calls and take no effect until commit; the row/document read-write endpoints can also take transactionId directly to attach a single operation to a transaction.
GET /v1/documentsdb/transactions
List transactions with pagination.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. |
Call example
curl -G \
"https://<your-endpoint>/v1/documentsdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(10)'Output: 200 + Models.TransactionList.
Response example
{
"total": 1,
"transactions": [
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 2,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}
]
}POST /v1/documentsdb/transactions
Create a transaction and return the transaction ID; the optional ttl controls its validity period.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
ttl | body | integer | No | Transaction validity period in seconds; unstaged operations expire and become void after this. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"ttl": 60}'Output: 201 + Models.Transaction.
Response example
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 0,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}GET /v1/documentsdb/transactions/{transactionId}
Get transaction status and staged operation counts.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. |
Call example
curl \
"https://<your-endpoint>/v1/documentsdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
POST /v1/documentsdb/transactions/{transactionId}/operations
Batch-stage operations into a transaction; can be called multiple times to append.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. | |
operations | body | object[] | No | Array of staged operations; element structure is shown at the start of this group; can be appended across multiple calls. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/documentsdb/transactions/259125845563242502/operations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"operations": [{"databaseId": "notes-db", "collectionId": "notes", "documentId": "note-101", "action": "create", "data": {"title": "Weekly plan", "body": "Finish the schema migration runbook.", "color": "amber", "wordCount": 250, "labels": ["work"]}}, {"databaseId": "notes-db", "collectionId": "notes", "documentId": "note-102", "action": "delete"}]}'Output: 201 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
PATCH /v1/documentsdb/transactions/{transactionId}
Commit (commit=true) or roll back (rollback=true) the transaction; only one of the two may be chosen.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. | |
commit | body | boolean | No | Set to true to commit the transaction (mutually exclusive with rollback). | |
rollback | body | boolean | No | Set to true to roll back the transaction (mutually exclusive with commit). |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/documentsdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"commit": true}'Output: 200 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
DELETE /v1/documentsdb/transactions/{transactionId}
Delete the transaction (discarding its staged operations).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/documentsdb/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Legacy Databases per-endpoint specification (/databases, 68 endpoints)
Database
database model fields:
| field | description |
|---|---|
$id | database ID |
name | name (≤128 characters) |
$createdAt / $updatedAt | creation/update time (ISO 8601) |
enabled | enabled state; disabling only blocks user-side access, API Keys can still read and write, no data loss |
type | database type: legacy / tablesdb / documentsdb / vectorsdb |
List response databaseList: total (total match count) + databases[].
GET /v1/databases
List the current project's databases with pagination, supporting queries filtering and search search. (SDK: databases.list)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
search | query | string | No | Keyword search, up to 256 characters. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/databases" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Orders")' \
--data-urlencode 'queries[]=limit(50)'Output: 200 + Models.DatabaseList.
Response example
{
"total": 1,
"databases": [
{
"$id": "shop-db",
"name": "Shop",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "legacy"
}
]
}POST /v1/databases
Create a database. (SDK: databases.create)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | body | string | Yes | Unique database ID. | |
name | body | string | Yes | Name, up to 128 characters. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"databaseId": "shop-db", "name": "Shop", "enabled": true}'Output: 201 + Models.Database.
Response example
{
"$id": "shop-db",
"name": "Shop",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"enabled": true,
"type": "legacy"
}GET /v1/databases/{databaseId}
Get database details by ID. (SDK: databases.get)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. |
Call example
curl \
"https://<your-endpoint>/v1/databases/shop-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Database.
Response example: isomorphic to the Models.Database example already shown above in the same group.
PUT /v1/databases/{databaseId}
Update the database name and enabled state. (SDK: databases.update)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
name | body | string | No | Name, up to 128 characters. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/databases/shop-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Orders", "enabled": true}'Output: 200 + Models.Database.
Response example: isomorphic to the Models.Database example already shown above in the same group.
DELETE /v1/databases/{databaseId}
Delete a database by ID. (SDK: databases.delete)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Collections (collection)
collection model fields:
| field | description |
|---|---|
$id | Collection ID |
databaseId | parent database ID |
name | name (≤128 characters) |
$permissions | Array of collection-level permission strings |
enabled | enabled state; disabling only blocks user-side access |
documentSecurity | Whether document-level permissions are enabled |
attributes[] | Array of attribute definitions (attribute* model; see the Attributes section) |
indexes[] | index array (index model, see the "Indexes" section) |
bytesMax / bytesUsed | Capacity quota and used bytes |
List response collectionList: total + collections[].
GET /v1/databases/{databaseId}/collections
List collections in the database, supporting queries filtering and search search.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
search | query | string | No | Keyword search, up to 256 characters. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/databases/shop-db/collections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("name","Orders")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.CollectionList.
Response example
{
"total": 1,
"collections": [
{
"$id": "orders",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "shop-db",
"name": "Orders",
"enabled": true,
"documentSecurity": false,
"bytesMax": 52428800,
"bytesUsed": 20480,
"attributes": [
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 64,
"encrypt": false
},
{
"key": "status",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"pending",
"paid",
"shipped"
],
"format": "enum",
"size": 16
},
{
"key": "total",
"type": "double",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 0,
"max": 100000
}
],
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}
]
}POST /v1/databases/{databaseId}/collections
Create a collection; the request body may carry the complete attributes/indexes definitions.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | body | string | Yes | Collection unique ID. | |
name | body | string | Yes | Name, up to 128 characters. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
documentSecurity | body | boolean | No | Whether document-level permissions are enabled; once enabled, accessing a single document requires holding either a document-level or a collection-level permission. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. | |
attributes | body | object[] | No | Array of attribute definitions created together with the collection; fields are the same as TablesDB's columns (key and type required, etc.). | |
indexes | body | object[] | No | Definition array for creating indexes along with the table/collection (key, type, attributes required; orders, lengths optional). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"collectionId": "orders", "name": "Orders", "documentSecurity": false, "attributes": [{"key": "customerId", "type": "string", "size": 64, "required": true}, {"key": "status", "type": "string", "size": 16, "format": "enum", "elements": ["pending", "paid", "shipped"], "required": true}, {"key": "total", "type": "double"}], "indexes": [{"key": "idx_status", "type": "key", "attributes": ["status"]}]}'Output: 201 + Models.Collection.
Response example
{
"$id": "orders",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"databaseId": "shop-db",
"name": "Orders",
"enabled": true,
"documentSecurity": false,
"bytesMax": 52428800,
"bytesUsed": 20480,
"attributes": [
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 64,
"encrypt": false
},
{
"key": "status",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"pending",
"paid",
"shipped"
],
"format": "enum",
"size": 16
},
{
"key": "total",
"type": "double",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 0,
"max": 100000
}
],
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/databases/{databaseId}/collections/{collectionId}
Get collection details (including attribute and index definitions).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. |
Call example
curl \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Collection.
Response example: isomorphic to the Models.Collection example already shown above in the same group.
PUT /v1/databases/{databaseId}/collections/{collectionId}
Update collection attributes, or submit the whole collection structure (attributes/indexes arrays).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
name | body | string | No | Name, up to 128 characters. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
documentSecurity | body | boolean | No | Whether document-level permissions are enabled; once enabled, accessing a single document requires holding either a document-level or a collection-level permission. | |
enabled | body | boolean | No | Whether enabled. When disabled, it is inaccessible on the user side, but servers holding an API Key can still read and write; switching causes no data loss. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"name": "Orders", "enabled": true}'Output: 200 + Models.Collection.
Response example: isomorphic to the Models.Collection example already shown above in the same group.
DELETE /v1/databases/{databaseId}/collections/{collectionId}
Delete the collection.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Attributes (attribute, 17 types)
Common fields of the collection attribute models (Models.AttributeString … Models.AttributeRelationship):
| field | description |
|---|---|
key | Attribute key |
type | Type identifier (the type of the enum property remains string, distinguished by format: "enum" + elements) |
status | available / processing / deleting / stuck / failed |
error | failure reason (empty string if no error) |
required / array | required / whether an array column |
$createdAt / $updatedAt | creation/update time |
Lifecycle notes:
Creation returns
202(async DDL), andstatusgoes fromprocessing→available(orfailed); pollGET …/{key}untilavailablebefore writing data that depends on the attribute.Update endpoints (
PATCH …/{type}/{key}) return200synchronously; common parameters arerequired,default,newKey(rename), and each type has its own specific parameters (see each endpoint's table).defaultandrequiredare mutually exclusive; before changingrequired, ensure all existing rows have values.
GET /v1/databases/{databaseId}/collections/{collectionId}/attributes
List all attributes of a collection (including attribute creation progress status).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(100)'Output: 200 + Models.AttributeList.
Response example
{
"total": 2,
"attributes": [
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
},
{
"key": "status",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"pending",
"paid",
"shipped"
],
"format": "enum",
"default": "paid",
"size": 16
}
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/boolean
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | boolean | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/boolean" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "paid", "required": false, "default": false}'Output: 202 + Models.AttributeBoolean; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "paid",
"type": "boolean",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/datetime
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/datetime" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "placedAt", "required": false, "default": "1970-01-01T00:00:00.000+00:00"}'Output: 202 + Models.AttributeDatetime; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "placedAt",
"type": "datetime",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "datetime",
"default": "1970-01-01T00:00:00.000+00:00"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/email
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/email" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "buyerEmail", "required": false}'Output: 202 + Models.AttributeEmail; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "buyerEmail",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "email",
"default": "default@example.com"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/enum
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
elements | body | string[] | Yes | Array of enum values (non-empty string array); default must be taken from it. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/enum" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "status", "elements": ["pending", "paid", "shipped"], "required": false, "default": "pending"}'Output: 202 + Models.AttributeEnum; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "status",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"elements": [
"pending",
"paid",
"shipped"
],
"format": "enum",
"default": "paid",
"size": 16
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/float
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
min | body | number | No | Minimum lower bound. | |
max | body | number | No | Maximum upper bound. | |
default | body | number | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/float" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "total", "min": 0, "max": 100000, "required": false, "default": 0}'Output: 202 + Models.AttributeFloat; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "total",
"type": "double",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 0,
"max": 10,
"default": 0
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/integer
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
min | body | integer | No | Minimum lower bound. | |
max | body | integer | No | Maximum upper bound. | |
default | body | integer | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/integer" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "itemCount", "min": 0, "max": 1000, "required": false, "default": 1}'Output: 202 + Models.AttributeInteger; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "itemCount",
"type": "integer",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"min": 1900,
"max": 2100,
"default": 2000
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/ip
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/ip" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "clientIp", "required": false}'Output: 202 + Models.AttributeIp; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "clientIp",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "ip",
"default": "192.0.2.0"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/line
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/line" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "route", "required": false}'Output: 202 + Models.AttributeLine; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "route",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
[
116.4,
39.9
],
[
116.5,
40.0
]
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/longtext
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/longtext" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "payload", "required": false}'Output: 202 + Models.AttributeLongtext; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "payload",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": "default",
"encrypt": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/mediumtext
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/mediumtext" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "log", "required": false}'Output: 202 + Models.AttributeMediumtext; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "log",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": "default",
"encrypt": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/point
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/point" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "deliveryPoint", "required": false}'Output: 202 + Models.AttributePoint; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "deliveryPoint",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
116.4,
39.9
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/polygon
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/polygon" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "region", "required": false}'Output: 202 + Models.AttributePolygon; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "region",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": [
[
[
116.4,
39.9
],
[
116.5,
39.9
],
[
116.5,
40.0
],
[
116.4,
39.9
]
]
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/relationship
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
relatedCollectionId | body | string | Yes | Related collection ID. The target collection of a relationship attribute cannot be changed after creation. | |
type | body | string | Yes | Enum oneToOne / manyToOne / manyToMany / oneToMany | Relationship type: oneToOne / manyToOne / manyToMany / oneToMany. |
twoWay | body | boolean | No | Whether the relationship is two-way. For two-way relationships, twoWayKey must be provided. | |
key | body | string | No | Column/attribute key. Character constraints are the same as for resource IDs; must be unique within the table/collection. | |
twoWayKey | body | string | No | The reverse column key on the opposite-side table/collection for a two-way relationship. | |
onDelete | body | string | No | Enum cascade / restrict / setNull | Constraint when related rows are deleted: cascade (cascade delete) / restrict (block deletion) / setNull (set null). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/relationship" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "customer", "relatedCollectionId": "customers", "type": "manyToOne", "onDelete": "restrict"}'Output: 202 + Models.AttributeRelationship; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "customer",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"relatedCollection": "customers",
"relationType": "manyToOne",
"twoWay": false,
"twoWayKey": "",
"onDelete": "restrict",
"side": "parent|child"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/string
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
size | body | integer | Yes | Maximum number of characters. Required at creation for string/varchar; varchar maximum is 16381. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/string" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "customerId", "size": 128, "required": true}'Output: 202 + Models.AttributeString; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/text
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/text" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "remark", "required": false}'Output: 202 + Models.AttributeText; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "remark",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"default": "default",
"encrypt": false
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/url
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/url" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "receiptUrl", "required": false}'Output: 202 + Models.AttributeUrl; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "receiptUrl",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"format": "url",
"default": "http://example.com"
}POST /v1/databases/{databaseId}/collections/{collectionId}/attributes/varchar
Create an attribute (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
size | body | integer | Yes | Maximum number of characters. Required at creation for string/varchar; varchar maximum is 16381. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | No | Default value (fills in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
array | body | boolean | No | Whether it is an array column. | |
encrypt | body | boolean | No | Whether to store encrypted. Encrypted columns cannot be used for queries, sorting, or indexes. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/varchar" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "orderNo", "size": 32, "required": false, "default": "NEW"}'Output: 202 + Models.AttributeVarchar; asynchronous attribute creation: status starts as processing; poll GET …/attributes/{key} until available before writing.
Response example
{
"key": "orderNo",
"type": "string",
"status": "available",
"error": "",
"required": false,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 32,
"default": "NEW",
"encrypt": false
}PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/boolean/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | boolean | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/boolean/paid" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": false, "required": false}'Output: 200 + Models.AttributeBoolean; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeBoolean example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/datetime/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/datetime/placedAt" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": "1970-01-01T00:00:00.000+00:00", "required": false}'Output: 200 + Models.AttributeDatetime; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeDatetime example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/email/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/email/buyerEmail" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.AttributeEmail; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeEmail example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/enum/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
elements | body | string[] | Yes | Array of enum values (non-empty string array); default must be taken from it. | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/enum/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"elements": ["pending", "paid", "shipped", "refunded"], "default": "pending", "required": false}'Output: 200 + Models.AttributeEnum; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeEnum example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/float/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
min | body | number | No | Minimum lower bound. | |
max | body | number | No | Maximum upper bound. | |
default | body | number | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/float/total" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"min": 0, "max": 100000, "required": false}'Output: 200 + Models.AttributeFloat; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeFloat example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/integer/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
min | body | integer | No | Minimum lower bound. | |
max | body | integer | No | Maximum upper bound. | |
default | body | integer | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/integer/itemCount" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"min": 0, "max": 1000, "required": false}'Output: 200 + Models.AttributeInteger; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeInteger example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/ip/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/ip/clientIp" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.AttributeIp; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeIp example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/line/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/line/route" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'Output: 200 + Models.AttributeLine; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeLine example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/longtext/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/longtext/payload" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.AttributeLongtext; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeLongtext example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/mediumtext/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/mediumtext/log" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.AttributeMediumtext; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeMediumtext example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/point/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/point/deliveryPoint" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'Output: 200 + Models.AttributePoint; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributePoint example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/polygon/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | array | No | Default coordinates. point is [经度, 纬度]; line is an array of coordinate pairs [[lon, lat], …]; polygon is an array of rings [[[lon, lat], …], …] (the first ring is the outer boundary, and the first and last points of each ring are identical). | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/polygon/region" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"required": false}'Output: 200 + Models.AttributePolygon; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributePolygon example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/relationship/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
onDelete | body | string | No | Enum cascade / restrict / setNull | Constraint when related rows are deleted: cascade (cascade delete) / restrict (block deletion) / setNull (set null). |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/relationship/customer" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"onDelete": "setNull", "newKey": "customer-x"}'Output: 200 + Models.AttributeRelationship; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeRelationship example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/string/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
size | body | integer | No | Maximum number of characters. Required at creation for string/varchar; varchar maximum is 16381. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/string/customerId" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"size": 256, "required": false}'Output: 200 + Models.AttributeString; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeString example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/text/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/text/remark" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.AttributeText; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeText example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/url/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/url/receiptUrl" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"default": null, "required": false}'Output: 200 + Models.AttributeUrl; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeUrl example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/attributes/varchar/{key}
Update an attribute (requiredness, default value, bounds; newKey can rename it).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). | |
required | body | boolean | Yes | Whether required. Before making it required, ensure all existing rows have values in this column. | |
default | body | string | Yes | Default value (filled in when the column is not provided on write). Required columns cannot have a default value; the type varies with the column type. | |
size | body | integer | No | Maximum number of characters. Required at creation for string/varchar; varchar maximum is 16381. | |
newKey | body | string | No | New key. Renaming preserves existing data; index/permission references must be updated accordingly. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/varchar/orderNo" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"size": 64, "required": false}'Output: 200 + Models.AttributeVarchar; synchronous update, returns the updated attribute model.
Response example: isomorphic to the Models.AttributeVarchar example already shown above in the same group.
GET /v1/databases/{databaseId}/collections/{collectionId}/attributes/{key}
Get a single attribute definition and status.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + any Models.Attribute* type model; the response is any column* / attribute* type model (using string as an example).
Response example (using string type as an example)
{
"key": "customerId",
"type": "string",
"status": "available",
"error": "",
"required": true,
"array": false,
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"size": 128,
"encrypt": false
}DELETE /v1/databases/{databaseId}/collections/{collectionId}/attributes/{key}
Delete an attribute (asynchronous).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/attributes/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; asynchronous deletion; no response body.
Indexes (index)
index model fields:
| field | description |
|---|---|
$id | Index ID |
key | Index key |
type | key / fulltext / unique / spatial |
status | available / processing / deleting / stuck / failed |
error | Failure reason |
attributes[] | Array of attribute keys participating in the index |
lengths[] | Prefix lengths per column (positionally aligned with the attributes) |
orders[] | Sort direction per column ASC/DESC (positionally aligned with the attributes) |
Creation/deletion is asynchronous (202); poll GET …/indexes/{key} until status=available. List responses are total + indexes[].
GET /v1/databases/{databaseId}/collections/{collectionId}/indexes
List collection indexes (filterable by key/type/status).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
Call example
curl -G \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("type","key")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.IndexList.
Response example
{
"total": 1,
"indexes": [
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}
]
}GET /v1/databases/{databaseId}/collections/{collectionId}/indexes/{key}
Get the index definition and status.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/indexes/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Index.
Response example: isomorphic to the Models.Index example already shown above in the same group.
POST /v1/databases/{databaseId}/collections/{collectionId}/indexes
Create an index (asynchronous, returns 202).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | body | string | Yes | Column/attribute key. Character constraints are the same as resource IDs; unique within the table/collection. | |
type | body | string | Yes | Enum key / fulltext / unique / spatial | Index type: key (regular) / fulltext (fulltext) / unique (unique) / spatial (spatial). |
attributes | body | string[] | Yes | Array of attribute keys participating in the index; orders/lengths are positionally aligned with it. | |
orders | body | string[] | No | Sort direction of each indexed column: ASC / DESC (positionally matched with columns). | |
lengths | body | integer[] | No | Prefix length of each indexed column (integer array, positionally matched with columns). |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/indexes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"key": "idx_status", "type": "key", "attributes": ["status"], "orders": ["ASC"]}'Output: 202 + Models.Index; index creation is asynchronous: poll GET …/indexes/{key} until available.
Response example
{
"$id": "idx_status",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"key": "idx_status",
"type": "key",
"status": "available",
"error": "",
"attributes": [
"status"
],
"lengths": [],
"orders": [
"ASC"
]
}DELETE /v1/databases/{databaseId}/collections/{collectionId}/indexes/{key}
Delete an index.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
key | path | string | Yes | Column/attribute key (path parameter). |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/indexes/status" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Documents (document)
Document model fields:
| field | description |
|---|---|
$id | Document ID |
$sequence | Document sequence number (monotonically increasing within the same collection) |
$collectionId | Owning collection ID |
$databaseId | parent database ID |
$createdAt / $updatedAt | creation/update time |
$permissions | Array of document-level permission strings |
All keys other than system fields are data attributes (key = attribute key). List responses documentList: total + documents[]; the query parameter total=false skips counting, and ttl (0–86400 seconds) enables response caching for select queries (requires the instance to have it enabled).
GET /v1/databases/{databaseId}/collections/{collectionId}/documents
Query documents: filtering/sorting/pagination, with support for reading uncommitted changes within a transaction and a cache TTL.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | query | string | No | Transaction ID. | |
total | query | boolean | No | Default true | When set to false, counting is skipped and total in the response is always 0. |
ttl | query | integer | No | Default 0 | Response cache TTL for select queries (0–86400 seconds); requires the instance to have caching enabled; 0 means no caching. |
Call example
curl -G \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=equal("status","pending")' \
--data-urlencode 'queries[]=limit(25)'Output: 200 + Models.DocumentList.
Response example
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}POST /v1/databases/{databaseId}/collections/{collectionId}/documents
Create documents; a single endpoint carries both the single (createDocument) and batch (createDocuments) SDK methods. (SDK: databases.createDocument / databases.createDocuments)
Input (createDocument, single)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | body | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
data | body | object | Yes | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID: attaches this write to a transaction. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}, "documentId": "order-1001"}'Output: 201 + Models.Document (fields as described at the beginning of this group).
Response example
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}Input (createDocuments, batch)
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documents | body | object[] | Yes | Array of document data objects, which may contain partial fields (for batch upsert). | |
transactionId | body | string | No | Transaction ID: attaches the batch write to a transaction. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"documents": [{"documentId": "order-1001", "data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}, {"documentId": "order-1002", "data": {"customerId": "cust-77", "itemCount": 1, "total": 36.0, "status": "paid", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}]}'Output: 201 + Models.DocumentList (total + array; pagination structure as described at the beginning of this group).
Response example
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}PUT /v1/databases/{databaseId}/collections/{collectionId}/documents
Batch upsert documents (the documents array may contain partial fields). (SDK: databases.upsertDocuments)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documents | body | object[] | Yes | Array of document data objects, which may contain partial fields (for batch upsert). | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"documents": [{"documentId": "order-1001", "data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}, {"documentId": "order-1002", "data": {"customerId": "cust-77", "itemCount": 1, "total": 36.0, "status": "paid", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}]}'Output: 201 + Models.DocumentList.
Response example
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents
Batch update documents by queries and return the affected documents.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
queries | body | string[] | No | Array of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"status": "paid"}, "queries": ["equal(\"status\",pending)"]}'Output: 200 + Models.DocumentList.
Response example
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}DELETE /v1/databases/{databaseId}/collections/{collectionId}/documents
Batch delete documents by queries and return the affected documents.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
queries | body | string[] | No | Array of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"queries": ["lessThan(\"total\",50)"]}'Output: 200 + Models.DocumentList.
Response example
{
"total": 2,
"documents": [
{
"$id": "order-1001",
"$sequence": "1",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-42",
"itemCount": 2,
"total": 128.5,
"status": "pending",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
},
{
"$id": "order-1002",
"$sequence": "2",
"$collectionId": "orders",
"$databaseId": "shop-db",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"$permissions": [
"read(\"any\")"
],
"customerId": "cust-77",
"itemCount": 1,
"total": 36.0,
"status": "paid",
"items": [
"sku-1",
"sku-7"
],
"placedAt": "2026-03-01T10:00:00.000+00:00"
}
]
}GET /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}
Get a single document by ID.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. | |
transactionId | query | string | No | Transaction ID. |
Call example
curl \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Document.
Response example: isomorphic to the Models.Document example already shown above in the same group.
PUT /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}
Upsert a document: update if it exists, create if it does not. (SDK: databases.upsertDocument)
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PUT \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}, "permissions": ["read(\"any\")"]}'Output: 201 + Models.Document.
Response example: isomorphic to the Models.Document example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}
Partially update a document (data contains only the attributes to update).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
data | body | object | No | Data object with keys as column/attribute keys. Contains only the fields to write/update. | |
permissions | body | string[] | No | Array of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"data": {"total": 130.0}}'Output: 200 + Models.Document.
Response example: isomorphic to the Models.Document example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/decrement
Atomically decrement a numeric attribute (with an optional lower bound min).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
attribute | path | string | Yes | Attribute key (path parameter). | |
value | body | number | No | Increment value (number), default 1. | |
min | body | number | No | Lower bound for the decrement; an out-of-bounds value raises an error and is not written. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001/itemCount/decrement" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 1}'Output: 200 + Models.Document; returns the complete document after decrement.
Response example: isomorphic to the Models.Document example already shown above in the same group.
PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/increment
Atomically increment a numeric attribute (with an optional upper bound max).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
attribute | path | string | Yes | Attribute key (path parameter). | |
value | body | number | No | Increment value (number), default 1. | |
max | body | number | No | Upper bound for the increment; an out-of-bounds value raises an error and is not written. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001/itemCount/increment" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"value": 1}'Output: 200 + Models.Document; returns the complete document after increment.
Response example: isomorphic to the Models.Document example already shown above in the same group.
DELETE /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}
Delete a document; can be attached to a transaction.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
databaseId | path | string | Yes | Unique database ID. | |
collectionId | path | string | Yes | Collection unique ID. | |
documentId | path | string | Yes | Document unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters. | |
transactionId | body | string | No | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/databases/shop-db/collections/orders/documents/order-1001" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Transactions (transaction)
transaction model fields:
| field | description |
|---|---|
$id | Transaction ID, used by row/document endpoints to pass transactionId |
$createdAt / $updatedAt | creation/update time |
status | pending → committing → committed / rolled_back / failed |
operations | Number of staged operations |
expiresAt | Expiration time; uncommitted operations are voided after expiration |
Element structure of POST …/operations for operations[] (databaseId, action, and collectionId are required; data is the operation payload):
| action | additional required | description |
|---|---|---|
create / update / upsert / increment / decrement | documentId, data | single-document operation; data is an object of column values |
delete | documentId | deletes a single document |
bulkCreate / bulkUpdate / bulkUpsert / bulkDelete | data | batch operations; data is an array of objects |
Operations are appended across multiple calls and take no effect until commit; the row/document read-write endpoints can also take transactionId directly to attach a single operation to a transaction.
GET /v1/databases/transactions
List transactions with pagination.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
queries | query | string[] | No | Array of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items. |
Call example
curl -G \
"https://<your-endpoint>/v1/databases/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
--data-urlencode 'queries[]=limit(10)'Output: 200 + Models.TransactionList.
Response example
{
"total": 1,
"transactions": [
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 2,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}
]
}POST /v1/databases/transactions
Create a transaction and return the transaction ID; the optional ttl controls its validity period.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
ttl | body | integer | No | Transaction validity period in seconds; unstaged operations expire and become void after this. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/transactions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"ttl": 60}'Output: 201 + Models.Transaction.
Response example
{
"$id": "259125845563242502",
"$createdAt": "2026-01-12T08:00:00.000+00:00",
"$updatedAt": "2026-01-12T08:00:00.000+00:00",
"status": "pending",
"operations": 0,
"expiresAt": "2026-01-12T08:01:00.000+00:00"
}GET /v1/databases/transactions/{transactionId}
Get transaction status and staged operation counts.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. |
Call example
curl \
"https://<your-endpoint>/v1/databases/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 200 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
POST /v1/databases/transactions/{transactionId}/operations
Batch-stage operations into a transaction; can be called multiple times to append.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. | |
operations | body | object[] | No | Array of staged operations; element structure is shown at the start of this group; can be appended across multiple calls. |
Call example
curl -X POST \
"https://<your-endpoint>/v1/databases/transactions/259125845563242502/operations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"operations": [{"databaseId": "shop-db", "collectionId": "orders", "documentId": "order-1001", "action": "create", "data": {"customerId": "cust-42", "itemCount": 2, "total": 128.5, "status": "pending", "items": ["sku-1", "sku-7"], "placedAt": "2026-03-01T10:00:00.000+00:00"}}, {"databaseId": "shop-db", "collectionId": "orders", "documentId": "order-1002", "action": "delete"}]}'Output: 201 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
PATCH /v1/databases/transactions/{transactionId}
Commit (commit=true) or roll back (rollback=true) the transaction; only one of the two may be chosen.
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. | |
commit | body | boolean | No | Set to true to commit the transaction (mutually exclusive with rollback). | |
rollback | body | boolean | No | Set to true to roll back the transaction (mutually exclusive with commit). |
Call example
curl -X PATCH \
"https://<your-endpoint>/v1/databases/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"commit": true}'Output: 200 + Models.Transaction.
Response example: isomorphic to the Models.Transaction example already shown above in the same group.
DELETE /v1/databases/transactions/{transactionId}
Delete the transaction (discarding its staged operations).
Input
| Parameter | Location | Type | Required | Default/enum | Description |
|---|---|---|---|---|---|
transactionId | path | string | Yes | Transaction ID. |
Call example
curl -X DELETE \
"https://<your-endpoint>/v1/databases/transactions/259125845563242502" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"Output: 204 No Content, no response body; no response body.
Errors and boundaries
Database/table/row not found:
404+database_not_found/table_not_found/row_not_found(legacy:collection_not_found/document_not_found; DocumentsDB matches legacy).Duplicate database/table ID:
409+database_already_exists/table_already_exists.Column mismatch when writing a row: missing required columns return
row_invalid(structure 400); unknown columns are rejected or ignored depending on the spec validation; writes fail while a column is stillprocessing(202 incomplete).Creating columns/indexes is asynchronous (202): poll
GET .../columns/{key}/.../indexes/{key}untilstatus=availablebefore performing reads/writes that depend on the column.Quantity and capacity limits: exceeding the number of databases or tables returns
database_limit_exceededandtable_limit_exceededrespectively; exceeding database storage returnsdatabase_storage_limit_exceeded(413).Transactions:
commitandrollbackcannot both be true; attaching an operation to an expired transaction returns 400; concurrent out-of-transaction writes to the same row follow last-write-wins — usetransactionIdorincrement/decrementwhen atomicity is needed.Batch update/delete uses
queriesto delimit the scope; an emptyqueriesmatches the entire table — callers must explicitly include filter conditions to confirm the scope.enabled=false(databases/tables/collections) only blocks user-side access; API Key paths are unaffected, and switching does not lose data.Schema rollback is not data rollback: rollback only restores the visible structure scope; data written during that period is not deleted. After rollback, new column data is invisible but not lost, and rolling forward again restores it.
Correspondence with the Server SDK
| service.method | Endpoint |
|---|---|
TablesDB.list / create / get / update / delete | GET|POST /tablesdb、GET|PUT|DELETE /tablesdb/{databaseId} |
TablesDB.listTables / createTable / getTable / updateTable / deleteTable | /tablesdb/{databaseId}/tables each CRUD |
TablesDB.listColumns / getColumn / deleteColumn | .../columns、.../columns/{key} |
TablesDB.createBooleanColumn … createPolygonColumn (17 typed methods), updateBooleanColumn … updatePolygonColumn | POST|PATCH .../columns/{type}, .../columns/{type}/{key} |
TablesDB.createRelationshipColumn / updateRelationshipColumn | POST .../columns/relationship、PATCH .../columns/{key}/relationship |
TablesDB.updateColumnComment | PATCH .../columns/{key}/comment |
TablesDB.listIndexes / createIndex / getIndex / deleteIndex | .../indexes CRUD |
TablesDB.listRows / createRow / createRows / getRow / updateRow / upsertRow / upsertRows / updateRows / deleteRow / deleteRows | single-item and batch endpoints (see table above) |
TablesDB.incrementRowColumn / decrementRowColumn | PATCH .../rows/{rowId}/{column}/increment|decrement |
TablesDB.aggregateRows | GET .../tables/{tableId}/aggregation |
TablesDB.listTransactions / createTransaction / getTransaction / updateTransaction / createOperations / deleteTransaction | /tablesdb/transactions* |
TablesDB.listSchemaVersions / createSchemaVersion / getSchemaVersion / rollbackSchemaVersion | /tablesdb/{databaseId}/schema/versions*、/schema/rollback/{versionId} |
DocumentsDB.list … DocumentsDB.incrementDocumentAttribute / decrementDocumentAttribute | /documentsdb all isomorphic endpoints |
Databases.list … Databases.decrementDocumentAttribute | /databases all isomorphic endpoints (including 17 create{Type}Attribute / update{Type}Attribute methods) |