Docs
Contents

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:

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

Authentication and Permissions

For authentication and request header conventions, see Common Conventions. Scopes in this domain:

ScopeCoverage
databases.read / databases.writeDatabase-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 + pathPurpose
GET /tablesdbList databases
POST /tablesdbCreate database
GET /tablesdb/{databaseId}Get database
PUT /tablesdb/{databaseId}Update database name/enabled status
DELETE /tablesdb/{databaseId}Delete database
GET /tablesdb/{databaseId}/tablesList tables
POST /tablesdb/{databaseId}/tablesCreate 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}/columnsList 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}/commentUpdate column label (display name)
PATCH /tablesdb/{databaseId}/tables/{tableId}/columns/{key}/relationshipUpdate relationship column
DELETE /tablesdb/{databaseId}/tables/{tableId}/columns/{key}Delete column
GET /tablesdb/{databaseId}/tables/{tableId}/indexesList indexes
POST /tablesdb/{databaseId}/tables/{tableId}/indexesCreate index
GET /tablesdb/{databaseId}/tables/{tableId}/indexes/{key}Get index
DELETE /tablesdb/{databaseId}/tables/{tableId}/indexes/{key}Delete index
GET /tablesdb/{databaseId}/tables/{tableId}/rowsList rows (query/pagination/cache TTL)
POST /tablesdb/{databaseId}/tables/{tableId}/rowsCreate 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}/rowsUpsert rows in batch
PATCH /tablesdb/{databaseId}/tables/{tableId}/rowsUpdate rows in batch by query
DELETE /tablesdb/{databaseId}/tables/{tableId}/rowsDelete rows in batch by query
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/incrementIncrement column value
PATCH /tablesdb/{databaseId}/tables/{tableId}/rows/{rowId}/{column}/decrementDecrement column value
GET /tablesdb/{databaseId}/tables/{tableId}/aggregationAggregate rows (count/sum/avg/min/max)
GET /tablesdb/transactionsList transactions
POST /tablesdb/transactionsCreate transaction
GET /tablesdb/transactions/{transactionId}Get transaction
PATCH /tablesdb/transactions/{transactionId}Commit/rollback transaction
POST /tablesdb/transactions/{transactionId}/operationsStage transaction operations in batch
DELETE /tablesdb/transactions/{transactionId}Delete transaction
GET /tablesdb/{databaseId}/schema/versionsList Schema versions
POST /tablesdb/{databaseId}/schema/versionsSubmit 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)

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

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:

Requests and Responses

Database

Tables and collections

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:

typeSpecific parameters (besides key and required)
stringsize (required, character count), default, array, encrypt (not queryable when encrypted)
varcharsize (required, max 16381), default, array, encrypt
text / mediumtext / longtextdefault、array、encrypt
email / url / ipdefault、array
integermin、max、default、array
floatmin、max、default、array
booleandefault、array
datetimedefault(ISO 8601)、array
enumelements (required, array of enum values), default, array
pointdefault([longitude, latitude])
linedefault (two-dimensional array of coordinate pairs)
polygondefault (three-dimensional array of rings, first ring is the outer boundary)
relationshiptype (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

Rows / documents

Aggregation (TablesDB only)

GET /tablesdb/{databaseId}/tables/{tableId}/aggregation:

ParameterLocationRequiredDescription
selectqueryYesAggregation expressions and grouping columns, supporting count/sum/avg/min/max with AS aliases; plain columns must appear in groupBy
groupByqueryNoGrouping columns, up to 5 scalar columns
queriesqueryNoFilters the query only; pagination, sorting, cursors, and Query.select are not supported (they will be rejected)
transactionIdqueryNoRead uncommitted changes within a transaction

Returns 200 + rowAggregation (total + aggregated result rows).

Transactions

Schema versions and rollback (TablesDB only)

TablesDB per-endpoint specification (/tablesdb, 74 endpoints)

Database

database model fields:

fielddescription
$iddatabase ID
namename (≤128 characters)
$createdAt / $updatedAtcreation/update time (ISO 8601)
enabledenabled state; disabling only blocks user-side access, API Keys can still read and write, no data loss
typedatabase 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

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
searchquerystringNoKeyword search, up to 256 characters.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdbodystringYesUnique database ID.
namebodystringYesName, up to 128 characters.
enabledbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
namebodystringNoName, up to 128 characters.
enabledbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique 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:

fielddescription
$idtable ID
databaseIdparent database ID
namename (≤128 characters)
commentdisplay name (≤256 Unicode characters, may be empty)
$permissionsarray of table-level permission strings
enabledenabled state; disabling only blocks user-side access
rowSecuritywhether 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 / bytesUsedtable 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
searchquerystringNoKeyword search, up to 256 characters.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdbodystringYesUnique table ID.
namebodystringYesName, up to 128 characters.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
rowSecuritybodybooleanNoWhether to enable row-level permissions; once enabled, accessing a single row requires holding either row-level or table-level permissions.
enabledbodybooleanNoWhether 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.
columnsbodyobject[]NoColumn 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.
indexesbodyobject[]NoDefinition array for creating indexes along with the table/collection (key, type, attributes required; orders, lengths optional).
commentbodystringNoDisplay 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
namebodystringNoName, up to 128 characters.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
rowSecuritybodybooleanNoWhether to enable row-level permissions; once enabled, accessing a single row requires holding either row-level or table-level permissions.
enabledbodybooleanNoWhether 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.
columnsbodyobject[]NoColumn 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.
indexesbodyobject[]NoDefinition array for creating indexes along with the table/collection (key, type, attributes required; orders, lengths optional).
skipOnEmptybodybooleanNoWhen set to true, empty columns/indexes arrays are ignored; when false (default), empty arrays mean clearing all user-defined structure.
commentbodystringNoDisplay 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique 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):

fielddescription
keycolumn key
commentdisplay name/comment
typetype identifier (the type of a enum column is still string, distinguished by format: "enum" + elements)
statusavailable / processing / deleting / stuck / failed
errorfailure reason (empty string if no error)
required / arrayrequired / whether an array column
$createdAt / $updatedAtcreation/update time

Lifecycle notes:

GET /v1/tablesdb/{databaseId}/tables/{tableId}/columns

List all columns of a table (including column creation progress status).

Input

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodybooleanNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
elementsbodystring[]YesArray of enum values (non-empty string array); default must be taken from it.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
minbodynumberNoMinimum lower bound.
maxbodynumberNoMaximum upper bound.
defaultbodynumberNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
minbodyintegerNoMinimum lower bound.
maxbodyintegerNoMaximum upper bound.
defaultbodyintegerNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
relatedTableIdbodystringYesID of the related table. Once a relationship column is created, the opposite-side table cannot be changed.
typebodystringYesEnum oneToOne / manyToOne / manyToMany / oneToManyRelationship type: oneToOne / manyToOne / manyToMany / oneToMany.
twoWaybodybooleanNoWhether the relationship is two-way. For two-way relationships, twoWayKey must be provided.
keybodystringNoColumn/attribute key. Character constraints are the same as for resource IDs; must be unique within the table/collection.
twoWayKeybodystringNoThe reverse column key on the opposite-side table/collection for a two-way relationship.
onDeletebodystringNoEnum cascade / restrict / setNullConstraint 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
sizebodyintegerYesMaximum number of characters. Required at creation for string/varchar; varchar maximum is 16381.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
sizebodyintegerYesMaximum number of characters. Required at creation for string/varchar; varchar maximum is 16381.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodybooleanYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
elementsbodystring[]YesArray of enum values (non-empty string array); default must be taken from it.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
minbodynumberNoMinimum lower bound.
maxbodynumberNoMaximum upper bound.
defaultbodynumberYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
minbodyintegerNoMinimum lower bound.
maxbodyintegerNoMaximum upper bound.
defaultbodyintegerYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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).
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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).
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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).
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
sizebodyintegerNoMaximum number of characters. Required at creation for string/varchar; varchar maximum is 16381.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
sizebodyintegerNoMaximum number of characters. Required at creation for string/varchar; varchar maximum is 16381.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
commentbodystringYesDisplay 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/attribute key (path parameter).
onDeletebodystringNoEnum cascade / restrict / setNullConstraint when related rows are deleted: cascade (cascade delete) / restrict (block deletion) / setNull (set null).
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/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:

fielddescription
$idIndex ID
keyIndex key
typekey / fulltext / unique / spatial
statusavailable / processing / deleting / stuck / failed
errorFailure 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
typebodystringYesEnum key / fulltext / unique / spatialIndex type: key (regular) / fulltext (fulltext) / unique (unique) / spatial (spatial).
columnsbodystring[]YesArray of column keys participating in the index; orders/lengths correspond to it positionally.
ordersbodystring[]NoSort direction of each indexed column: ASC / DESC (positionally matched with columns).
lengthsbodyinteger[]NoPrefix 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
keypathstringYesColumn/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:

fielddescription
$idRow ID
$sequenceRow sequence number (monotonically increasing within the same table)
$tableIdID of the owning table
$databaseIdparent database ID
$createdAt / $updatedAtcreation/update time
$permissionsArray 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdquerystringNoTransaction ID.
totalquerybooleanNoDefault trueWhen set to false, counting is skipped and total in the response is always 0.
ttlqueryintegerNoDefault 0Response 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)

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowIdbodystringYesUnique 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.
databodyobjectYesData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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)

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowsbodyobject[]YesArray of row data objects, which may contain partial fields (used with batch upsert).
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowsbodyobject[]YesArray of row data objects, which may contain partial fields (used with batch upsert).
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
queriesbodystring[]NoArray of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
queriesbodystring[]NoArray of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowIdpathstringYesUnique 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.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdquerystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowIdpathstringYesUnique 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.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowIdpathstringYesUnique 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.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowIdpathstringYesUnique 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.
columnpathstringYesColumn key (path parameter).
valuebodynumberNoIncrement value (number), default 1.
minbodynumberNoLower bound for the decrement; an out-of-bounds value raises an error and is not written.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowIdpathstringYesUnique 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.
columnpathstringYesColumn key (path parameter).
valuebodynumberNoIncrement value (number), default 1.
maxbodynumberNoUpper bound for the increment; an out-of-bounds value raises an error and is not written.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
rowIdpathstringYesUnique 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.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
tableIdpathstringYesUnique table ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
groupByquerystring[]NoGrouping columns, up to 5 scalar columns.
selectquerystring[]YesAggregate expressions and grouping columns. Supports count/sum/avg/min/max with AS aliases; ordinary columns must also appear in groupBy.
transactionIdquerystringNoTransaction 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:

fielddescription
$idTransaction ID, used by row/document endpoints to pass transactionId
$createdAt / $updatedAtcreation/update time
statuspending → committing → committed / rolled_back / failed
operationsNumber of staged operations
expiresAtExpiration 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):

actionadditional requireddescription
create / update / upsert / increment / decrementrowId, datasingle-row operation; data is an object of column values
deleterowIddeletes a single row
bulkCreate / bulkUpdate / bulkUpsert / bulkDeletedatabatch 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

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoArray 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

ParameterLocationTypeRequiredDefault/enumDescription
ttlbodyintegerNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction ID.
operationsbodyobject[]NoArray 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction ID.
commitbodybooleanNoSet to true to commit the transaction (mutually exclusive with rollback).
rollbackbodybooleanNoSet 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction 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:

fielddescription
$idVersion record ID
databaseIdparent database ID
schemaVersionMonotonically increasing version number
schemaJsonThe complete structure JSON at commit time (snapshot)
schemaHashSHA-256 of the structure specification JSON, used for idempotency
statuspending / running / applying → active / failed; becomes deprecated after being superseded by a new version
migrationPlanJsonMigration plan (grouped by additive / compatible / destructive)
stepsTotal / stepsCompletedTotal number of DDL steps / completed count
errorMessageFailure reason
lastHeartbeatAtLatest migration Worker heartbeat
deprecatedColumnsColumns 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
versionIdpathstringYesTarget 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
versionIdpathstringYesTarget 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
schemabodyobjectYesComplete structure definition JSON object, including the tables array (a full database snapshot, not a diff patch).
modebodystringNoenum migration / baselinemigration (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:

fielddescription
$iddatabase ID
namename (≤128 characters)
$createdAt / $updatedAtcreation/update time (ISO 8601)
enabledenabled state; disabling only blocks user-side access, API Keys can still read and write, no data loss
typedatabase 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

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
searchquerystringNoKeyword search, up to 256 characters.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdbodystringYesUnique database ID.
namebodystringYesName, up to 128 characters.
enabledbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
namebodystringYesName, up to 128 characters.
enabledbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique 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:

fielddescription
$idCollection ID
databaseIdparent database ID
namename (≤128 characters)
$permissionsArray of collection-level permission strings
enabledenabled state; disabling only blocks user-side access
documentSecurityWhether 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 / bytesUsedCapacity 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
searchquerystringNoKeyword search, up to 256 characters.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdbodystringYesCollection unique ID.
namebodystringYesName, up to 128 characters.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
documentSecuritybodybooleanNoWhether document-level permissions are enabled; once enabled, accessing a single document requires holding either a document-level or a collection-level permission.
enabledbodybooleanNoWhether 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.
attributesbodyobject[]NoArray of attribute definitions created together with the collection; fields are the same as TablesDB's columns (key and type required, etc.).
indexesbodyobject[]NoDefinition 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
namebodystringYesName, up to 128 characters.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
documentSecuritybodybooleanNoWhether document-level permissions are enabled; once enabled, accessing a single document requires holding either a document-level or a collection-level permission.
enabledbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection 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:

fielddescription
$idIndex ID
keyIndex key
typekey / fulltext / unique / spatial
statusavailable / processing / deleting / stuck / failed
errorFailure 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
typebodystringYesEnum key / fulltext / unique / spatialIndex type: key (regular) / fulltext (fulltext) / unique (unique) / spatial (spatial).
attributesbodystring[]YesArray of attribute keys participating in the index; orders/lengths are positionally aligned with it.
ordersbodystring[]NoSort direction of each indexed column: ASC / DESC (positionally matched with columns).
lengthsbodyinteger[]NoPrefix 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/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:

fielddescription
$idDocument ID
$sequenceDocument sequence number (monotonically increasing within the same collection)
$collectionIdOwning collection ID
$databaseIdparent database ID
$createdAt / $updatedAtcreation/update time
$permissionsArray 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdquerystringNoTransaction ID.
totalquerybooleanNoDefault trueWhen set to false, counting is skipped and total in the response is always 0.
ttlqueryintegerNoDefault 0Response 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)

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdbodystringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
databodyobjectYesData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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)

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentsbodyobject[]YesArray of document data objects, which may contain partial fields (for batch upsert).
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentsbodyobject[]YesArray of document data objects, which may contain partial fields (for batch upsert).
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
queriesbodystring[]NoArray of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
queriesbodystring[]NoArray of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdquerystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
attributepathstringYesAttribute key (path parameter).
valuebodynumberNoIncrement value (number), default 1.
minbodynumberNoLower bound for the decrement; an out-of-bounds value raises an error and is not written.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
attributepathstringYesAttribute key (path parameter).
valuebodynumberNoIncrement value (number), default 1.
maxbodynumberNoUpper bound for the increment; an out-of-bounds value raises an error and is not written.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
transactionIdbodystringNoTransaction 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:

fielddescription
$idTransaction ID, used by row/document endpoints to pass transactionId
$createdAt / $updatedAtcreation/update time
statuspending → committing → committed / rolled_back / failed
operationsNumber of staged operations
expiresAtExpiration 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):

actionadditional requireddescription
create / update / upsert / increment / decrementdocumentId, datasingle-document operation; data is an object of column values
deletedocumentIddeletes a single document
bulkCreate / bulkUpdate / bulkUpsert / bulkDeletedatabatch 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

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoArray 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

ParameterLocationTypeRequiredDefault/enumDescription
ttlbodyintegerNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction ID.
operationsbodyobject[]NoArray 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction ID.
commitbodybooleanNoSet to true to commit the transaction (mutually exclusive with rollback).
rollbackbodybooleanNoSet 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction 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:

fielddescription
$iddatabase ID
namename (≤128 characters)
$createdAt / $updatedAtcreation/update time (ISO 8601)
enabledenabled state; disabling only blocks user-side access, API Keys can still read and write, no data loss
typedatabase 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

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
searchquerystringNoKeyword search, up to 256 characters.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdbodystringYesUnique database ID.
namebodystringYesName, up to 128 characters.
enabledbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
namebodystringNoName, up to 128 characters.
enabledbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique 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:

fielddescription
$idCollection ID
databaseIdparent database ID
namename (≤128 characters)
$permissionsArray of collection-level permission strings
enabledenabled state; disabling only blocks user-side access
documentSecurityWhether 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 / bytesUsedCapacity 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
searchquerystringNoKeyword search, up to 256 characters.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdbodystringYesCollection unique ID.
namebodystringYesName, up to 128 characters.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
documentSecuritybodybooleanNoWhether document-level permissions are enabled; once enabled, accessing a single document requires holding either a document-level or a collection-level permission.
enabledbodybooleanNoWhether 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.
attributesbodyobject[]NoArray of attribute definitions created together with the collection; fields are the same as TablesDB's columns (key and type required, etc.).
indexesbodyobject[]NoDefinition 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
namebodystringNoName, up to 128 characters.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
documentSecuritybodybooleanNoWhether document-level permissions are enabled; once enabled, accessing a single document requires holding either a document-level or a collection-level permission.
enabledbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection 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):

fielddescription
keyAttribute key
typeType identifier (the type of the enum property remains string, distinguished by format: "enum" + elements)
statusavailable / processing / deleting / stuck / failed
errorfailure reason (empty string if no error)
required / arrayrequired / whether an array column
$createdAt / $updatedAtcreation/update time

Lifecycle notes:

GET /v1/databases/{databaseId}/collections/{collectionId}/attributes

List all attributes of a collection (including attribute creation progress status).

Input

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodybooleanNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
elementsbodystring[]YesArray of enum values (non-empty string array); default must be taken from it.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
minbodynumberNoMinimum lower bound.
maxbodynumberNoMaximum upper bound.
defaultbodynumberNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
minbodyintegerNoMinimum lower bound.
maxbodyintegerNoMaximum upper bound.
defaultbodyintegerNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
relatedCollectionIdbodystringYesRelated collection ID. The target collection of a relationship attribute cannot be changed after creation.
typebodystringYesEnum oneToOne / manyToOne / manyToMany / oneToManyRelationship type: oneToOne / manyToOne / manyToMany / oneToMany.
twoWaybodybooleanNoWhether the relationship is two-way. For two-way relationships, twoWayKey must be provided.
keybodystringNoColumn/attribute key. Character constraints are the same as for resource IDs; must be unique within the table/collection.
twoWayKeybodystringNoThe reverse column key on the opposite-side table/collection for a two-way relationship.
onDeletebodystringNoEnum cascade / restrict / setNullConstraint 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
sizebodyintegerYesMaximum number of characters. Required at creation for string/varchar; varchar maximum is 16381.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
sizebodyintegerYesMaximum number of characters. Required at creation for string/varchar; varchar maximum is 16381.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringNoDefault 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.
arraybodybooleanNoWhether it is an array column.
encryptbodybooleanNoWhether 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodybooleanYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
elementsbodystring[]YesArray of enum values (non-empty string array); default must be taken from it.
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
minbodynumberNoMinimum lower bound.
maxbodynumberNoMaximum upper bound.
defaultbodynumberYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
minbodyintegerNoMinimum lower bound.
maxbodyintegerNoMaximum upper bound.
defaultbodyintegerYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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).
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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).
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodyarrayNoDefault 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).
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
onDeletebodystringNoEnum cascade / restrict / setNullConstraint when related rows are deleted: cascade (cascade delete) / restrict (block deletion) / setNull (set null).
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
sizebodyintegerNoMaximum number of characters. Required at creation for string/varchar; varchar maximum is 16381.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/attribute key (path parameter).
requiredbodybooleanYesWhether required. Before making it required, ensure all existing rows have values in this column.
defaultbodystringYesDefault 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.
sizebodyintegerNoMaximum number of characters. Required at creation for string/varchar; varchar maximum is 16381.
newKeybodystringNoNew 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/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:

fielddescription
$idIndex ID
keyIndex key
typekey / fulltext / unique / spatial
statusavailable / processing / deleting / stuck / failed
errorFailure 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
totalquerybooleanNoDefault trueWhen 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keybodystringYesColumn/attribute key. Character constraints are the same as resource IDs; unique within the table/collection.
typebodystringYesEnum key / fulltext / unique / spatialIndex type: key (regular) / fulltext (fulltext) / unique (unique) / spatial (spatial).
attributesbodystring[]YesArray of attribute keys participating in the index; orders/lengths are positionally aligned with it.
ordersbodystring[]NoSort direction of each indexed column: ASC / DESC (positionally matched with columns).
lengthsbodyinteger[]NoPrefix 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
keypathstringYesColumn/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:

fielddescription
$idDocument ID
$sequenceDocument sequence number (monotonically increasing within the same collection)
$collectionIdOwning collection ID
$databaseIdparent database ID
$createdAt / $updatedAtcreation/update time
$permissionsArray 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdquerystringNoTransaction ID.
totalquerybooleanNoDefault trueWhen set to false, counting is skipped and total in the response is always 0.
ttlqueryintegerNoDefault 0Response 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)

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdbodystringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
databodyobjectYesData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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)

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentsbodyobject[]YesArray of document data objects, which may contain partial fields (for batch upsert).
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentsbodyobject[]YesArray of document data objects, which may contain partial fields (for batch upsert).
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
queriesbodystring[]NoArray of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
queriesbodystring[]NoArray of Query query strings (e.g., equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
queriesquerystring[]NoArray of query query strings (e.g. equal("genre","sci-fi"), limit(25)), up to 100 items.
transactionIdquerystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
databodyobjectNoData object with keys as column/attribute keys. Contains only the fields to write/update.
permissionsbodystring[]NoArray of permission strings (e.g. read("any")). By default, no user role is granted; see permissions for semantics.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
attributepathstringYesAttribute key (path parameter).
valuebodynumberNoIncrement value (number), default 1.
minbodynumberNoLower bound for the decrement; an out-of-bounds value raises an error and is not written.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
attributepathstringYesAttribute key (path parameter).
valuebodynumberNoIncrement value (number), default 1.
maxbodynumberNoUpper bound for the increment; an out-of-bounds value raises an error and is not written.
transactionIdbodystringNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
databaseIdpathstringYesUnique database ID.
collectionIdpathstringYesCollection unique ID.
documentIdpathstringYesDocument unique ID. Custom or auto-generated by ID.unique(); character constraints same as resource IDs, up to 36 characters.
transactionIdbodystringNoTransaction 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:

fielddescription
$idTransaction ID, used by row/document endpoints to pass transactionId
$createdAt / $updatedAtcreation/update time
statuspending → committing → committed / rolled_back / failed
operationsNumber of staged operations
expiresAtExpiration 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):

actionadditional requireddescription
create / update / upsert / increment / decrementdocumentId, datasingle-document operation; data is an object of column values
deletedocumentIddeletes a single document
bulkCreate / bulkUpdate / bulkUpsert / bulkDeletedatabatch 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

ParameterLocationTypeRequiredDefault/enumDescription
queriesquerystring[]NoArray 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

ParameterLocationTypeRequiredDefault/enumDescription
ttlbodyintegerNoTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction ID.
operationsbodyobject[]NoArray 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction ID.
commitbodybooleanNoSet to true to commit the transaction (mutually exclusive with rollback).
rollbackbodybooleanNoSet 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

ParameterLocationTypeRequiredDefault/enumDescription
transactionIdpathstringYesTransaction 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

Correspondence with the Server SDK

service.methodEndpoint
TablesDB.list / create / get / update / deleteGET|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 … updatePolygonColumnPOST|PATCH .../columns/{type}, .../columns/{type}/{key}
TablesDB.createRelationshipColumn / updateRelationshipColumnPOST .../columns/relationship、PATCH .../columns/{key}/relationship
TablesDB.updateColumnCommentPATCH .../columns/{key}/comment
TablesDB.listIndexes / createIndex / getIndex / deleteIndex.../indexes CRUD
TablesDB.listRows / createRow / createRows / getRow / updateRow / upsertRow / upsertRows / updateRows / deleteRow / deleteRowssingle-item and batch endpoints (see table above)
TablesDB.incrementRowColumn / decrementRowColumnPATCH .../rows/{rowId}/{column}/increment|decrement
TablesDB.aggregateRowsGET .../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)