We're having lots of fun on Discord! Come and join us! 💬
Docs

Databases API


Client integration with  

The Databases service allows you to create structured collections of documents, query and filter lists of documents, and manage an advanced set of read and write access permissions.

All data returned by the Databases service are represented as structured JSON documents.

The Databases service can contain multiple databases, each database can contain multiple collections. A collection is a group of similarly structured documents. The accepted structure of documents is defined by collection attributes. The collection attributes help you ensure all your user-submitted data is validated and stored according to the collection structure.

Using Appwrite permissions architecture, you can assign read or write access to each collection or document in your project for either a specific user, team, user role, or even grant it with public access (any). You can learn more about how Appwrite handles permissions and access control.

Create Document

POST/v1/databases/{databaseId}/collections/{collectionId}/documents

Create a new Document. Before using this route, you should create a new collection resource using either a server integration API or directly from your database console.

Rate Limits

This endpoint is limited to 120 requests in every 1 minutes per IP address, method and user account. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

HTTP Request

Name Type Description
databaseId required string

Database ID.

collectionId required string

Collection ID. You can create a new collection using the Database service server integration. Make sure to define attributes before creating documents.

documentId required string

Document 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.

data required object

Document data as JSON object.

permissions optional array

An array of permissions strings. By default, only the current user is granted all permissions. Learn more about permissions.

HTTP Response

Status Code Content Type Payload
201  Created application/json Document Object
Example Request
  • import { Client, Databases } from "appwrite";
    
    const client = new Client();
    
    const databases = new Databases(client);
    
    client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    const promise = databases.createDocument('[DATABASE_ID]', '[COLLECTION_ID]', '[DOCUMENT_ID]', {});
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Databases databases = Databases(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = databases.createDocument(
        databaseId: '[DATABASE_ID]',
        collectionId: '[COLLECTION_ID]',
        documentId: '[DOCUMENT_ID]',
        data: {},
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    let client = Client()
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    let databases = Databases(client)
    
    let document = try await databases.createDocument(
        databaseId: "[DATABASE_ID]",
        collectionId: "[COLLECTION_ID]",
        documentId: "[DOCUMENT_ID]",
        data: [:]
    )
    
    
  • import io.appwrite.Client
    import io.appwrite.services.Databases
    
    val client = Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    val databases = Databases(client)
    
    val response = databases.createDocument(
        databaseId = "[DATABASE_ID]",
        collectionId = "[COLLECTION_ID]",
        documentId = "[DOCUMENT_ID]",
        data = mapOf( "a" to "b" ),
    )
    
  • import io.appwrite.Client;
    import io.appwrite.coroutines.CoroutineCallback;
    import io.appwrite.services.Databases;
    
    Client client = new Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2"); // Your project ID
    
    Databases databases = new Databases(client);
    
    databases.createDocument(
        "[DATABASE_ID]",
        "[COLLECTION_ID]",
        "[DOCUMENT_ID]",
        mapOf( "a" to "b" ),
        new CoroutineCallback<>((result, error) -> {
            if (error != null) {
                error.printStackTrace();
                return;
            }
    
            Log.d("Appwrite", result.toString());
        })
    );
    
  • mutation {
        databasesCreateDocument(
            databaseId: "[DATABASE_ID]",
            collectionId: "[COLLECTION_ID]",
            documentId: "[DOCUMENT_ID]",
            data: "{}"
        ) {
            _id
            _collectionId
            _databaseId
            _createdAt
            _updatedAt
            _permissions
            data
        }
    }
    
  • POST /v1/databases/{databaseId}/collections/{collectionId}/documents HTTP/1.1
    Host: HOSTNAME
    Content-Type: application/json
    X-Appwrite-Response-Format: 1.0.0
    X-Appwrite-Project: 5df5acd0d48c2
    X-Appwrite-JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...
    
    {
      "documentId": "[DOCUMENT_ID]",
      "data": {},
      "permissions": ["read(\"any\")"]
    }
    

List Documents

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

Get a list of all the user's documents in a given collection. You can use the query params to filter your results.

HTTP Request

Name Type Description
databaseId required string

Database ID.

collectionId required string

Collection ID. You can create a new collection using the Database service server integration.

queries optional array

Array of query strings generated using the Query class provided by the SDK. Learn more about queries. Maximum of 100 queries are allowed, each 4096 characters long.

HTTP Response

Status Code Content Type Payload
200  OK application/json Documents List Object
Example Request
  • import { Client, Databases } from "appwrite";
    
    const client = new Client();
    
    const databases = new Databases(client);
    
    client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    const promise = databases.listDocuments('[DATABASE_ID]', '[COLLECTION_ID]');
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Databases databases = Databases(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = databases.listDocuments(
        databaseId: '[DATABASE_ID]',
        collectionId: '[COLLECTION_ID]',
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    let client = Client()
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    let databases = Databases(client)
    
    let documentList = try await databases.listDocuments(
        databaseId: "[DATABASE_ID]",
        collectionId: "[COLLECTION_ID]"
    )
    
    
  • import io.appwrite.Client
    import io.appwrite.services.Databases
    
    val client = Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    val databases = Databases(client)
    
    val response = databases.listDocuments(
        databaseId = "[DATABASE_ID]",
        collectionId = "[COLLECTION_ID]",
    )
    
  • import io.appwrite.Client;
    import io.appwrite.coroutines.CoroutineCallback;
    import io.appwrite.services.Databases;
    
    Client client = new Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2"); // Your project ID
    
    Databases databases = new Databases(client);
    
    databases.listDocuments(
        "[DATABASE_ID]",
        "[COLLECTION_ID]",
        new CoroutineCallback<>((result, error) -> {
            if (error != null) {
                error.printStackTrace();
                return;
            }
    
            Log.d("Appwrite", result.toString());
        })
    );
    
  • query {
        databasesListDocuments(
            databaseId: "[DATABASE_ID]",
            collectionId: "[COLLECTION_ID]"
        ) {
            total
            documents {
                _id
                _collectionId
                _databaseId
                _createdAt
                _updatedAt
                _permissions
                data
            }
        }
    }
    
  • GET /v1/databases/{databaseId}/collections/{collectionId}/documents HTTP/1.1
    Host: HOSTNAME
    Content-Type: application/json
    X-Appwrite-Response-Format: 1.0.0
    X-Appwrite-Project: 5df5acd0d48c2
    X-Appwrite-JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...
    
    

Get Document

GET/v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}

Get a document by its unique ID. This endpoint response returns a JSON object with the document data.

HTTP Request

Name Type Description
databaseId required string

Database ID.

collectionId required string

Collection ID. You can create a new collection using the Database service server integration.

documentId required string

Document ID.

HTTP Response

Status Code Content Type Payload
200  OK application/json Document Object
Example Request
  • import { Client, Databases } from "appwrite";
    
    const client = new Client();
    
    const databases = new Databases(client);
    
    client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    const promise = databases.getDocument('[DATABASE_ID]', '[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Databases databases = Databases(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = databases.getDocument(
        databaseId: '[DATABASE_ID]',
        collectionId: '[COLLECTION_ID]',
        documentId: '[DOCUMENT_ID]',
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    let client = Client()
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    let databases = Databases(client)
    
    let document = try await databases.getDocument(
        databaseId: "[DATABASE_ID]",
        collectionId: "[COLLECTION_ID]",
        documentId: "[DOCUMENT_ID]"
    )
    
    
  • import io.appwrite.Client
    import io.appwrite.services.Databases
    
    val client = Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    val databases = Databases(client)
    
    val response = databases.getDocument(
        databaseId = "[DATABASE_ID]",
        collectionId = "[COLLECTION_ID]",
        documentId = "[DOCUMENT_ID]"
    )
    
  • import io.appwrite.Client;
    import io.appwrite.coroutines.CoroutineCallback;
    import io.appwrite.services.Databases;
    
    Client client = new Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2"); // Your project ID
    
    Databases databases = new Databases(client);
    
    databases.getDocument(
        "[DATABASE_ID]",
        "[COLLECTION_ID]",
        "[DOCUMENT_ID]"
        new CoroutineCallback<>((result, error) -> {
            if (error != null) {
                error.printStackTrace();
                return;
            }
    
            Log.d("Appwrite", result.toString());
        })
    );
    
  • query {
        databasesGetDocument(
            databaseId: "[DATABASE_ID]",
            collectionId: "[COLLECTION_ID]",
            documentId: "[DOCUMENT_ID]"
        ) {
            _id
            _collectionId
            _databaseId
            _createdAt
            _updatedAt
            _permissions
            data
        }
    }
    
  • GET /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId} HTTP/1.1
    Host: HOSTNAME
    Content-Type: application/json
    X-Appwrite-Response-Format: 1.0.0
    X-Appwrite-Project: 5df5acd0d48c2
    X-Appwrite-JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...
    
    

Update Document

PATCH/v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}

Update a document by its unique ID. Using the patch method you can pass only specific fields that will get updated.

Rate Limits

This endpoint is limited to 120 requests in every 1 minutes per IP address, method and user account. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

HTTP Request

Name Type Description
databaseId required string

Database ID.

collectionId required string

Collection ID.

documentId required string

Document ID.

data optional object

Document data as JSON object. Include only attribute and value pairs to be updated.

permissions optional array

An array of permissions strings. By default, the current permissions are inherited. Learn more about permissions.

HTTP Response

Status Code Content Type Payload
200  OK application/json Document Object
Example Request
  • import { Client, Databases } from "appwrite";
    
    const client = new Client();
    
    const databases = new Databases(client);
    
    client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    const promise = databases.updateDocument('[DATABASE_ID]', '[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Databases databases = Databases(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = databases.updateDocument(
        databaseId: '[DATABASE_ID]',
        collectionId: '[COLLECTION_ID]',
        documentId: '[DOCUMENT_ID]',
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    let client = Client()
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    let databases = Databases(client)
    
    let document = try await databases.updateDocument(
        databaseId: "[DATABASE_ID]",
        collectionId: "[COLLECTION_ID]",
        documentId: "[DOCUMENT_ID]"
    )
    
    
  • import io.appwrite.Client
    import io.appwrite.services.Databases
    
    val client = Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    val databases = Databases(client)
    
    val response = databases.updateDocument(
        databaseId = "[DATABASE_ID]",
        collectionId = "[COLLECTION_ID]",
        documentId = "[DOCUMENT_ID]",
    )
    
  • import io.appwrite.Client;
    import io.appwrite.coroutines.CoroutineCallback;
    import io.appwrite.services.Databases;
    
    Client client = new Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2"); // Your project ID
    
    Databases databases = new Databases(client);
    
    databases.updateDocument(
        "[DATABASE_ID]",
        "[COLLECTION_ID]",
        "[DOCUMENT_ID]",
        new CoroutineCallback<>((result, error) -> {
            if (error != null) {
                error.printStackTrace();
                return;
            }
    
            Log.d("Appwrite", result.toString());
        })
    );
    
  • mutation {
        databasesUpdateDocument(
            databaseId: "[DATABASE_ID]",
            collectionId: "[COLLECTION_ID]",
            documentId: "[DOCUMENT_ID]"
        ) {
            _id
            _collectionId
            _databaseId
            _createdAt
            _updatedAt
            _permissions
            data
        }
    }
    
  • PATCH /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId} HTTP/1.1
    Host: HOSTNAME
    Content-Type: application/json
    X-Appwrite-Response-Format: 1.0.0
    X-Appwrite-Project: 5df5acd0d48c2
    X-Appwrite-JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...
    
    {
      "data": {},
      "permissions": ["read(\"any\")"]
    }
    

Delete Document

DELETE/v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId}

Delete a document by its unique ID.

Rate Limits

This endpoint is limited to 60 requests in every 1 minutes per IP address, method and user account. We use rate limits to avoid service abuse by users and as a security practice. Learn more about rate limiting.

HTTP Request

Name Type Description
databaseId required string

Database ID.

collectionId required string

Collection ID. You can create a new collection using the Database service server integration.

documentId required string

Document ID.

HTTP Response

Status Code Content Type Payload
204  No Content - -
Example Request
  • import { Client, Databases } from "appwrite";
    
    const client = new Client();
    
    const databases = new Databases(client);
    
    client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
    ;
    
    const promise = databases.deleteDocument('[DATABASE_ID]', '[COLLECTION_ID]', '[DOCUMENT_ID]');
    
    promise.then(function (response) {
        console.log(response); // Success
    }, function (error) {
        console.log(error); // Failure
    });
  • import 'package:appwrite/appwrite.dart';
    
    void main() { // Init SDK
      Client client = Client();
      Databases databases = Databases(client);
    
      client
        .setEndpoint('https://[HOSTNAME_OR_IP]/v1') // Your API Endpoint
        .setProject('5df5acd0d48c2') // Your project ID
      ;
      Future result = databases.deleteDocument(
        databaseId: '[DATABASE_ID]',
        collectionId: '[COLLECTION_ID]',
        documentId: '[DOCUMENT_ID]',
      );
    
      result
        .then((response) {
          print(response);
        }).catchError((error) {
          print(error.response);
      });
    }
    
  • import Appwrite
    
    let client = Client()
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    let databases = Databases(client)
    
    let result = try await databases.deleteDocument(
        databaseId: "[DATABASE_ID]",
        collectionId: "[COLLECTION_ID]",
        documentId: "[DOCUMENT_ID]"
    )
    
    
  • import io.appwrite.Client
    import io.appwrite.services.Databases
    
    val client = Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2") // Your project ID
    
    val databases = Databases(client)
    
    val response = databases.deleteDocument(
        databaseId = "[DATABASE_ID]",
        collectionId = "[COLLECTION_ID]",
        documentId = "[DOCUMENT_ID]"
    )
    
  • import io.appwrite.Client;
    import io.appwrite.coroutines.CoroutineCallback;
    import io.appwrite.services.Databases;
    
    Client client = new Client(context)
        .setEndpoint("https://[HOSTNAME_OR_IP]/v1") // Your API Endpoint
        .setProject("5df5acd0d48c2"); // Your project ID
    
    Databases databases = new Databases(client);
    
    databases.deleteDocument(
        "[DATABASE_ID]",
        "[COLLECTION_ID]",
        "[DOCUMENT_ID]"
        new CoroutineCallback<>((result, error) -> {
            if (error != null) {
                error.printStackTrace();
                return;
            }
    
            Log.d("Appwrite", result.toString());
        })
    );
    
  • mutation {
        databasesDeleteDocument(
            databaseId: "[DATABASE_ID]",
            collectionId: "[COLLECTION_ID]",
            documentId: "[DOCUMENT_ID]"
        ) {
            status
        }
    }
    
  • DELETE /v1/databases/{databaseId}/collections/{collectionId}/documents/{documentId} HTTP/1.1
    Host: HOSTNAME
    Content-Type: application/json
    X-Appwrite-Response-Format: 1.0.0
    X-Appwrite-Project: 5df5acd0d48c2
    X-Appwrite-JWT: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ...