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/ 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