# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Azure Cosmos DB REST Items API
  version: 1.0.0
extends: openapi/microsoft-azure-items-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/dbs/{databaseId}/colls/{containerId}/docs'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents in a Cosmos DB container
      effect: read
      questions:
      - What documents are stored in one of my Cosmos DB containers?
      - Can I page through items with a continuation token and a max item count?
      instructions:
      - text: List items in container {containerId} of database {databaseId}.
        slots:
          containerId: path.containerId
          databaseId: path.databaseId
      - text: Show up to {x-ms-max-item-count} documents from {containerId} in {databaseId}.
        slots:
          x-ms-max-item-count: header.x-ms-max-item-count
          containerId: path.containerId
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dbs/{databaseId}/colls/{containerId}/docs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or upsert a document in a container
      effect: write
      questions:
      - How do I insert a new JSON document into a Cosmos DB container?
      - Can I upsert an item so it's replaced if the id already exists?
      instructions:
      - text: Create item {id} in container {containerId} of database {databaseId}.
        slots:
          id: requestBody.id
          containerId: path.containerId
          databaseId: path.databaseId
      - text: Upsert document {id} into {containerId} ({databaseId}) with partition key {x-ms-documentdb-partitionkey}.
        slots:
          id: requestBody.id
          containerId: path.containerId
          databaseId: path.databaseId
          x-ms-documentdb-partitionkey: header.x-ms-documentdb-partitionkey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dbs/{databaseId}/colls/{containerId}/docs/{itemId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a document by id and partition key
      effect: read
      questions:
      - How do I read a single Cosmos DB document if I know its id and partition key?
      - Can I fetch one item without running a query?
      instructions:
      - text: Get item {itemId} from container {containerId} in database {databaseId}.
        slots:
          itemId: path.itemId
          containerId: path.containerId
          databaseId: path.databaseId
      - text: Read document {itemId} with partition key {x-ms-documentdb-partitionkey} from {containerId}.
        slots:
          itemId: path.itemId
          x-ms-documentdb-partitionkey: header.x-ms-documentdb-partitionkey
          containerId: path.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dbs/{databaseId}/colls/{containerId}/docs/{itemId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an existing document entirely
      effect: write
      questions:
      - Can I overwrite a whole existing document with a new version?
      - What replaces an item that already exists in a container?
      instructions:
      - text: Replace item {itemId} in container {containerId} of database {databaseId}.
        slots:
          itemId: path.itemId
          containerId: path.containerId
          databaseId: path.databaseId
      - text: Overwrite existing document {itemId} (partition {x-ms-documentdb-partitionkey}) in {containerId}.
        slots:
          itemId: path.itemId
          x-ms-documentdb-partitionkey: header.x-ms-documentdb-partitionkey
          containerId: path.containerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/dbs/{databaseId}/colls/{containerId}/docs/{itemId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a document from a container
      effect: destructive
      questions:
      - How do I remove one document from a Cosmos DB container?
      - Do I need the partition key to delete an item?
      instructions:
      - text: Delete item {itemId} from container {containerId} in database {databaseId}.
        slots:
          itemId: path.itemId
          containerId: path.containerId
          databaseId: path.databaseId
      - text: Remove document {itemId} in partition {x-ms-documentdb-partitionkey} of {containerId}.
        slots:
          itemId: path.itemId
          x-ms-documentdb-partitionkey: header.x-ms-documentdb-partitionkey
          containerId: path.containerId
      method: generated
      generated: '2026-09-26'