Azure Cosmos DB is a globally distributed, multi-model database service that provides turnkey global distribution, elastic scaling, and guaranteed low latency. The REST API provides programmatic access to Cosmos DB resources for creating, querying, and managing databases, collections, and documents, supporting multiple data models including document, key-value, graph, and column-family databases.
openapi: 3.1.0
info:
title: Microsoft Azure Azure Cosmos DB REST API
description: >-
Azure Cosmos DB is a globally distributed, multi-model database service that
provides turnkey global distribution, elastic scaling of throughput and
storage, single-digit millisecond latency at the 99th percentile, and
guaranteed high availability, all backed by industry-leading SLAs. The REST
API enables programmatic access to Cosmos DB resources for creating, querying,
and managing databases, containers, items, stored procedures, triggers, and
user-defined functions.
version: '2018-12-31'
contact:
name: Microsoft Azure Support
url: https://azure.microsoft.com/en-us/support/
email: [email protected]
license:
name: Microsoft API License
url: https://learn.microsoft.com/en-us/legal/
x-logo:
url: https://azure.microsoft.com/svghandler/azure-logo.png
servers:
- url: https://{accountName}.documents.azure.com
description: Azure Cosmos DB account endpoint
variables:
accountName:
default: mycosmosaccount
description: The name of the Azure Cosmos DB account.
security:
- masterKey: []
- resourceToken: []
tags:
- name: Containers
description: Operations for managing containers (collections)
- name: Databases
description: Operations for managing Cosmos DB databases
- name: Items
description: Operations for managing items (documents)
- name: Stored Procedures
description: Operations for managing stored procedures
paths:
/dbs:
get:
operationId: Databases_List
summary: Microsoft Azure List Databases
description: Returns a list of databases under the database account.
tags:
- Databases
parameters:
- $ref: '#/components/parameters/ApiVersionParameter'
- $ref: '#/components/parameters/MaxItemCountParameter'
- $ref: '#/components/parameters/ContinuationParameter'
responses:
'200':
description: Successfully returned the list of databases.
content:
application/json:
schema:
$ref: '#/components/schemas/DatabaseListResult'
examples:
DatabasesList200Example:
summary: Default Databases_List 200 response
x-microcks-default: true
value:
_rid: '500123'
Databases:
- id: abc123
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_colls: example_value
_users: example_value
_count: 10
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
DatabasesListdefaultExample:
summary: Default Databases_List default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: Databases_Create
summary: Microsoft Azure Create a Database
description: Creates a new database in the database account.
tags:
- Databases
parameters:
- $ref: '#/components/parameters/ApiVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
id:
type: string
description: The unique name that identifies the database.
required:
- id
examples:
DatabasesCreateRequestExample:
summary: Default Databases_Create request
x-microcks-default: true
value:
id: abc123
responses:
'201':
description: Successfully created the database.
content:
application/json:
schema:
$ref: '#/components/schemas/Database'
examples:
DatabasesCreate201Example:
summary: Default Databases_Create 201 response
x-microcks-default: true
value:
id: abc123
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_colls: example_value
_users: example_value
'409':
description: The database with the specified ID already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
DatabasesCreate409Example:
summary: Default Databases_Create 409 response
x-microcks-default: true
value:
code: example_value
message: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
DatabasesCreatedefaultExample:
summary: Default Databases_Create default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/dbs/{databaseId}:
get:
operationId: Databases_Get
summary: Microsoft Azure Get a Database
description: Retrieves a database resource by its ID.
tags:
- Databases
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
responses:
'200':
description: Successfully returned the database.
content:
application/json:
schema:
$ref: '#/components/schemas/Database'
examples:
DatabasesGet200Example:
summary: Default Databases_Get 200 response
x-microcks-default: true
value:
id: abc123
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_colls: example_value
_users: example_value
'404':
description: The database was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
DatabasesGet404Example:
summary: Default Databases_Get 404 response
x-microcks-default: true
value:
code: example_value
message: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
DatabasesGetdefaultExample:
summary: Default Databases_Get default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: Databases_Delete
summary: Microsoft Azure Delete a Database
description: Deletes a database and all child resources (containers, items, etc.).
tags:
- Databases
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
responses:
'204':
description: Successfully deleted the database.
'404':
description: The database was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
DatabasesDelete404Example:
summary: Default Databases_Delete 404 response
x-microcks-default: true
value:
code: example_value
message: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
DatabasesDeletedefaultExample:
summary: Default Databases_Delete default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/dbs/{databaseId}/colls:
get:
operationId: Containers_List
summary: Microsoft Azure List Containers
description: Returns a list of containers under the specified database.
tags:
- Containers
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
- $ref: '#/components/parameters/MaxItemCountParameter'
- $ref: '#/components/parameters/ContinuationParameter'
responses:
'200':
description: Successfully returned the list of containers.
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerListResult'
examples:
ContainersList200Example:
summary: Default Containers_List 200 response
x-microcks-default: true
value:
_rid: '500123'
DocumentCollections:
- id: abc123
defaultTtl: 10
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_docs: example_value
_sprocs: example_value
_triggers: example_value
_udfs: example_value
_count: 10
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ContainersListdefaultExample:
summary: Default Containers_List default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: Containers_Create
summary: Microsoft Azure Create a Container
description: Creates a new container under the specified database.
tags:
- Containers
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerCreateRequest'
examples:
ContainersCreateRequestExample:
summary: Default Containers_Create request
x-microcks-default: true
value:
id: abc123
indexingPolicy:
automatic: true
indexingMode: consistent
includedPaths:
- {}
excludedPaths:
- {}
compositeIndexes:
- {}
spatialIndexes:
- {}
partitionKey:
paths:
- {}
kind: Hash
version: 1
uniqueKeyPolicy:
uniqueKeys:
- {}
conflictResolutionPolicy:
mode: LastWriterWins
conflictResolutionPath: example_value
conflictResolutionProcedure: example_value
defaultTtl: 10
responses:
'201':
description: Successfully created the container.
content:
application/json:
schema:
$ref: '#/components/schemas/Container'
examples:
ContainersCreate201Example:
summary: Default Containers_Create 201 response
x-microcks-default: true
value:
id: abc123
indexingPolicy:
automatic: true
indexingMode: consistent
includedPaths:
- {}
excludedPaths:
- {}
compositeIndexes:
- {}
spatialIndexes:
- {}
partitionKey:
paths:
- {}
kind: Hash
version: 1
uniqueKeyPolicy:
uniqueKeys:
- {}
conflictResolutionPolicy:
mode: LastWriterWins
conflictResolutionPath: example_value
conflictResolutionProcedure: example_value
defaultTtl: 10
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_docs: example_value
_sprocs: example_value
_triggers: example_value
_udfs: example_value
'409':
description: The container with the specified ID already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ContainersCreate409Example:
summary: Default Containers_Create 409 response
x-microcks-default: true
value:
code: example_value
message: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ContainersCreatedefaultExample:
summary: Default Containers_Create default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/dbs/{databaseId}/colls/{containerId}:
get:
operationId: Containers_Get
summary: Microsoft Azure Get a Container
description: Retrieves a container resource by its ID.
tags:
- Containers
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ContainerIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
responses:
'200':
description: Successfully returned the container.
content:
application/json:
schema:
$ref: '#/components/schemas/Container'
examples:
ContainersGet200Example:
summary: Default Containers_Get 200 response
x-microcks-default: true
value:
id: abc123
indexingPolicy:
automatic: true
indexingMode: consistent
includedPaths:
- {}
excludedPaths:
- {}
compositeIndexes:
- {}
spatialIndexes:
- {}
partitionKey:
paths:
- {}
kind: Hash
version: 1
uniqueKeyPolicy:
uniqueKeys:
- {}
conflictResolutionPolicy:
mode: LastWriterWins
conflictResolutionPath: example_value
conflictResolutionProcedure: example_value
defaultTtl: 10
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_docs: example_value
_sprocs: example_value
_triggers: example_value
_udfs: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ContainersGetdefaultExample:
summary: Default Containers_Get default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: Containers_Replace
summary: Microsoft Azure Replace a Container
description: Replaces the entire container resource.
tags:
- Containers
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ContainerIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerCreateRequest'
examples:
ContainersReplaceRequestExample:
summary: Default Containers_Replace request
x-microcks-default: true
value:
id: abc123
indexingPolicy:
automatic: true
indexingMode: consistent
includedPaths:
- {}
excludedPaths:
- {}
compositeIndexes:
- {}
spatialIndexes:
- {}
partitionKey:
paths:
- {}
kind: Hash
version: 1
uniqueKeyPolicy:
uniqueKeys:
- {}
conflictResolutionPolicy:
mode: LastWriterWins
conflictResolutionPath: example_value
conflictResolutionProcedure: example_value
defaultTtl: 10
responses:
'200':
description: Successfully replaced the container.
content:
application/json:
schema:
$ref: '#/components/schemas/Container'
examples:
ContainersReplace200Example:
summary: Default Containers_Replace 200 response
x-microcks-default: true
value:
id: abc123
indexingPolicy:
automatic: true
indexingMode: consistent
includedPaths:
- {}
excludedPaths:
- {}
compositeIndexes:
- {}
spatialIndexes:
- {}
partitionKey:
paths:
- {}
kind: Hash
version: 1
uniqueKeyPolicy:
uniqueKeys:
- {}
conflictResolutionPolicy:
mode: LastWriterWins
conflictResolutionPath: example_value
conflictResolutionProcedure: example_value
defaultTtl: 10
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_docs: example_value
_sprocs: example_value
_triggers: example_value
_udfs: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ContainersReplacedefaultExample:
summary: Default Containers_Replace default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: Containers_Delete
summary: Microsoft Azure Delete a Container
description: Deletes a container and all contained items.
tags:
- Containers
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ContainerIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
responses:
'204':
description: Successfully deleted the container.
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ContainersDeletedefaultExample:
summary: Default Containers_Delete default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/dbs/{databaseId}/colls/{containerId}/docs:
get:
operationId: Items_List
summary: Microsoft Azure List Items
description: Returns a list of items (documents) under the specified container.
tags:
- Items
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ContainerIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
- $ref: '#/components/parameters/MaxItemCountParameter'
- $ref: '#/components/parameters/ContinuationParameter'
- $ref: '#/components/parameters/PartitionKeyParameter'
responses:
'200':
description: Successfully returned the list of items.
content:
application/json:
schema:
$ref: '#/components/schemas/ItemListResult'
examples:
ItemsList200Example:
summary: Default Items_List 200 response
x-microcks-default: true
value:
_rid: '500123'
Documents:
- id: abc123
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_attachments: example_value
_count: 10
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ItemsListdefaultExample:
summary: Default Items_List default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: Items_Create
summary: Microsoft Azure Create an Item
description: Creates a new item (document) in the specified container.
tags:
- Items
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ContainerIdParameter'
- $ref: '#/components/parameters/ApiVersionParameter'
- $ref: '#/components/parameters/PartitionKeyParameter'
- name: x-ms-documentdb-is-upsert
in: header
description: If true, the operation will perform an upsert instead of create.
schema:
type: boolean
default: false
example: true
requestBody:
required: true
content:
application/json:
schema:
type: object
description: The JSON document to create.
properties:
id:
type: string
description: The unique identifier of the item.
required:
- id
additionalProperties: true
examples:
ItemsCreateRequestExample:
summary: Default Items_Create request
x-microcks-default: true
value:
id: abc123
responses:
'201':
description: Successfully created the item.
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
examples:
ItemsCreate201Example:
summary: Default Items_Create 201 response
x-microcks-default: true
value:
id: abc123
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_attachments: example_value
'409':
description: An item with the specified ID already exists.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ItemsCreate409Example:
summary: Default Items_Create 409 response
x-microcks-default: true
value:
code: example_value
message: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ItemsCreatedefaultExample:
summary: Default Items_Create default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/dbs/{databaseId}/colls/{containerId}/docs/{itemId}:
get:
operationId: Items_Get
summary: Microsoft Azure Get an Item
description: Retrieves an item (document) by its ID and partition key.
tags:
- Items
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ContainerIdParameter'
- name: itemId
in: path
required: true
description: The ID of the item.
schema:
type: string
example: '500123'
- $ref: '#/components/parameters/ApiVersionParameter'
- $ref: '#/components/parameters/PartitionKeyParameter'
responses:
'200':
description: Successfully returned the item.
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
examples:
ItemsGet200Example:
summary: Default Items_Get 200 response
x-microcks-default: true
value:
id: abc123
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_attachments: example_value
'404':
description: The item was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ItemsGet404Example:
summary: Default Items_Get 404 response
x-microcks-default: true
value:
code: example_value
message: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ItemsGetdefaultExample:
summary: Default Items_Get default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
operationId: Items_Replace
summary: Microsoft Azure Replace an Item
description: Replaces the entire item (document).
tags:
- Items
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ContainerIdParameter'
- name: itemId
in: path
required: true
description: The ID of the item.
schema:
type: string
example: '500123'
- $ref: '#/components/parameters/ApiVersionParameter'
- $ref: '#/components/parameters/PartitionKeyParameter'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: The replacement JSON document.
additionalProperties: true
examples:
ItemsReplaceRequestExample:
summary: Default Items_Replace request
x-microcks-default: true
value: {}
responses:
'200':
description: Successfully replaced the item.
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
examples:
ItemsReplace200Example:
summary: Default Items_Replace 200 response
x-microcks-default: true
value:
id: abc123
_rid: '500123'
_ts: 10
_self: example_value
_etag: example_value
_attachments: example_value
default:
description: Error response.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
ItemsReplacedefaultExample:
summary: Default Items_Replace default response
x-microcks-default: true
value:
code: example_value
message: example_value
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: Items_Delete
summary: Microsoft Azure Delete an Item
description: Deletes an item (document) from the container.
tags:
- Items
parameters:
- $ref: '#/components/parameters/DatabaseIdParameter'
- $ref: '#/components/parameters/ContainerIdParameter'
- name: itemId
in: path
requir
# --- truncated at 32 KB (50 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/microsoft-azure/refs/heads/main/openapi/azure-cosmos-db-openapi.yml