Azure Cosmos DB REST API Reference

Comprehensive documentation for interacting with Azure Cosmos DB using its RESTful API.

Introduction

Azure Cosmos DB is a globally distributed, multi-model database service. The REST API allows you to perform all database operations programmatically. This document provides a detailed reference for using the Cosmos DB REST API.

Authentication

All requests to the Cosmos DB REST API must be authenticated. The primary method of authentication is using an authorization header with a Shared Key or a Resource Token.

Shared Key Authentication

Requests must include an Authorization header with the following format:

Authorization: type base64EncodedToken

The type is master for master keys or resource for resource tokens.

The base64EncodedToken is a Base64 encoded string of:

UTF-8-Encoding-Of-StringToSign + "\n" + Base64-Encoded-HMAC-SHA256(UTF-8-Encoding-Of-StringToSign, Base64-Decoding-Of-The-Keys)

The StringToSign is constructed as follows:

HTTPVerb\n
            ResourceType\n
            CollectionName\n
            PartitionKeyRangeID\n
            Date\n
            ISO8601Date\n
            ResourceID\n
            Version\n

For detailed information on constructing the token, refer to the official Cosmos DB REST API Authentication documentation.

Common Headers

The following headers are commonly used in requests:

Header Description
x-ms-version Specifies the version of the REST API to use. Currently, 2018-12-12 is recommended.
x-ms-date The UTC date and time of the request in RFC 7231 format (e.g., Tue, 15 Nov 1994 08:12:31 GMT).
Authorization Authentication credentials (as described above).
x-ms-continuation Used for paginated results from queries.
x-ms-documentdb-partitionkey Specifies the partition key value for operations on partitioned collections.

Key Resources and Endpoints

The Cosmos DB REST API exposes various resources, each with its own set of operations.

Databases

HTTP Method Endpoint Description
GET /dbs Lists all databases in the account.
POST /dbs Creates a new database.
GET /dbs/{db_id} Retrieves a specific database.
DELETE /dbs/{db_id} Deletes a specific database.

Collections (Containers)

HTTP Method Endpoint Description
GET /dbs/{db_id}/colls Lists all collections in a database.
POST /dbs/{db_id}/colls Creates a new collection.
GET /dbs/{db_id}/colls/{coll_id} Retrieves a specific collection.
PUT /dbs/{db_id}/colls/{coll_id} Updates a specific collection (e.g., indexing policy, throughput).
DELETE /dbs/{db_id}/colls/{coll_id} Deletes a specific collection.

Documents

HTTP Method Endpoint Description
GET /dbs/{db_id}/colls/{coll_id}/docs Lists all documents in a collection.
POST /dbs/{db_id}/colls/{coll_id}/docs Creates a new document.
GET /dbs/{db_id}/colls/{coll_id}/docs/{doc_id} Retrieves a specific document.
PUT /dbs/{db_id}/colls/{coll_id}/docs/{doc_id} Replaces an existing document.
PATCH /dbs/{db_id}/colls/{coll_id}/docs/{doc_id} Partially updates an existing document.
DELETE /dbs/{db_id}/colls/{coll_id}/docs/{doc_id} Deletes a specific document.

Stored Procedures, Triggers, User Defined Functions (UDFs)

These resources follow a similar pattern, typically under the collection resource (e.g., /dbs/{db_id}/colls/{coll_id}/sprocs, /dbs/{db_id}/colls/{coll_id}/triggers, /dbs/{db_id}/colls/{coll_id}/udfs).

Queries

Queries are executed using the POST method on the collection's document endpoint:

POST /dbs/{db_id}/colls/{coll_id}/docs/​

The request body should contain a JSON object with the query details:

{
    "query": "SELECT * FROM c WHERE c.category = 'books'",
    "parameters": [
        { "name": "@category", "value": "books" }
    ]
}

The request must also include the x-ms-documentdb-isquery header set to true.

Response Codes

Common HTTP response codes you may encounter:

Code Description
200 OK The request was successful.
201 Created A resource was successfully created.
204 No Content The request was successful, but there is no content to return (e.g., delete operation).
400 Bad Request The request was malformed or invalid.
401 Unauthorized Authentication failed.
404 Not Found The requested resource was not found.
409 Conflict A conflict occurred (e.g., attempting to create a resource that already exists).
429 Too Many Requests Request rate limit exceeded.

Further Reading