# 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 Assistants API
  version: 1.0.0
extends: openapi/microsoft-azure-assistants-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: 34
- target: $.paths['/assistants'].get
  update:
    x-apievangelist-phrasing:
      intent: List the assistants I have created
      effect: read
      questions:
      - Which assistants have I already set up in Azure OpenAI?
      - Can I page through my assistants newest first, a fixed number at a time?
      instructions:
      - text: Show me all the assistants I've created.
      - text: List my first {limit} assistants in {order} order.
        slots:
          limit: query.limit
          order: query.order
      - text: Continue listing my assistants after assistant {after}.
        slots:
          after: query.after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new assistant
      effect: write
      questions:
      - How do I set up a new assistant on a model deployment with its own system instructions?
      - Can a brand-new assistant be given tools and files from the moment it is created?
      instructions:
      - text: Create an assistant named {name} on model {model}.
        slots:
          name: requestBody.name
          model: requestBody.model
      - text: 'Set up a new {model} assistant that follows these instructions: {instructions}.'
        slots:
          model: requestBody.model
          instructions: requestBody.instructions
      - text: Create a {model} assistant with access to uploaded files {file_ids}.
        slots:
          model: requestBody.model
          file_ids: requestBody.file_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistantId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one assistant's configuration
      effect: read
      questions:
      - What model and instructions is a particular assistant configured with?
      - Can I pull up the settings of one assistant by its id?
      instructions:
      - text: Show me the configuration of assistant {assistantId}.
        slots:
          assistantId: path.assistantId
      - text: Fetch assistant {assistantId} so I can check which tools it has.
        slots:
          assistantId: path.assistantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistantId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Change an existing assistant's settings
      effect: write
      questions:
      - Can I switch an assistant I already built to a different model?
      - How do I rewrite the instructions of an assistant that's already live?
      instructions:
      - text: Move assistant {assistantId} to model {model}.
        slots:
          assistantId: path.assistantId
          model: requestBody.model
      - text: 'Replace the instructions on assistant {assistantId} with: {instructions}.'
        slots:
          assistantId: path.assistantId
          instructions: requestBody.instructions
      - text: Rename existing assistant {assistantId} to {name}.
        slots:
          assistantId: path.assistantId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistantId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an assistant
      effect: destructive
      questions:
      - Can I permanently remove an assistant I no longer use?
      - What happens when I delete an assistant by its id?
      instructions:
      - text: Delete assistant {assistantId}.
        slots:
          assistantId: path.assistantId
      - text: Get rid of the assistant with id {assistantId}.
        slots:
          assistantId: path.assistantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistantId}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List files attached to an assistant
      effect: read
      questions:
      - Which files can a given assistant's retrieval tools read right now?
      - Is there a way to page through the files linked to one assistant?
      instructions:
      - text: List the files attached to assistant {assistantId}.
        slots:
          assistantId: path.assistantId
      - text: Show the first {limit} files linked to assistant {assistantId}.
        slots:
          limit: query.limit
          assistantId: path.assistantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistantId}/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach an uploaded file to an assistant
      effect: write
      questions:
      - How do I give an assistant access to a file I already uploaded?
      - Can I link one more document to an assistant's file-reading tools?
      instructions:
      - text: Attach uploaded file {file_id} to assistant {assistantId}.
        slots:
          file_id: requestBody.file_id
          assistantId: path.assistantId
      - text: Let assistant {assistantId} read file {file_id} with its tools.
        slots:
          assistantId: path.assistantId
          file_id: requestBody.file_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistantId}/files/{fileId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up a file attached to an assistant
      effect: read
      questions:
      - Can I confirm a specific file is still attached to an assistant?
      - When was a particular file linked to my assistant?
      instructions:
      - text: Show attached file {fileId} on assistant {assistantId}.
        slots:
          fileId: path.fileId
          assistantId: path.assistantId
      - text: Check the attachment record for file {fileId} on assistant {assistantId}.
        slots:
          fileId: path.fileId
          assistantId: path.assistantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistantId}/files/{fileId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a file from an assistant
      effect: destructive
      questions:
      - How do I stop an assistant's tools from reading a file I attached?
      - Does unlinking a file from an assistant make it unavailable to that assistant?
      instructions:
      - text: Unlink file {fileId} from assistant {assistantId}.
        slots:
          fileId: path.fileId
          assistantId: path.assistantId
      - text: Detach file {fileId} so assistant {assistantId} can no longer read it.
        slots:
          fileId: path.fileId
          assistantId: path.assistantId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an assistant at a set API version
      effect: read
      questions:
      - Can I fetch an assistant while pinning a specific api-version?
      - Which version-pinned call returns one assistant's details?
      instructions:
      - text: Retrieve assistant {assistant_id} using api-version {api_version}.
        slots:
          assistant_id: path.assistant_id
          api_version: query.api-version
      - text: Pull assistant {assistant_id} from the versioned assistants endpoint.
        slots:
          assistant_id: path.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an assistant at a set API version
      effect: destructive
      questions:
      - Can I delete an assistant through the call that requires an api-version?
      - Is removing an assistant on a pinned API version permanent?
      instructions:
      - text: Delete assistant {assistant_id} with api-version {api_version}.
        slots:
          assistant_id: path.assistant_id
          api_version: query.api-version
      - text: Remove assistant {assistant_id} via the versioned delete endpoint.
        slots:
          assistant_id: path.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new conversation thread
      effect: write
      questions:
      - How do I open a new conversation thread for an assistant to work in?
      - Can I seed a new thread with starting messages when I create it?
      instructions:
      - text: Start a new empty conversation thread.
      - text: 'Create a thread pre-loaded with these messages: {messages}.'
        slots:
          messages: requestBody.messages
      - text: Open a new thread tagged with metadata {metadata}.
        slots:
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a conversation thread
      effect: read
      questions:
      - Can I look up a conversation thread and its metadata by id?
      - When was a given thread created?
      instructions:
      - text: Show me thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Fetch the details and metadata of conversation thread {thread_id}.
        slots:
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a thread's metadata
      effect: write
      questions:
      - Can I tag an existing conversation thread with my own metadata?
      - What on a thread can be changed after it's created?
      instructions:
      - text: Set the metadata on thread {thread_id} to {metadata}.
        slots:
          thread_id: path.thread_id
          metadata: requestBody.metadata
      - text: Label conversation thread {thread_id} with {metadata}.
        slots:
          thread_id: path.thread_id
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a conversation thread
      effect: destructive
      questions:
      - How do I delete a conversation thread when the chat is finished?
      - Can a deleted thread be recovered afterwards?
      instructions:
      - text: Delete thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Throw away the whole conversation thread {thread_id}.
        slots:
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages'].get
  update:
    x-apievangelist-phrasing:
      intent: List the messages in a thread
      effect: read
      questions:
      - How do I read back every message in a conversation thread?
      - Can I get a thread's messages oldest first instead of newest first?
      instructions:
      - text: List the messages in thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Show the last {limit} messages of thread {thread_id} in {order} order.
        slots:
          limit: query.limit
          thread_id: path.thread_id
          order: query.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a message to a thread
      effect: write
      questions:
      - How do I post a user message into an existing thread?
      - Can a message I add to a thread carry file attachments?
      instructions:
      - text: Add a {role} message saying {content} to thread {thread_id}.
        slots:
          role: requestBody.role
          content: requestBody.content
          thread_id: path.thread_id
      - text: Post {content} into thread {thread_id} with files {file_ids} attached.
        slots:
          content: requestBody.content
          thread_id: path.thread_id
          file_ids: requestBody.file_ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages/{message_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one message from a thread
      effect: read
      questions:
      - Can I fetch a single message out of a thread by its id?
      - Who wrote a particular message in a conversation thread?
      instructions:
      - text: Show message {message_id} from thread {thread_id}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Get the content of message {message_id} in thread {thread_id}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages/{message_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a message's metadata
      effect: write
      questions:
      - Can I attach my own metadata to a message already in a thread?
      - Is the text of a posted message editable, or only its metadata?
      instructions:
      - text: Set metadata {metadata} on message {message_id} in thread {thread_id}.
        slots:
          metadata: requestBody.metadata
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Tag message {message_id} of thread {thread_id} as reviewed.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a thread and run it in one step
      effect: write
      questions:
      - Can I start a new thread and have an assistant answer it in a single call?
      - What's the quickest way to get an assistant response without creating the thread first?
      instructions:
      - text: Create a new thread and run assistant {assistant_id} on it right away.
        slots:
          assistant_id: requestBody.assistant_id
      - text: Start thread {thread} and immediately run assistant {assistant_id} on it.
        slots:
          thread: requestBody.thread
          assistant_id: requestBody.assistant_id
      - text: Spin up a fresh thread with assistant {assistant_id} using model {model} for this run.
        slots:
          assistant_id: requestBody.assistant_id
          model: requestBody.model
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List the runs on a thread
      effect: read
      questions:
      - Which assistant runs have been executed on a thread?
      - Can I page through a thread's run history?
      instructions:
      - text: List the runs on thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Show the {limit} most recent runs of thread {thread_id}.
        slots:
          limit: query.limit
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/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 a thread I already have?
      - Can I override the assistant's instructions for just one run?
      instructions:
      - text: Run assistant {assistant_id} on thread {thread_id}.
        slots:
          assistant_id: requestBody.assistant_id
          thread_id: path.thread_id
      - text: 'Run assistant {assistant_id} on thread {thread_id} with these one-off instructions: {instructions}.'
        slots:
          assistant_id: requestBody.assistant_id
          thread_id: path.thread_id
          instructions: requestBody.instructions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/runs/{run_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the status of a 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: Check the status of run {run_id} on thread {thread_id}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Fetch run {run_id} in thread {thread_id} and tell me if it needs action.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/runs/{run_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a run's metadata
      effect: write
      questions:
      - Can I add my own tracking metadata to a run after it starts?
      - What part of an existing run am I allowed to modify?
      instructions:
      - text: Set metadata {metadata} on run {run_id} of thread {thread_id}.
        slots:
          metadata: requestBody.metadata
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Tag run {run_id} in thread {thread_id} with my ticket reference {metadata}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/runs/{run_id}/submit_tool_outputs'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit tool call results to a waiting run
      effect: write
      questions:
      - How do I hand my function call results back to a run that requires action?
      - What does a run need from me when its status is requires_action?
      instructions:
      - text: Submit tool outputs {tool_outputs} to run {run_id} on thread {thread_id}.
        slots:
          tool_outputs: requestBody.tool_outputs
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Send my function results back so run {run_id} in thread {thread_id} can continue.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/runs/{run_id}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an in-progress run
      effect: destructive
      questions:
      - Can I stop an assistant run that's still in progress?
      - What happens if I cancel a run midway through?
      instructions:
      - text: Cancel run {run_id} on thread {thread_id}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Stop the in-progress run {run_id} in thread {thread_id} now.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/runs/{run_id}/steps'].get
  update:
    x-apievangelist-phrasing:
      intent: List the steps a run took
      effect: read
      questions:
      - What steps did the assistant go through during a run?
      - Can I see which tool calls a run made, step by step?
      instructions:
      - text: List the steps of run {run_id} on thread {thread_id}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Show the first {limit} steps run {run_id} took in thread {thread_id}.
        slots:
          limit: query.limit
          run_id: path.run_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/runs/{run_id}/steps/{step_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a single run step
      effect: read
      questions:
      - Can I inspect one specific step of a run in detail?
      - Which tool call happened in a particular run step?
      instructions:
      - text: Show step {step_id} of run {run_id} in thread {thread_id}.
        slots:
          step_id: path.step_id
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Get the details of run step {step_id} from run {run_id} on thread {thread_id}.
        slots:
          step_id: path.step_id
          run_id: path.run_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List an assistant's files at a set API version
      effect: read
      questions:
      - Can I list an assistant's attached files while pinning an api-version?
      - Which versioned call pages through the assistant files of one assistant?
      instructions:
      - text: List assistant files for {assistant_id} on api-version {api_version}.
        slots:
          assistant_id: path.assistant_id
          api_version: query.api-version
      - text: Page through the assistant files of {assistant_id} after file {after} via the versioned endpoint.
        slots:
          assistant_id: path.assistant_id
          after: query.after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a file to an assistant at a set API version
      effect: write
      questions:
      - Can I create an assistant file through the call that takes an api-version?
      - Is there a version-pinned way to link an uploaded file to an assistant?
      instructions:
      - text: Create an assistant file linking {file_id} to {assistant_id} on api-version {api_version}.
        slots:
          file_id: requestBody.file_id
          assistant_id: path.assistant_id
          api_version: query.api-version
      - text: Use the versioned endpoint to attach file {file_id} to assistant {assistant_id}.
        slots:
          file_id: requestBody.file_id
          assistant_id: path.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}/files/{file_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an assistant file at a set API version
      effect: read
      questions:
      - Can I retrieve one assistant file record while pinning an api-version?
      - Which versioned call returns a single AssistantFile?
      instructions:
      - text: Retrieve AssistantFile {file_id} of {assistant_id} on api-version {api_version}.
        slots:
          file_id: path.file_id
          assistant_id: path.assistant_id
          api_version: query.api-version
      - text: Look up AssistantFile {file_id} for assistant {assistant_id} via the versioned endpoint.
        slots:
          file_id: path.file_id
          assistant_id: path.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}/files/{file_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an assistant file at a set API version
      effect: destructive
      questions:
      - Can I delete an AssistantFile through the versioned endpoint?
      - Is removing an assistant file on a pinned api-version reversible?
      instructions:
      - text: Delete AssistantFile {file_id} from {assistant_id} on api-version {api_version}.
        slots:
          file_id: path.file_id
          assistant_id: path.assistant_id
          api_version: query.api-version
      - text: Remove the assistant file record {file_id} of {assistant_id} through the versioned delete.
        slots:
          file_id: path.file_id
          assistant_id: path.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages/{message_id}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List the files attached to a message
      effect: read
      questions:
      - Which files were attached to a particular message in a thread?
      - Can I page through a message's file attachments?
      instructions:
      - text: List the files on message {message_id} in thread {thread_id}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Show up to {limit} attachments of message {message_id} in thread {thread_id}.
        slots:
          limit: query.limit
          message_id: path.message_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages/{message_id}/files/{file_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one file attached to a message
      effect: read
      questions:
      - Can I look up a single file attachment on a thread message?
      - Is a particular file still attached to that message?
      instructions:
      - text: Show file {file_id} attached to message {message_id} in thread {thread_id}.
        slots:
          file_id: path.file_id
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Get the message file record {file_id} on message {message_id} of thread {thread_id}.
        slots:
          file_id: path.file_id
          message_id: path.message_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'