Common Azure Cosmos DB REST request headers
The following request headers are common to all tasks that you might do with the SQL API:
| Header | Required | Type | Description |
|---|---|---|---|
| Authorization | Required | String | The authorization token for the request. For more information on generating a valid authorization token, see Access Control on Cosmos DB Resources |
| Content-Type | Required (on PUT, PATCH and POST) | String | For POST on query operations, it must be application/query+json. For PATCH operations, it must be application/json_patch+json. For attachments, must be set to the Mime type of the attachment. For more information on Mime types, see Create an Attachment For all other tasks, must be application/json. |
| If-Match | Optional (applicable only on PUT and DELETE) | String | Used to make operation conditional for optimistic concurrency. The value should be the etag value of the resource. |
| If-None-Match | Optional (applicable only on GET) | String | Makes operation conditional to only execute if the resource has changed. The value should be the etag of the resource. |
| If-Modified-Since | Optional (applicable only on GET) | Date | Returns etag of resource modified after specified date in RFC 1123 format. Ignored when If-None-Match is specified |
| User-Agent | Optional | String | A string that specifies the client user agent performing the request. The recommended format is {user agent name}/{version}. For example, the official SQL API .NET SDK sets the User-Agent string to Microsoft.Document.Client/1.0.0.0. A custom user-agent could be something like ContosoMarketingApp/1.0.0. |
| x-ms-activity-id | Optional | String | A client supplied identifier for the operation, which is echoed in the server response. The recommended value is a unique identifier. |
| x-ms-consistency-level | Optional | String | The consistency level override for read options against documents and attachments. The valid values are: Strong, Bounded, Session, or Eventual (in order of strongest to weakest). The override must be the same or weaker than the account’s configured consistency level. |
| x-ms-continuation | Optional | String | A string token returned for queries and read-feed operations if there are more results to be read. Clients can retrieve the next page of results by resubmitting the request with the x-ms-continuation request header set to this value. |
| x-ms-date | Required | Date | The date of the request per RFC 1123 date format expressed in Coordinated Universal Time, for example, Fri, 08 Apr 2015 03:52:31 GMT. |
| x-ms-max-item-count | Optional | Number | An integer indicating the maximum number of items to be returned per page. An x-ms-max-item-count of -1 can be specified to let the service determine the optimal item count. This is the recommended configuration value for x-ms-max-item-count |
| x-ms-documentdb-partitionkey | Optional | Array | The partition key value for the requested document or attachment operation. Required for operations against documents and attachments when the collection definition includes a partition key definition. This value is used to scope your query to documents that match the partition key criteria. By design it's a single partition query. Supported in API versions 2015-12-16 and newer. Currently, the SQL API supports a single partition key, so this is an array containing just one value. |
| x-ms-documentdb-query-enablecrosspartition | Optional | Boolean | When this header is set to true and if your query doesn't have a partition key, Azure Cosmos DB fans out the query across partitions. The fan out is done by issuing individual queries to all the partitions. To read the query results, the client applications should consume the results from the FeedResponse and check for the ContinuationToken property. To read all the results, keep iterating on the data until the ContinuationToken is null. |
| x-ms-session-token | Required (for session consistency only) | String | A string token used with session level consistency. For more information, see Using consistency levels in Cosmos DB |
| x-ms-version | Required | String | The version of the Cosmos DB REST service. For a list of supported API versions, see Azure Cosmos DB REST API Reference |
| A-IM | Optional | String | Indicates a change feed request. Must be set to "Incremental feed", or omitted otherwise. |
| x-ms-documentdb-partitionkeyrangeid | Optional | Number | Used in change feed requests. The partition key range ID for reading data. |
| x-ms-cosmos-allow-tentative-writes | Optional | Boolean | When this header is set to true for the Azure Cosmos accounts configured with multiple write locations, Azure Cosmos DB will allow writes to all locations. Write requests with the value of this header set to false (or if the header is absent) will fail with 403 Response Status code with error message "Writes are not allowed in the region". |
See also