Cosmos DB REST API

Overview

The Azure Cosmos DB REST API provides direct HTTP access to all database operations. It enables you to manage databases, containers, items, users, permissions, and more using standard HTTP methods.

Authentication

All requests must be signed with a master key or resource token. The signature is generated using HMAC‑SHA256.

Signature format

authorization: type<master|resource> <ver>
key<padding>

Generating the token (JavaScript)

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

Endpoints

Base URL format:

https://{account}.documents.azure.com:443

All API calls are relative to the base URL.

Resources

Databases

Containers

Items

Query

Execute SQL queries using POST with the Content-Type: application/query+json header.

{
  "query": "SELECT c.id, c.name FROM c WHERE c.status = @status",
  "parameters": [
    {"name": "@status", "value": "active"}
  ]
}

Response includes Documents array and ContinuationToken for paging.

Samples

Node.js - Create a document

const https = require('https');
const crypto = require('crypto');

const account = 'YOUR_ACCOUNT';
const masterKey = 'YOUR_MASTER_KEY';
const dbId = 'SampleDB';
const collId = 'SampleColl';
const doc = { id: 'item1', name: 'Sample Item', status: 'active' };

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

const resourceId = `dbs/${dbId}/colls/${collId}`;
const token = getAuthToken('post', 'docs', resourceId);
const options = {
  hostname: `${account}.documents.azure.com`,
  path: `/${resourceId}/docs`,
  method: 'POST',
  headers: {
    'Authorization': token,
    'x-ms-date': new Date().toUTCString(),
    'x-ms-version': '2023-05-15',
    'Content-Type': 'application/json',
    'x-ms-documentdb-partitionkey': '[]'
  }
};

const req = https.request(options, (res) => {
  let data = '';
  res.on('data', (chunk) => data += chunk);
  res.on('end', () => console.log(JSON.parse(data)));
});
req.write(JSON.stringify(doc));
req.end();

Error handling

Cosmos DB returns standard HTTP status codes. The response body contains an error object.

{
  "code": "BadRequest",
  "message": "Request rate is too large."
}

Common codes:

• 400 – Bad request
• 401 – Unauthorized
• 404 – Not found
• 429 – Too many requests (rate limit)
• 500 – Internal server error