Appwrite TablesDB API

openapi: 3.0.0
info:
  title: Appwrite TablesDB API
  description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
  version: 2.0.0
  termsOfService: https://appwrite.io/policy/terms
  contact:
    name: Appwrite Team
    url: https://appwrite.io/support
    email: team@appwrite.io
  license:
    name: BSD-3-Clause
    url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
  description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
  description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
  variables:
    region:
      default: fra
      description: Appwrite Cloud region.
tags:
- name: tablesDB
  description: The TablesDB service allows you to create structured tables of columns, query and filter lists of rows
paths:
  /tablesdb:
    get:
      summary: List databases
      operationId: tablesDBList
      tags:
      - tablesDB
      description: Get a list of all databases from the current Appwrite project. You can use the search parameter to filter your results.
      responses:
        '200':
          description: Databases List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/databaseList'
      deprecated: false
      x-appwrite:
        group: tablesdb
        demo: tablesdb/list.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following columns: name'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: search
        description: 'Search term to filter your list results. Max length: 256 chars.'
        required: false
        schema:
          type: string
          example: <SEARCH>
          default: ''
        in: query
      - name: total
        description: When set to false, the total count returned will be 0 and will not be calculated.
        required: false
        schema:
          type: boolean
          example: false
          default: true
        in: query
    post:
      summary: Create database
      operationId: tablesDBCreate
      tags:
      - tablesDB
      description: 'Create a new Database.

        '
      responses:
        '201':
          description: Database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/database'
      deprecated: false
      x-appwrite:
        group: tablesdb
        demo: tablesdb/create.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                databaseId:
                  description: Unique Id. Choose a custom ID or generate a random ID with `ID.unique()`. Valid chars are a-z, A-Z, 0-9, period, hyphen, and underscore. Can't start with a special char. Max length is 36 chars.
                  type: string
                  example: <DATABASE_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                name:
                  description: 'Database name. Max length: 128 chars.'
                  type: string
                  example: <NAME>
                enabled:
                  description: Is the database enabled? When set to 'disabled', users cannot access the database but Server SDKs with an API key can still read and write to the database. No data is lost when this is toggled.
                  type: boolean
                  default: true
                  example: false
                specification:
                  description: Database specification. Defaults to `serverless`, which creates the database on the shared pool. Any other value provisions a dedicated database on that specification.
                  type: string
                  default: serverless
                  example: serverless
                replicas:
                  description: Number of high availability replicas (0-5) for the dedicated database backing this database. Requires a dedicated `specification`; must be 0 for a serverless database. High availability is enabled when greater than 0.
                  type: integer
                  default: 0
                  example: 0
                  format: int32
                syncMode:
                  description: 'Replication sync mode for the dedicated database backing this database. Requires a dedicated `specification`; the mode is only in force once there is at least one replica. Allowed values: async, sync, quorum.'
                  type: string
                  example: async
                  nullable: true
              required:
              - databaseId
              - name
  /tablesdb/specifications:
    get:
      summary: List specifications
      operationId: tablesDBListSpecifications
      tags:
      - tablesDB
      description: List the dedicated database specifications available on the current plan. Each specification reports its resource limits, its own prices and overage rates, and whether it is enabled for the organization.
      responses:
        '200':
          description: SpecificationList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseSpecificationList'
      deprecated: false
      x-appwrite:
        group: tablesdb
        demo: tablesdb/list-specifications.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
  /tablesdb/transactions:
    get:
      summary: List transactions
      operationId: tablesDBListTransactions
      tags:
      - tablesDB
      description: List transactions across all databases.
      responses:
        '200':
          description: Transaction List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transactionList'
      deprecated: false
      x-appwrite:
        group: transactions
        demo: tablesdb/list-transactions.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope:
        - documents.read
        - rows.read
        platforms:
        - console
        - server
        - client
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
          client:
            Project: []
      security:
      - Project: []
        Key: []
        Session: []
        JWT: []
      parameters:
      - name: queries
        description: Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries).
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
    post:
      summary: Create transaction
      operationId: tablesDBCreateTransaction
      tags:
      - tablesDB
      description: Create a new transaction.
      responses:
        '201':
          description: Transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transaction'
      deprecated: false
      x-appwrite:
        group: transactions
        demo: tablesdb/create-transaction.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope:
        - documents.write
        - rows.write
        platforms:
        - console
        - server
        - client
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
          client:
            Project: []
      security:
      - Project: []
        Key: []
        Session: []
        JWT: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                ttl:
                  description: Seconds before the transaction expires.
                  type: integer
                  default: 300
                  example: 60
                  format: int32
  /tablesdb/transactions/{transactionId}:
    get:
      summary: Get transaction
      operationId: tablesDBGetTransaction
      tags:
      - tablesDB
      description: Get a transaction by its unique ID.
      responses:
        '200':
          description: Transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transaction'
      deprecated: false
      x-appwrite:
        group: transactions
        demo: tablesdb/get-transaction.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope:
        - documents.read
        - rows.read
        platforms:
        - console
        - server
        - client
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
          client:
            Project: []
      security:
      - Project: []
        Key: []
        Session: []
        JWT: []
      parameters:
      - name: transactionId
        description: Transaction ID.
        required: true
        schema:
          type: string
          example: <TRANSACTION_ID>
        in: path
    patch:
      summary: Update transaction
      operationId: tablesDBUpdateTransaction
      tags:
      - tablesDB
      description: Update a transaction, to either commit or roll back its operations.
      responses:
        '200':
          description: Transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transaction'
      deprecated: false
      x-appwrite:
        group: transactions
        demo: tablesdb/update-transaction.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope:
        - documents.write
        - rows.write
        platforms:
        - console
        - server
        - client
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
          client:
            Project: []
      security:
      - Project: []
        Key: []
        Session: []
        JWT: []
      parameters:
      - name: transactionId
        description: Transaction ID.
        required: true
        schema:
          type: string
          example: <TRANSACTION_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                commit:
                  description: Commit transaction?
                  type: boolean
                  default: false
                  example: false
                rollback:
                  description: Rollback transaction?
                  type: boolean
                  default: false
                  example: false
    delete:
      summary: Delete transaction
      operationId: tablesDBDeleteTransaction
      tags:
      - tablesDB
      description: Delete a transaction by its unique ID.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: transactions
        demo: tablesdb/delete-transaction.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope:
        - documents.write
        - rows.write
        platforms:
        - console
        - server
        - client
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
          client:
            Project: []
      security:
      - Project: []
        Key: []
        Session: []
        JWT: []
      parameters:
      - name: transactionId
        description: Transaction ID.
        required: true
        schema:
          type: string
          example: <TRANSACTION_ID>
        in: path
  /tablesdb/transactions/{transactionId}/operations:
    post:
      summary: Create operations
      operationId: tablesDBCreateOperations
      tags:
      - tablesDB
      description: Create multiple operations in a single transaction.
      responses:
        '201':
          description: Transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transaction'
      deprecated: false
      x-appwrite:
        group: transactions
        demo: tablesdb/create-operations.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope:
        - documents.write
        - rows.write
        platforms:
        - console
        - server
        - client
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
          client:
            Project: []
      security:
      - Project: []
        Key: []
        Session: []
        JWT: []
      parameters:
      - name: transactionId
        description: Transaction ID.
        required: true
        schema:
          type: string
          example: <TRANSACTION_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                operations:
                  description: Array of staged operations.
                  type: array
                  default: []
                  example:
                  - action: create
                    databaseId: <DATABASE_ID>
                    tableId: <TABLE_ID>
                    rowId: <ROW_ID>
                    data:
                      name: Walter O'Brien
                  items:
                    type: object
  /tablesdb/{databaseId}:
    get:
      summary: Get database
      operationId: tablesDBGet
      tags:
      - tablesDB
      description: Get a database by its unique ID. This endpoint response returns a JSON object with the database metadata.
      responses:
        '200':
          description: Database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/database'
      deprecated: false
      x-appwrite:
        group: tablesdb
        demo: tablesdb/get.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
    put:
      summary: Update database
      operationId: tablesDBUpdate
      tags:
      - tablesDB
      description: Update a database by its unique ID.
      responses:
        '200':
          description: Database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/database'
      deprecated: false
      x-appwrite:
        group: tablesdb
        demo: tablesdb/update.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: 'Database name. Max length: 128 chars.'
                  type: string
                  example: <NAME>
                enabled:
                  description: Is database enabled? When set to 'disabled', users cannot access the database but Server SDKs with an API key can still read and write to the database. No data is lost when this is toggled.
                  type: boolean
                  default: true
                  example: false
                specification:
                  description: Database specification. Resizing between dedicated specifications changes cpu, memory, storage and the connection ceiling via a rolling cutover with zero downtime. Moving a `serverless` database onto a dedicated specification is a data migration, not a resize.
                  type: string
                  example: serverless
                  nullable: true
                replicas:
                  description: Number of high availability replicas (0-5) for the dedicated database backing this database. Only valid when the database is backed by a dedicated specification. High availability is enabled when greater than 0.
                  type: integer
                  example: 0
                  format: int32
                  nullable: true
                syncMode:
                  description: 'Replication sync mode for the dedicated database backing this database. Only valid when the database is backed by a dedicated specification; the mode is only in force once there is at least one replica. Allowed values: async, sync, quorum.'
                  type: string
                  example: async
                  nullable: true
    delete:
      summary: Delete database
      operationId: tablesDBDelete
      tags:
      - tablesDB
      description: Delete a database by its unique ID. Only API keys with with databases.write scope can delete a database.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: tablesdb
        demo: tablesdb/delete.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
  /tablesdb/{databaseId}/failovers:
    post:
      summary: Create failover
      operationId: tablesDBCreateFailover
      tags:
      - tablesDB
      description: Trigger a manual failover for a dedicated database with high availability enabled. Promotes a replica to primary. The failover runs asynchronously; poll the database document for status updates. A database left mid-operation also accepts this call as a repair once nothing is driving the operation it is stuck in. Repairing a failover that did not finish, a `failed` database, a stranded upgrade or migrate, or a stranded compute resize additionally requires `targetReplicaId` to name the member to promote, because the default target may be the member that operation already promoted.
      responses:
        '202':
          description: DedicatedDatabase
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabase'
      deprecated: false
      x-appwrite:
        group: failovers
        demo: tablesdb/create-failover.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                targetReplicaId:
                  description: Target replica ID to promote. If not specified, the healthiest replica is selected.
                  type: string
                  example: <TARGET_REPLICA_ID>
                  nullable: true
  /tablesdb/{databaseId}/migrations:
    get:
      summary: List migrations
      operationId: tablesDBListMigrations
      tags:
      - tablesDB
      description: List the dedicated migrations for a TablesDB database. A database has at most one in-flight migration.
      responses:
        '200':
          description: Database Migrations List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/databaseMigrationList'
      deprecated: false
      x-appwrite:
        group: migrations
        demo: tablesdb/list-migrations.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: migrations.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
    post:
      summary: Create migration
      operationId: tablesDBCreateMigration
      tags:
      - tablesDB
      description: Start migrating a serverless TablesDB database onto a dedicated MySQL compute. Data is copied to the target while the source stays live, with a brief read-only window during cutover.
      responses:
        '201':
          description: Database Migration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/databaseMigration'
      deprecated: false
      x-appwrite:
        group: migrations
        demo: tablesdb/create-migration.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: migrations.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                specification:
                  description: Dedicated compute specification to provision as the migration target (e.g. s-2vcpu-4gb). The migration always targets a dedicated compute, so `serverless` is not accepted.
                  type: string
                  example: s-1vcpu-1gb
                autoCutover:
                  description: Whether to cut over automatically once the copy is verified. When disabled the migration parks at ready_to_cutover and holds there until the cutover is performed manually.
                  type: boolean
                  default: true
                  example: false
              required:
              - specification
  /tablesdb/{databaseId}/migrations/{migrationId}:
    get:
      summary: Get migration
      operationId: tablesDBGetMigration
      tags:
      - tablesDB
      description: Get a single dedicated migration for a TablesDB database by its ID.
      responses:
        '200':
          description: Database Migration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/databaseMigration'
      deprecated: false
      x-appwrite:
        group: migrations
        demo: tablesdb/get-migration.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: migrations.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: migrationId
        description: Migration ID.
        required: true
        schema:
          type: string
          example: <MIGRATION_ID>
        in: path
    delete:
      summary: Delete migration
      operationId: tablesDBDeleteMigration
      tags:
      - tablesDB
      description: Abort an in-flight TablesDB dedicated migration. Only allowed before cutover; once the migration has cut over it cannot be aborted.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: migrations
        demo: tablesdb/delete-migration.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: migrations.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: migrationId
        description: Migration ID.
        required: true
        schema:
          type: string
          example: <MIGRATION_ID>
        in: path
  /tablesdb/{databaseId}/migrations/{migrationId}/cutovers:
    post:
      summary: Cutover migration
      operationId: tablesDBCreateCutover
      tags:
      - tablesDB
      description: 'Cut a verified TablesDB migration over to its dedicated compute. Only applies to a migration created with `autoCutover` disabled, which waits at `ready_to_cutover` until this is called. The routing flip happens shortly after this returns, with a brief read-only window. One call buys one attempt: a cutover that fails a check returns the migration to `verifying` and parks it again, so call this once more to retry.'
      responses:
        '200':
          description: Database Migration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/databaseMigration'
      deprecated: false
      x-appwrite:
        group: migrations
        demo: tablesdb/create-cutover.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: migrations.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: migrationId
        description: Migration ID.
        required: true
        schema:
          type: string
          example: <MIGRATION_ID>
        in: path
  /tablesdb/{databaseId}/operations:
    get:
      summary: List operations
      operationId: tablesDBListOperations
      tags:
      - tablesDB
      description: List the lifecycle operations recorded for a dedicated database, newest first. Every provision, update, restore, backup and replication action is recorded here with its outcome, including an attempt that was abandoned because another worker took over the database.
      responses:
        '200':
          description: OperationList
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseOperationList'
      deprecated: false
      x-appwrite:
        group: operations
        demo: tablesdb/list-operations.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: databaseId
        description: Database ID.
        required: true
        schema:
          type: string
          example: <DATABASE_ID>
        in: path
      - name: status
        description: Filter by operation status.
        required: false
        schema:
          type: string
          example: queued
        in: query
      - name: limit
        description: Maximum number of operations to return.
        required: false
        schema:
          type: integer
          format: int32
          example: 1
          default: 25
        in: query
      - name: offset
        description: Number of operations to skip.
        required: false
        schema:
          type: integer
          format: int32
          example: 0
          default: 0
        in: query
  /tablesdb/{databaseId}/replicas:
    get:
      summary: Get replicas
      operationId: tablesDBGetReplicas
      tags:
      - tablesDB
      description: Get high availability status for a dedicated database. Returns replica statuses, replication lag, and sync mode.
      responses:
        '200':
          description: Replicas
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dedicatedDatabaseReplicas'
      deprecated: false
      x-appwrite:
        group: replicas
        demo: tablesdb/get-replicas.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: databases.read
        platforms:
        - console
        - se

# --- truncated at 32 KB (301 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appwrite/refs/heads/main/openapi/appwrite-tablesdb-api-openapi.yml