# 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 Threads API
  version: 1.0.0
extends: openapi/microsoft-azure-threads-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: 26
- target: $.paths['/chat/threads/{chatThreadId}/readReceipts'].get
  update:
    x-apievangelist-phrasing:
      intent: List read receipts in a chat thread
      effect: read
      questions:
      - Who has read the latest messages in my Azure Communication Services chat thread?
      - Can I page through read receipts for a chat thread a few at a time?
      instructions:
      - text: Show the read receipts for chat thread {chatThreadId}.
        slots:
          chatThreadId: path.chatThreadId
      - text: List up to {maxPageSize} read receipts in chat thread {chatThreadId}.
        slots:
          maxPageSize: query.maxPageSize
          chatThreadId: path.chatThreadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/chat/threads/{chatThreadId}/readReceipts'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a chat message as read
      effect: write
      questions:
      - How do I tell a chat thread that a user has read a particular message?
      - Can I send a read receipt on behalf of a chat participant?
      instructions:
      - text: Send a read receipt for message {chatMessageId} in chat thread {chatThreadId}.
        slots:
          chatMessageId: requestBody.chatMessageId
          chatThreadId: path.chatThreadId
      - text: Mark chat message {chatMessageId} as read in thread {chatThreadId}.
        slots:
          chatMessageId: requestBody.chatMessageId
          chatThreadId: path.chatThreadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/chat/threads'].get
  update:
    x-apievangelist-phrasing:
      intent: List a user's chat threads
      effect: read
      questions:
      - Which chat threads is the current user part of?
      - Can I only see chat threads that have been active since a certain time?
      instructions:
      - text: List the chat threads for the current chat user.
      - text: List my chat threads updated since {startTime}.
        slots:
          startTime: query.startTime
      method: generated
      generated: '2026-09-26'
- target: $.paths['/chat/threads'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new chat thread
      effect: write
      questions:
      - How do I start a new group chat thread with a topic and participants?
      - Can I set a retention policy when I create a chat thread?
      instructions:
      - text: Create a chat thread with the topic {topic}.
        slots:
          topic: requestBody.topic
      - text: Start a chat thread called {topic} and add participants {participants}.
        slots:
          topic: requestBody.topic
          participants: requestBody.participants
      method: generated
      generated: '2026-09-26'
- target: $.paths['/chat/threads/{chatThreadId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a chat thread's properties
      effect: read
      questions:
      - What is the topic and creation info of a specific chat thread?
      - Where can I see who created a chat thread and when?
      instructions:
      - text: Get the properties of chat thread {chatThreadId}.
        slots:
          chatThreadId: path.chatThreadId
      - text: Show me the topic and metadata for chat thread {chatThreadId}.
        slots:
          chatThreadId: path.chatThreadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/chat/threads/{chatThreadId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a chat thread
      effect: destructive
      questions:
      - Can I permanently remove a Communication Services chat thread?
      - What happens when I delete a chat thread I no longer need?
      instructions:
      - text: Delete chat thread {chatThreadId}.
        slots:
          chatThreadId: path.chatThreadId
      - text: Remove the chat conversation {chatThreadId} entirely.
        slots:
          chatThreadId: path.chatThreadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/chat/threads/{chatThreadId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or update a chat thread
      effect: write
      questions:
      - How do I change the topic of an existing chat thread?
      - Can I change the retention policy on a chat thread after it's created?
      instructions:
      - text: Change the topic of chat thread {chatThreadId} to {topic}.
        slots:
          chatThreadId: path.chatThreadId
          topic: requestBody.topic
      - text: Update the metadata on chat thread {chatThreadId} to {metadata}.
        slots:
          chatThreadId: path.chatThreadId
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an assistant thread
      effect: write
      questions:
      - How do I create a conversation thread that an assistant can run on?
      - Can I seed a new assistant thread with starting messages?
      instructions:
      - text: Create a new empty assistant thread.
      - text: Create an assistant thread starting with the messages {messages}.
        slots:
          messages: requestBody.messages
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an assistant thread
      effect: read
      questions:
      - What details are stored on an existing assistant thread?
      - Can I look up an assistant thread by its ID to check its metadata?
      instructions:
      - text: Get assistant thread {threadId}.
        slots:
          threadId: path.threadId
      - text: Show the metadata on assistant thread {threadId}.
        slots:
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an assistant thread's metadata
      effect: write
      questions:
      - Can I tag an existing assistant thread with my own metadata?
      - Is it possible to change key-value metadata on an assistant thread?
      instructions:
      - text: Set the metadata on assistant thread {threadId} to {metadata}.
        slots:
          threadId: path.threadId
          metadata: requestBody.metadata
      - text: Modify assistant thread {threadId} with new metadata.
        slots:
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an assistant thread
      effect: destructive
      questions:
      - How do I delete an assistant conversation thread I'm done with?
      - Can I remove an old assistant thread and its history?
      instructions:
      - text: Delete assistant thread {threadId}.
        slots:
          threadId: path.threadId
      - text: Remove the assistant conversation {threadId}.
        slots:
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List messages on an assistant thread
      effect: read
      questions:
      - What messages have been posted to an assistant thread so far?
      - Can I list thread messages oldest-first and page with a cursor?
      instructions:
      - text: List the messages on assistant thread {threadId}.
        slots:
          threadId: path.threadId
      - text: Show the last {limit} messages on thread {threadId} in {order} order.
        slots:
          limit: query.limit
          threadId: path.threadId
          order: query.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a message to an assistant thread
      effect: write
      questions:
      - How do I add a user message to an assistant thread?
      - Can I attach uploaded files when posting a message to a thread?
      instructions:
      - text: Post the message {content} as {role} on assistant thread {threadId}.
        slots:
          content: requestBody.content
          role: requestBody.role
          threadId: path.threadId
      - text: Add a user message {content} to thread {threadId} with files {file_ids}.
        slots:
          content: requestBody.content
          threadId: path.threadId
          file_ids: requestBody.file_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/messages/{messageId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a message from an assistant thread
      effect: read
      questions:
      - Can I fetch one specific message from an assistant thread?
      - What role and content does a particular thread message have?
      instructions:
      - text: Get message {messageId} from assistant thread {threadId}.
        slots:
          messageId: path.messageId
          threadId: path.threadId
      - text: Show the content of thread message {messageId} in {threadId}.
        slots:
          messageId: path.messageId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/messages/{messageId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update metadata on a thread message
      effect: write
      questions:
      - Can I add my own metadata to a message already on an assistant thread?
      - Is there a way to change key-value tags on an existing thread message?
      instructions:
      - text: Set metadata {metadata} on message {messageId} in thread {threadId}.
        slots:
          metadata: requestBody.metadata
          messageId: path.messageId
          threadId: path.threadId
      - text: Modify message {messageId} on assistant thread {threadId}.
        slots:
          messageId: path.messageId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/messages/{messageId}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List files attached to a thread message
      effect: read
      questions:
      - Which files are attached to a message on an assistant thread?
      - Can I page through the file attachments of one thread message?
      instructions:
      - text: List the files attached to message {messageId} in thread {threadId}.
        slots:
          messageId: path.messageId
          threadId: path.threadId
      - text: Show up to {limit} file attachments on message {messageId} of thread {threadId}.
        slots:
          limit: query.limit
          messageId: path.messageId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/messages/{messageId}/files/{fileId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a file attached to a thread message
      effect: read
      questions:
      - Can I look up details of one file attached to a thread message?
      - What do I get back about a single message file attachment?
      instructions:
      - text: Get file {fileId} attached to message {messageId} in thread {threadId}.
        slots:
          fileId: path.fileId
          messageId: path.messageId
          threadId: path.threadId
      - text: Show the attachment {fileId} on thread {threadId} message {messageId}.
        slots:
          fileId: path.fileId
          threadId: path.threadId
          messageId: path.messageId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List runs on an assistant thread
      effect: read
      questions:
      - How many times has an assistant been run on this thread?
      - Can I list a thread's runs newest-first?
      instructions:
      - text: List the runs for assistant thread {threadId}.
        slots:
          threadId: path.threadId
      - text: Show the {limit} most recent runs on thread {threadId}.
        slots:
          limit: query.limit
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Run an assistant on an existing thread
      effect: write
      questions:
      - How do I have an assistant respond to the messages on a thread I already created?
      - Can I override the model or instructions for a single run?
      instructions:
      - text: Start a run of assistant {assistant_id} on thread {threadId}.
        slots:
          assistant_id: requestBody.assistant_id
          threadId: path.threadId
      - text: Run assistant {assistant_id} on thread {threadId} using model {model}.
        slots:
          assistant_id: requestBody.assistant_id
          threadId: path.threadId
          model: requestBody.model
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/runs/{runId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a thread run
      effect: read
      questions:
      - Has my assistant run finished or is it still in progress?
      - Is a run waiting on me to submit tool outputs?
      instructions:
      - text: Get run {runId} on thread {threadId}.
        slots:
          runId: path.runId
          threadId: path.threadId
      - text: Check the status of assistant run {runId} in thread {threadId}.
        slots:
          runId: path.runId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/runs/{runId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update metadata on a thread run
      effect: write
      questions:
      - Can I attach my own metadata to an assistant run after it starts?
      - Is it possible to relabel an existing run with key-value tags?
      instructions:
      - text: Set metadata {metadata} on run {runId} in thread {threadId}.
        slots:
          metadata: requestBody.metadata
          runId: path.runId
          threadId: path.threadId
      - text: Modify assistant run {runId} on thread {threadId}.
        slots:
          runId: path.runId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/runs/{runId}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an in-progress thread run
      effect: destructive
      questions:
      - How do I stop an assistant run that's taking too long?
      - Can I cancel a run while it's still in progress?
      instructions:
      - text: Cancel run {runId} on thread {threadId}.
        slots:
          runId: path.runId
          threadId: path.threadId
      - text: Stop the in-progress assistant run {runId} in thread {threadId}.
        slots:
          runId: path.runId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/runs/{runId}/steps'].get
  update:
    x-apievangelist-phrasing:
      intent: List the steps of a thread run
      effect: read
      questions:
      - What steps did the assistant take during a run, like tool calls or message creation?
      - Can I page through a run's steps in ascending order?
      instructions:
      - text: List the steps of run {runId} on thread {threadId}.
        slots:
          runId: path.runId
          threadId: path.threadId
      - text: Show the first {limit} steps of assistant run {runId} in thread {threadId}.
        slots:
          limit: query.limit
          runId: path.runId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/runs/{runId}/steps/{stepId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single step of a thread run
      effect: read
      questions:
      - Can I inspect one specific step from an assistant run?
      - What details are recorded for an individual run step?
      instructions:
      - text: Get step {stepId} of run {runId} on thread {threadId}.
        slots:
          stepId: path.stepId
          runId: path.runId
          threadId: path.threadId
      - text: Show run step {stepId} from assistant run {runId} in {threadId}.
        slots:
          stepId: path.stepId
          runId: path.runId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{threadId}/runs/{runId}/submit_tool_outputs'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit tool outputs to a waiting run
      effect: write
      questions:
      - My run's status is requires_action — how do I send back the function results?
      - Where do I submit tool call outputs so the assistant run can continue?
      instructions:
      - text: Submit tool outputs {tool_outputs} to run {runId} on thread {threadId}.
        slots:
          tool_outputs: requestBody.tool_outputs
          runId: path.runId
          threadId: path.threadId
      - text: Send the function call results {tool_outputs} back to waiting run {runId} in {threadId}.
        slots:
          tool_outputs: requestBody.tool_outputs
          runId: path.runId
          threadId: path.threadId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a thread and run an assistant at once
      effect: write
      questions:
      - Can I create a new thread and start the assistant on it in a single call?
      - What's the quickest way to kick off an assistant conversation from scratch?
      instructions:
      - text: Create a new thread and immediately run assistant {assistant_id} on it.
        slots:
          assistant_id: requestBody.assistant_id
      - text: Start a fresh thread {thread} and run assistant {assistant_id} on it in one step.
        slots:
          thread: requestBody.thread
          assistant_id: requestBody.assistant_id
      method: generated
      generated: '2026-09-26'