# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for OpenAI Conversations API
  version: 1.0.0
extends: openapi/openai-conversations-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: 8
- target: $.paths['/conversations/{conversation_id}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List the items in a conversation
      effect: read
      questions:
      - How do I read back everything said in a stored conversation?
      - Can I list a conversation's items oldest first?
      instructions:
      - text: List the items in conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Show the last {limit} items of conversation {conversation_id}.
        slots:
          limit: query.limit
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations/{conversation_id}/items'].post
  update:
    x-apievangelist-phrasing:
      intent: Add items to a conversation
      effect: write
      questions:
      - Can I append new messages to an existing conversation?
      - Is it possible to add several items to a conversation in one call?
      instructions:
      - text: Add items {items} to conversation {conversation_id}.
        slots:
          items: requestBody.items
          conversation_id: path.conversation_id
      - text: 'Append these messages to existing conversation {conversation_id}: {items}.'
        slots:
          conversation_id: path.conversation_id
          items: requestBody.items
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations/{conversation_id}/items/{item_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one item from a conversation
      effect: read
      questions:
      - What does a single message in a conversation contain?
      - Can I fetch one conversation item by its item ID?
      instructions:
      - text: Get item {item_id} from conversation {conversation_id}.
        slots:
          item_id: path.item_id
          conversation_id: path.conversation_id
      - text: Show the content of conversation item {item_id} in {conversation_id}.
        slots:
          item_id: path.item_id
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations/{conversation_id}/items/{item_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an item from a conversation
      effect: destructive
      questions:
      - Can I remove one message from a conversation's history?
      - How do I delete a single item without deleting the whole conversation?
      instructions:
      - text: Delete item {item_id} from conversation {conversation_id}.
        slots:
          item_id: path.item_id
          conversation_id: path.conversation_id
      - text: Remove message {item_id} from the history of conversation {conversation_id}.
        slots:
          item_id: path.item_id
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a conversation
      effect: write
      questions:
      - How do I create a persistent conversation to keep state across responses?
      - Can I start a new conversation with some initial messages already in it?
      instructions:
      - text: Create a new conversation.
      - text: Start a conversation seeded with items {items} and metadata {metadata}.
        slots:
          items: requestBody.items
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations/{conversation_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a conversation
      effect: read
      questions:
      - What metadata is attached to one of my conversations?
      - Can I look up a conversation by its ID to confirm it still exists?
      instructions:
      - text: Get conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Show the details and metadata of conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations/{conversation_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a conversation's metadata
      effect: write
      questions:
      - Can I tag a conversation with my own customer or session IDs?
      - How do I change the metadata on an existing conversation?
      instructions:
      - text: Set metadata {metadata} on conversation {conversation_id}.
        slots:
          metadata: requestBody.metadata
          conversation_id: path.conversation_id
      - text: Replace the metadata of conversation {conversation_id} with {metadata}.
        slots:
          conversation_id: path.conversation_id
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/conversations/{conversation_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a conversation
      effect: destructive
      questions:
      - Does deleting a conversation also delete the items inside it?
      - What's the way to remove a whole conversation by ID?
      instructions:
      - text: Delete conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      - text: Remove the entire conversation {conversation_id}.
        slots:
          conversation_id: path.conversation_id
      method: generated
      generated: '2026-09-26'