# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Openai Threads API
  version: 1.0.0
extends: openapi/openai-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: 19
- target: $.paths['/threads/{thread_id}/messages/{message_id}/files'].get
  update:
    x-apievangelist-phrasing:
      intent: List files attached to a thread message
      effect: read
      questions:
      - Which files are attached to a particular message in an Assistants thread?
      - Can I page through the attachments on one thread message oldest first?
      instructions:
      - text: List the files attached to message {message_id} in thread {thread_id}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Show message {message_id}'s attachments in thread {thread_id}, ordered {order}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
          order: query.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/messages/{message_id}/files/{file_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one file attached to a thread message
      effect: read
      questions:
      - How do I look up a single file attached to a thread message?
      - Can I confirm a specific file is linked to a given message?
      instructions:
      - text: Show file {file_id} on message {message_id} in thread {thread_id}.
        slots:
          file_id: path.file_id
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Fetch attachment {file_id} from 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'
- target: $.paths['/threads'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a new conversation thread
      effect: write
      questions:
      - How do I start a new conversation thread for an assistant?
      - Can I open an empty thread now and add messages to it later?
      instructions:
      - text: Create a new empty thread.
      - text: Start a fresh Assistants conversation thread without running it.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a conversation thread
      effect: read
      questions:
      - What metadata is stored on one of my assistant threads?
      - Can I fetch a thread by its ID to check it still exists?
      instructions:
      - text: Show thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Look up the details 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 conversation thread
      effect: write
      questions:
      - Is it possible to change the metadata on a thread after it was created?
      - How do I update the settings of an existing thread?
      instructions:
      - text: Update thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Modify the metadata on existing thread {thread_id}.
        slots:
          thread_id: path.thread_id
      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 permanently remove a conversation thread?
      - Can I delete a thread I no longer need?
      instructions:
      - text: Delete thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Permanently remove 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:
      - What messages have been exchanged in a thread so far?
      - Can I read a thread's conversation newest message first?
      instructions:
      - text: List the messages in thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Show the last {limit} messages in 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 message into an existing thread?
      - Can I add a message to a thread without starting a run?
      instructions:
      - text: Add a new message to thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Post my message into conversation thread {thread_id}.
        slots:
          thread_id: path.thread_id
      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:
      - What exactly did a specific message in my thread say?
      - Can I fetch a single thread message by its ID?
      instructions:
      - text: Show message {message_id} in thread {thread_id}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Get the content of message {message_id} from 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 in a thread
      effect: write
      questions:
      - Is it possible to change a message's metadata after posting it to a thread?
      - Can I tag an existing thread message with extra information?
      instructions:
      - text: Update message {message_id} in thread {thread_id}.
        slots:
          message_id: path.message_id
          thread_id: path.thread_id
      - text: Modify the metadata on thread {thread_id}'s message {message_id}.
        slots:
          thread_id: path.thread_id
          message_id: path.message_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 call
      effect: write
      questions:
      - Can I create a thread and kick off an assistant run in a single request?
      - What's the quickest way to start a new conversation and get the assistant working on it?
      instructions:
      - text: Create a new thread and run the assistant on it in one step.
      - text: Start a conversation and immediately launch a run on the new thread.
      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 runs have been executed on a particular thread?
      - Can I see a thread's run history oldest first?
      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 start a run on a thread I created earlier?
      instructions:
      - text: Start a run on existing thread {thread_id}.
        slots:
          thread_id: path.thread_id
      - text: Have the assistant process thread {thread_id} now.
        slots:
          thread_id: path.thread_id
      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?
      - Can I see whether a run is waiting on tool outputs?
      instructions:
      - text: Show run {run_id} on thread {thread_id}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Check the status of 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}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a run's metadata
      effect: write
      questions:
      - Is it possible to attach metadata to a run after it started?
      - Can I edit an existing run on a thread?
      instructions:
      - text: Update run {run_id} on thread {thread_id}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Modify the metadata of thread {thread_id}'s run {run_id}.
        slots:
          thread_id: path.thread_id
          run_id: path.run_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 call results to a waiting run
      effect: write
      questions:
      - My run says requires_action — how do I send back the results of the function calls?
      - What do I do once all the tool calls in a run have completed?
      instructions:
      - text: Submit the tool outputs for run {run_id} on thread {thread_id}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
      - text: Send my function call results back to run {run_id} in thread {thread_id} so it 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:
      - How do I stop an assistant run that is still in progress?
      - Can I cancel a run that is 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 an assistant took in a run
      effect: read
      questions:
      - What steps did the assistant take during a run, such as tool calls and messages?
      - Can I page through a run's steps in chronological order?
      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 run {run_id}'s steps in thread {thread_id} ordered {order}.
        slots:
          run_id: path.run_id
          thread_id: path.thread_id
          order: query.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/threads/{thread_id}/runs/{run_id}/steps/{step_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one step of a run
      effect: read
      questions:
      - What happened in one particular step of an assistant run?
      - Can I inspect a single run step by its ID?
      instructions:
      - text: Show step {step_id} of run {run_id} on 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} in run {run_id}, 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'