Appwrite DocumentsDB API

openapi: 3.0.0
info:
  title: Appwrite DocumentsDB 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: documentsDB
  description: Appwrite documentsDB service.
paths:
  /documentsdb:
    get:
      summary: List databases
      operationId: documentsDBList
      tags:
      - documentsDB
      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: documentsdb
        demo: documentsdb/list.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.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: 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: documentsDBCreate
      tags:
      - documentsDB
      description: 'Create a new Database.

        '
      responses:
        '201':
          description: Database
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/database'
      deprecated: false
      x-appwrite:
        group: documentsdb
        demo: documentsdb/create.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.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
  /documentsdb/specifications:
    get:
      summary: List specifications
      operationId: documentsDBListSpecifications
      tags:
      - documentsDB
      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: documentsdb
        demo: documentsdb/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: []
  /documentsdb/transactions:
    get:
      summary: List transactions
      operationId: documentsDBListTransactions
      tags:
      - documentsDB
      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: documentsdb/list-transactions.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.documents.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: documentsDBCreateTransaction
      tags:
      - documentsDB
      description: Create a new transaction.
      responses:
        '201':
          description: Transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transaction'
      deprecated: false
      x-appwrite:
        group: transactions
        demo: documentsdb/create-transaction.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.documents.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
  /documentsdb/transactions/{transactionId}:
    get:
      summary: Get transaction
      operationId: documentsDBGetTransaction
      tags:
      - documentsDB
      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: documentsdb/get-transaction.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.documents.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: documentsDBUpdateTransaction
      tags:
      - documentsDB
      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: documentsdb/update-transaction.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.documents.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: documentsDBDeleteTransaction
      tags:
      - documentsDB
      description: Delete a transaction by its unique ID.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: transactions
        demo: documentsdb/delete-transaction.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.documents.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
  /documentsdb/transactions/{transactionId}/operations:
    post:
      summary: Create operations
      operationId: documentsDBCreateOperations
      tags:
      - documentsDB
      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: documentsdb/create-operations.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.documents.write
        platforms:
        - server
        - client
        packaging: false
        public: true
        auth:
          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>
                    collectionId: <COLLECTION_ID>
                    documentId: <DOCUMENT_ID>
                    data:
                      name: Walter O'Brien
                  items:
                    type: object
  /documentsdb/{databaseId}:
    get:
      summary: Get database
      operationId: documentsDBGet
      tags:
      - documentsDB
      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: documentsdb
        demo: documentsdb/get.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.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: documentsDBUpdate
      tags:
      - documentsDB
      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: documentsdb
        demo: documentsdb/update.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.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
              required:
              - name
    delete:
      summary: Delete database
      operationId: documentsDBDelete
      tags:
      - documentsDB
      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: documentsdb
        demo: documentsdb/delete.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.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
  /documentsdb/{databaseId}/collections:
    get:
      summary: List collections
      operationId: documentsDBListCollections
      tags:
      - documentsDB
      description: Get a list of all collections that belong to the provided databaseId. You can use the search parameter to filter your results.
      responses:
        '200':
          description: Collections List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collectionList'
      deprecated: false
      x-appwrite:
        group: collections
        demo: documentsdb/list-collections.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.collections.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: 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 attributes: name, enabled, documentSecurity'
        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 collection
      operationId: documentsDBCreateCollection
      tags:
      - documentsDB
      description: Create a new Collection. Before using this route, you should create a new database resource using either a [server integration](https://appwrite.io/docs/server/databases#documentsDBCreateCollection) API or directly from your database console.
      responses:
        '201':
          description: Collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collection'
      deprecated: false
      x-appwrite:
        group: collections
        demo: documentsdb/create-collection.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.collections.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:
                collectionId:
                  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: <COLLECTION_ID>
                  x-appwrite:
                    idGenerator: ID.unique
                name:
                  description: 'Collection name. Max length: 128 chars.'
                  type: string
                  example: <NAME>
                permissions:
                  description: An array of permissions strings. By default, no user is granted with any permissions. [Learn more about permissions](https://appwrite.io/docs/permissions).
                  type: array
                  example:
                  - read("any")
                  items:
                    type: string
                  nullable: true
                documentSecurity:
                  description: Enables configuring permissions for individual documents. A user needs one of document or collection level permissions to access a document. [Learn more about permissions](https://appwrite.io/docs/permissions).
                  type: boolean
                  default: false
                  example: false
                enabled:
                  description: Is collection enabled? When set to 'disabled', users cannot access the collection but Server SDKs with and API key can still read and write to the collection. No data is lost when this is toggled.
                  type: boolean
                  default: true
                  example: false
                attributes:
                  description: 'Array of attribute definitions to create. Each attribute should contain: key (string), type (string: string, varchar, text, mediumtext, longtext, integer, bigint, double, boolean, datetime, point, linestring, polygon, email, url, ip, enum), size (integer, required for string and varchar types), required (boolean, optional), default (mixed, optional), array (boolean, optional), and type-specific options.'
                  type: array
                  default: []
                  items:
                    type: object
                indexes:
                  description: 'Array of index definitions to create. Each index should contain: key (string), type (string: key, fulltext, unique, spatial), attributes (array of attribute keys), orders (array of ASC/DESC, optional), and lengths (array of integers, optional).'
                  type: array
                  default: []
                  items:
                    type: object
              required:
              - collectionId
              - name
  /documentsdb/{databaseId}/collections/{collectionId}:
    get:
      summary: Get collection
      operationId: documentsDBGetCollection
      tags:
      - documentsDB
      description: Get a collection by its unique ID. This endpoint response returns a JSON object with the collection metadata.
      responses:
        '200':
          description: Collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collection'
      deprecated: false
      x-appwrite:
        group: collections
        demo: documentsdb/get-collection.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.collections.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: collectionId
        description: Collection ID.
        required: true
        schema:
          type: string
          example: <COLLECTION_ID>
        in: path
    put:
      summary: Update collection
      operationId: documentsDBUpdateCollection
      tags:
      - documentsDB
      description: Update a collection by its unique ID.
      responses:
        '200':
          description: Collection
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/collection'
      deprecated: false
      x-appwrite:
        group: collections
        demo: documentsdb/update-collection.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.collections.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: collectionId
        description: Collection ID.
        required: true
        schema:
          type: string
          example: <COLLECTION_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: 'Collection name. Max length: 128 chars.'
                  type: string
                  example: <NAME>
                permissions:
                  description: An array of permission strings. By default, the current permissions are inherited. [Learn more about permissions](https://appwrite.io/docs/permissions).
                  type: array
                  example:
                  - read("any")
                  items:
                    type: string
                documentSecurity:
                  description: Enables configuring permissions for individual documents. A user needs one of document or collection level permissions to access a document. [Learn more about permissions](https://appwrite.io/docs/permissions).
                  type: boolean
                  default: false
                  example: false
                enabled:
                  description: Is collection enabled? When set to 'disabled', users cannot access the collection but Server SDKs with and API key can still read and write to the collection. No data is lost when this is toggled.
                  type: boolean
                  default: true
                  example: false
                purge:
                  description: When true, purge all cached list responses for this collection as part of the update. Use this to force readers to see fresh data immediately instead of waiting for the cache TTL to expire.
                  type: boolean
                  default: false
                  example: false
              required:
              - name
    delete:
      summary: Delete collection
      operationId: documentsDBDeleteCollection
      tags:
      - documentsDB
      description: Delete a collection by its unique ID. Only users with write permissions have access to delete this resource.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: collections
        demo: documentsdb/delete-collection.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: documentsdb.collections.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: collectionId
        description: Collection ID.
        required: true
        schema:
          type: string
          example: <COLLECTION_ID>
        in: path
  /documentsdb/{databaseId}/collections/{collectionId}/documents:
    get:
      summary: List documents
      operationId: documentsDBListDocuments
      tags:
      - documentsDB
      description: Get a list of all the user's documents in a given collection. You can use the query params to filter your results.
      responses:
        '200':
          description: Documents List
          content:
            application/json:
         

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