Azure Cosmos DB REST API – MSDN Documentation

Overview

The Azure Cosmos DB REST API provides a programmable interface that you can use to manage databases, containers, items, triggers, user-defined functions, and stored procedures directly over HTTP. It follows the same consistency, throughput, and globally distributed nature of the service, allowing you to integrate Cosmos DB with any platform or language.

Authentication

All requests must be authorized using the Shared Key authentication scheme, which relies on your account's primary or secondary key. The Authorization header contains a signature generated from the request method, resource type, resource ID, date, and your key.

// Sample Node.js code to generate the Authorization header
const crypto = require('crypto');

function getAuthHeader(verb, resourceType, resourceId, masterKey) {
    const date = new Date().toUTCString();
    const text = `${verb.toLowerCase()}\n${resourceType.toLowerCase()}\n${resourceId}\n${date}\n\n`;
    const signature = crypto.createHmac('sha256', Buffer.from(masterKey, 'base64'))
                          .update(text, 'utf8')
                          .digest('base64');
    return `type=master&ver=1.0&sig=${signature}`;
}

Endpoints

The base URI for the REST API is:

https://{your-account}.documents.azure.com

Key endpoints include:

Operation	HTTP Method	URI Template
List Databases	GET	/dbs
Create Database	POST	/dbs
Query Items	POST	/dbs/{db-id}/colls/{coll-id}/docs
Read Item	GET	/dbs/{db-id}/colls/{coll-id}/docs/{doc-id}
Replace Item	PUT	/dbs/{db-id}/colls/{coll-id}/docs/{doc-id}
Delete Item	DELETE	/dbs/{db-id}/colls/{coll-id}/docs/{doc-id}

Code Samples

Below is a simple cURL example that creates a new item in a container.

curl -X POST "https://mycosmosaccount.documents.azure.com/dbs/MyDb/colls/MyColl/docs" \
  -H "x-ms-date: $(date -u '+%a, %d %b %Y %T GMT')" \
  -H "x-ms-version: 2023-06-01" \
  -H "Authorization: $(node -e "const fs=require('fs');const key='YOUR_MASTER_KEY';const verb='POST';const rt='docs';const rid='dbs/MyDb/colls/MyColl';const date=new Date().toUTCString();const text=\`\${verb.toLowerCase()}\\n\${rt}\\n\${rid}\\n\${date}\\n\\n\`;const signature=require('crypto').createHmac('sha256', Buffer.from(key,'base64')).update(text,'utf8').digest('base64');console.log(\`type=master&ver=1.0&sig=\${signature}\`);")}" \
  -H "Content-Type: application/json" \
  -d '{"id":"item1","name":"Sample Item","value":42}'

Error Codes

The REST API returns standard HTTP status codes. Common error responses include:

Status	Reason
401	Unauthorized – Invalid master key or signature.
404	Not Found – The requested resource does not exist.
409	Conflict – Resource already exists.
429	Too Many Requests – Request rate exceeded (throttling).
500	Internal Server Error – Unexpected server condition.

SDKs & Tools

While you can interact directly via the REST API, Microsoft provides official SDKs for many languages that abstract the authentication process and provide richer features.

FAQ

Do I need to include the x-ms-consistency-level header on every request?: Only if you want to override the account's default consistency level for a specific operation.
How do I handle pagination when querying items?: Use the x-ms-continuation response header. Include its value in the subsequent request's x-ms-continuation header.
Can I use Azure AD for authentication?: Yes. Azure AD and Azure Managed Identities are supported via the Azure Resource Tokens authentication scheme.