Azure Cosmos DB Documents API

openapi: 3.1.0
info:
  title: Azure Cosmos DB Data Plane REST Collections Documents API
  version: '2018-12-31'
  description: 'Data-plane REST API for Azure Cosmos DB (SQL/Core API). Requests are sent to the

    per-account endpoint `https://{databaseaccount}.documents.azure.com` and authorized

    with a master key or resource token using HMAC-signed `Authorization` headers, or

    with a Microsoft Entra ID bearer token. The `x-ms-version` header selects the API

    version; the latest known version is used when omitted.

    '
  contact:
    name: Azure Cosmos DB REST API
    url: https://learn.microsoft.com/en-us/rest/api/cosmos-db/
servers:
- url: https://{databaseaccount}.documents.azure.com
  description: Cosmos DB account endpoint
  variables:
    databaseaccount:
      default: my-account
      description: Your Cosmos DB account name
tags:
- name: Documents
  description: Document items
paths:
  /dbs/{dbId}/colls/{collId}/docs:
    parameters:
    - in: path
      name: dbId
      required: true
      schema:
        type: string
    - in: path
      name: collId
      required: true
      schema:
        type: string
    get:
      summary: List documents in a collection
      operationId: listDocuments
      tags:
      - Documents
      responses:
        '200':
          description: Documents
          content:
            application/json:
              schema:
                type: object
                properties:
                  Documents:
                    type: array
                    items:
                      type: object
      security:
      - cosmosAuth: []
      - entra: []
    post:
      summary: Create or query a document
      description: 'POST is used to create a document. To execute a SQL query, set the

        `x-ms-documentdb-isquery` header to `true` and send a query body.

        '
      operationId: createOrQueryDocument
      tags:
      - Documents
      parameters:
      - in: header
        name: x-ms-documentdb-isquery
        schema:
          type: string
        description: Set to "true" when issuing a query
      - in: header
        name: x-ms-documentdb-query-enablecrosspartition
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
          application/query+json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                parameters:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                      value: {}
      responses:
        '200':
          description: Query results
        '201':
          description: Document created
      security:
      - cosmosAuth: []
      - entra: []
  /dbs/{dbId}/colls/{collId}/docs/{docId}:
    parameters:
    - in: path
      name: dbId
      required: true
      schema:
        type: string
    - in: path
      name: collId
      required: true
      schema:
        type: string
    - in: path
      name: docId
      required: true
      schema:
        type: string
    get:
      summary: Get a document
      operationId: getDocument
      tags:
      - Documents
      responses:
        '200':
          description: Document
          content:
            application/json:
              schema:
                type: object
      security:
      - cosmosAuth: []
      - entra: []
    put:
      summary: Replace a document
      operationId: replaceDocument
      tags:
      - Documents
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Replaced
          content:
            application/json:
              schema:
                type: object
      security:
      - cosmosAuth: []
      - entra: []
    delete:
      summary: Delete a document
      operationId: deleteDocument
      tags:
      - Documents
      responses:
        '204':
          description: Deleted
      security:
      - cosmosAuth: []
      - entra: []
components:
  securitySchemes:
    cosmosAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Cosmos DB master-key or resource-token HMAC signature. Format:

        `type=master&ver=1.0&sig=<base64-hmac-sha256>` (URL-encoded).

        See https://learn.microsoft.com/en-us/rest/api/cosmos-db/access-control-on-cosmosdb-resources

        '
    entra:
      type: oauth2
      description: Microsoft Entra ID OAuth 2.0 bearer token
      flows:
        clientCredentials:
          tokenUrl: https://login.microsoftonline.com/common/oauth2/v2.0/token
          scopes:
            https://cosmos.azure.com/.default: Cosmos DB data plane access