API Evangelist conversational phrasing for Openai Assistants API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Openai Assistants API
  version: 1.0.0
extends: openapi/openai-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: 27
- target: $.paths['/assistants'].get
  update:
    x-apievangelist-phrasing:
      intent: List my assistants
      effect: read
      questions:
      - Which assistants have I already built in my OpenAI account?
      - Can I page through my assistants oldest first instead of newest first?
      instructions:
      - text: List all of my assistants.
      - text: Show me the {limit} most recently created assistants.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an assistant
      effect: write
      questions:
      - How do I set up a new assistant with its own model and instructions?
      - Can I give a brand-new assistant tools like code interpreter when I create it?
      instructions:
      - text: Create a new assistant named {name} using model {model}.
        slots:
          name: requestBody.name
          model: requestBody.model
      - text: 'Build an assistant on {model} with these system instructions: {instructions}.'
        slots:
          model: requestBody.model
          instructions: requestBody.instructions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve an assistant
      effect: read
      questions:
      - What model and instructions is a particular assistant configured with?
      - Where can I see the full settings of one assistant by its ID?
      instructions:
      - text: Show me the configuration of assistant {assistant_id}.
        slots:
          assistant_id: path.assistant_id
      - text: Fetch assistant {assistant_id} so I can check its tools.
        slots:
          assistant_id: path.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update an existing assistant
      effect: write
      questions:
      - Can I switch an existing assistant to a different model without recreating it?
      - How do I change the instructions on an assistant I already built?
      instructions:
      - text: Change assistant {assistant_id} to use model {model}.
        slots:
          assistant_id: path.assistant_id
          model: requestBody.model
      - text: 'Rewrite the instructions of assistant {assistant_id} to: {instructions}.'
        slots:
          assistant_id: path.assistant_id
          instructions: requestBody.instructions
      - text: Rename existing assistant {assistant_id} to {name}.
        slots:
          assistant_id: path.assistant_id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}'].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 {assistant_id}.
        slots:
          assistant_id: path.assistant_id
      - text: Remove the assistant {assistant_id} from my account for good.
        slots:
          assistant_id: path.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List files attached to an assistant
      effect: read
      questions:
      - Which files are attached to one of my assistants?
      - Can I see every file an assistant has access to, page by page?
      instructions:
      - text: List the files attached to assistant {assistant_id}.
        slots:
          assistant_id: path.assistant_id
      - text: Show the first {limit} files on assistant {assistant_id}.
        slots:
          limit: query.limit
          assistant_id: path.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}/files'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a file to an assistant
      effect: write
      questions:
      - How do I give an assistant access to a file I already uploaded?
      - Can I attach an uploaded file to an existing assistant after creating it?
      instructions:
      - text: Attach file {file_id} to assistant {assistant_id}.
        slots:
          file_id: requestBody.file_id
          assistant_id: path.assistant_id
      - text: Give assistant {assistant_id} access to uploaded file {file_id}.
        slots:
          assistant_id: path.assistant_id
          file_id: requestBody.file_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/assistants/{assistant_id}/files/{file_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a file attached to an assistant
      effect: read
      questions:
      - Is a specific file still attached to my assistant?
      - What details does the assistant-file record hold for one attached file?
      instructions:
      - text: Get the assistant file {file_id} on assistant {assistant_id}.
        slots:
          file_id: path.file_id
          assistant_id: path.assistant_id
      - text: Check whether file {file_id} is attached to assistant {assistant_id}.
        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: Detach a file from an assistant
      effect: destructive
      questions:
      - Can I take a file away from an assistant without deleting the assistant?
      - How do I stop an assistant from using one of its attached files?
      instructions:
      - text: Detach file {file_id} from assistant {assistant_id}.
        slots:
          file_id: path.file_id
          assistant_id: path.assistant_id
      - text: Delete the assistant file {file_id} from assistant {assistant_id}.
        slots:
          file_id: path.file_id
          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 start a fresh thread for a user before running an assistant on it?
      - Can I seed a new thread with some starting messages?
      instructions:
      - text: Create a new empty thread.
      - text: 'Start a thread pre-loaded with these messages: {messages}.'
        slots:
          messages: requestBody.messages
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a thread and run an assistant on it
      effect: write
      questions:
      - Can I create a thread and kick off an assistant run in a single call?
      - What's the quickest way to get an assistant answering a new conversation in one request?
      instructions:
      - text: Create a thread and immediately run assistant {assistant_id} on it.
        slots:
          assistant_id: requestBody.assistant_id
      - text: Open a new thread with {thread} and run assistant {assistant_id} on it, streaming the output.
        slots:
          thread: requestBody.thread
          assistant_id: requestBody.assistant_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a thread
      effect: read
      questions:
      - What metadata and tool resources does one thread have?
      - Can I look up a thread by its ID to confirm it exists?
      instructions:
      - text: Get thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Show the tool resources configured on 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 or tool resources
      effect: write
      questions:
      - Can I add metadata to a thread after it's been created?
      - How do I change the tool resources on an existing thread?
      instructions:
      - text: Set metadata {metadata} on thread {thread_id}.
        slots:
          metadata: requestBody.metadata
          thread_id: path.thread_id
      - text: Update the tool resources of thread {thread_id} to {tool_resources}.
        slots:
          thread_id: path.thread_id
          tool_resources: requestBody.tool_resources
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a thread
      effect: destructive
      questions:
      - Can I delete a whole conversation thread once it's finished?
      - What's the way to permanently remove a thread by ID?
      instructions:
      - text: Delete thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Permanently remove the 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 messages in a thread
      effect: read
      questions:
      - How do I read back all the messages in a thread?
      - Can I only see the messages that a particular run produced?
      instructions:
      - text: List the messages in thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Show messages in thread {thread_id} created by run {run_id}.
        slots:
          thread_id: path.thread_id
          run_id: query.run_id
      - text: Give me the last {limit} messages of thread {thread_id}.
        slots:
          limit: query.limit
          thread_id: path.thread_id
      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's question into an existing thread?
      - Can I attach files to a message when I add it to a thread?
      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} as a user message on thread {thread_id} with attachments {attachments}.
        slots:
          content: requestBody.content
          thread_id: path.thread_id
          attachments: requestBody.attachments
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages/{message_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a message from a thread
      effect: read
      questions:
      - What exactly did one message in a thread say?
      - Can I fetch a single thread message by its ID?
      instructions:
      - text: Get message {message_id} from thread {thread_id}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Show me 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 tag a thread message with my own metadata after it's posted?
      - Is it possible to edit anything on a message other than 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} with metadata {metadata}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
          metadata: requestBody.metadata
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages/{message_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a message from a thread
      effect: destructive
      questions:
      - Can I remove a single message from a thread without deleting the thread?
      - How do I delete one message I posted by mistake?
      instructions:
      - text: Delete message {message_id} from thread {thread_id}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Remove the mistaken 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}/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List runs on a thread
      effect: read
      questions:
      - Which assistant runs have been executed on a thread?
      - Can I see the history of runs for one conversation?
      instructions:
      - text: List the runs on thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Show the {limit} most recent runs for 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 get an assistant to respond to the messages already in a thread?
      - Can I override the model or add extra instructions just for one run?
      instructions:
      - text: Run assistant {assistant_id} on thread {thread_id}.
        slots:
          assistant_id: requestBody.assistant_id
          thread_id: path.thread_id
      - text: Start a run of assistant {assistant_id} on existing thread {thread_id} with extra instructions {additional_instructions}.
        slots:
          assistant_id: requestBody.assistant_id
          thread_id: path.thread_id
          additional_instructions: requestBody.additional_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 yet, or is it still in progress?
      - Can I see why a run failed or whether it needs tool outputs?
      instructions:
      - text: Get the status of run {run_id} on thread {thread_id}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Check whether run {run_id} in thread {thread_id} has completed.
        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 attach my own tracking metadata to an assistant run?
      - Is there a way to label a run after it has started?
      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: Label run {run_id} in thread {thread_id} with metadata {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}/cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel an in-progress run
      effect: destructive
      questions:
      - How do I stop an assistant run that is still in progress?
      - Can I cancel a run that's taking too long?
      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}.
        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 of a run
      effect: read
      questions:
      - What steps did the assistant take during a run, like tool calls and messages?
      - Can I include file search result content when listing a run's steps?
      instructions:
      - text: List the steps of run {run_id} in thread {thread_id}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Show every tool call step from run {run_id} on thread {thread_id}.
        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/{step_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a single run step
      effect: read
      questions:
      - What happened in one specific step of an assistant run?
      - Can I look up a single run step by its step ID?
      instructions:
      - text: Get 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: Show the details of run step {step_id} for 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['/threads/{thread_id}/runs/{run_id}/submit_tool_outputs'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit tool outputs to a waiting run
      effect: write
      questions:
      - My run says requires_action — how do I send back the results of the function calls?
      - Can I stream the rest of the run after submitting tool outputs?
      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 call results {tool_outputs} back to run {run_id} in thread {thread_id} so it can continue.
        slots:
          tool_outputs: requestBody.tool_outputs
          run_id: path.run_id
          thread_id: path.thread_id
      method: generated
      generated: '2026-09-26'