OpenAI

OpenAI Threads API

The Threads API from OpenAI — 13 operation(s) for threads.

GitHub OpenAPI

Operations 19

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

GET /threads/{thread_id}/messages/{message_id}/files List files attached to a thread message · OpenAI Returns a list of message files #
Ask an LLM
“Which files are attached to a particular message in an Assistants thread?”
“Can I page through the attachments on one thread message oldest first?”
Tell an agent
List the files attached to message {message_id} in thread {thread_id}.
Show message {message_id}'s attachments in thread {thread_id}, ordered {order}.
GET /threads/{thread_id}/messages/{message_id}/files/{file_id} Get one file attached to a thread message · OpenAI Retrieves a message file #
Ask an LLM
“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?”
Tell an agent
Show file {file_id} on message {message_id} in thread {thread_id}.
Fetch attachment {file_id} from message {message_id} of thread {thread_id}.
POST /threads Start a new conversation thread · OpenAI Create a thread #
Ask an LLM
“How do I start a new conversation thread for an assistant?”
“Can I open an empty thread now and add messages to it later?”
Tell an agent
Create a new empty thread.
Start a fresh Assistants conversation thread without running it.
GET /threads/{thread_id} Retrieve a conversation thread · OpenAI Retrieves a thread #
Ask an LLM
“What metadata is stored on one of my assistant threads?”
“Can I fetch a thread by its ID to check it still exists?”
Tell an agent
Show thread {thread_id}.
Look up the details of conversation thread {thread_id}.
POST /threads/{thread_id} Update a conversation thread · OpenAI Modifies a thread #
Ask an LLM
“Is it possible to change the metadata on a thread after it was created?”
“How do I update the settings of an existing thread?”
Tell an agent
Update thread {thread_id}.
Modify the metadata on existing thread {thread_id}.
DELETE /threads/{thread_id} Delete a conversation thread · OpenAI Delete a thread #
Ask an LLM
“How do I permanently remove a conversation thread?”
“Can I delete a thread I no longer need?”
Tell an agent destructive · confirm first
Delete thread {thread_id}.
Permanently remove conversation thread {thread_id}.
GET /threads/{thread_id}/messages List the messages in a thread · OpenAI Returns a list of messages for a given thread #
Ask an LLM
“What messages have been exchanged in a thread so far?”
“Can I read a thread's conversation newest message first?”
Tell an agent
List the messages in thread {thread_id}.
Show the last {limit} messages in thread {thread_id}.
POST /threads/{thread_id}/messages Add a message to a thread · OpenAI Create a message #
Ask an LLM
“How do I post a user message into an existing thread?”
“Can I add a message to a thread without starting a run?”
Tell an agent
Add a new message to thread {thread_id}.
Post my message into conversation thread {thread_id}.
GET /threads/{thread_id}/messages/{message_id} Retrieve one message from a thread · OpenAI Retrieve a message #
Ask an LLM
“What exactly did a specific message in my thread say?”
“Can I fetch a single thread message by its ID?”
Tell an agent
Show message {message_id} in thread {thread_id}.
Get the content of message {message_id} from thread {thread_id}.
POST /threads/{thread_id}/messages/{message_id} Update a message in a thread · OpenAI Modifies a message #
Ask an LLM
“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?”
Tell an agent
Update message {message_id} in thread {thread_id}.
Modify the metadata on thread {thread_id}'s message {message_id}.
POST /threads/runs Create a thread and run it in one call · OpenAI Create a thread and run it in one request #
Ask an LLM
“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?”
Tell an agent
Create a new thread and run the assistant on it in one step.
Start a conversation and immediately launch a run on the new thread.
GET /threads/{thread_id}/runs List the runs on a thread · OpenAI Returns a list of runs belonging to a thread #
Ask an LLM
“Which runs have been executed on a particular thread?”
“Can I see a thread's run history oldest first?”
Tell an agent
List the runs on thread {thread_id}.
Show the {limit} most recent runs for thread {thread_id}.
POST /threads/{thread_id}/runs Run an assistant on an existing thread · OpenAI Create a run #
Ask an LLM
“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?”
Tell an agent
Start a run on existing thread {thread_id}.
Have the assistant process thread {thread_id} now.
GET /threads/{thread_id}/runs/{run_id} Check the status of a run · OpenAI Retrieves a run #
Ask an LLM
“Has my assistant run finished or is it still in progress?”
“Can I see whether a run is waiting on tool outputs?”
Tell an agent
Show run {run_id} on thread {thread_id}.
Check the status of run {run_id} in thread {thread_id}.
POST /threads/{thread_id}/runs/{run_id} Update a run's metadata · OpenAI Modifies a run #
Ask an LLM
“Is it possible to attach metadata to a run after it started?”
“Can I edit an existing run on a thread?”
Tell an agent
Update run {run_id} on thread {thread_id}.
Modify the metadata of thread {thread_id}'s run {run_id}.
POST /threads/{thread_id}/runs/{run_id}/submit_tool_outputs Submit tool call results to a waiting run · OpenAI When a run has the `status: "requires_action"` and… #
Ask an LLM
“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?”
Tell an agent
Submit the tool outputs for run {run_id} on thread {thread_id}.
Send my function call results back to run {run_id} in thread {thread_id} so it can continue.
POST /threads/{thread_id}/runs/{run_id}/cancel Cancel an in-progress run · OpenAI Cancels a run that is `in_progress` #
Ask an LLM
“How do I stop an assistant run that is still in progress?”
“Can I cancel a run that is taking too long?”
Tell an agent destructive · confirm first
Cancel run {run_id} on thread {thread_id}.
Stop the in-progress run {run_id} in thread {thread_id}.
GET /threads/{thread_id}/runs/{run_id}/steps List the steps an assistant took in a run · OpenAI Returns a list of run steps belonging to a run #
Ask an LLM
“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?”
Tell an agent
List the steps of run {run_id} on thread {thread_id}.
Show run {run_id}'s steps in thread {thread_id} ordered {order}.
GET /threads/{thread_id}/runs/{run_id}/steps/{step_id} Retrieve one step of a run · OpenAI Retrieves a run step #
Ask an LLM
“What happened in one particular step of an assistant run?”
“Can I inspect a single run step by its ID?”
Tell an agent
Show step {step_id} of run {run_id} on thread {thread_id}.
Get the details of run step {step_id} in run {run_id}, thread {thread_id}.

Documentation

📖
Documentation
https://platform.openai.com/docs/assistants/overview
📖
Documentation
https://platform.openai.com/docs/api-reference/assistants
📖
Documentation
https://platform.openai.com/docs/guides/text-to-speech
📖
Documentation
https://platform.openai.com/docs/api-reference/audio
📖
Documentation
https://platform.openai.com/docs/guides/speech-to-text
📖
Documentation
https://developers.openai.com/api/docs/guides/audio/
📖
Documentation
https://developers.openai.com/api/docs/guides/voice-agents/
📖
Documentation
https://platform.openai.com/docs/api-reference/chat
📖
Documentation
https://platform.openai.com/docs/guides/embeddings
📖
Documentation
https://platform.openai.com/docs/api-reference/embeddings
📖
Documentation
https://platform.openai.com/docs/api-reference/files
📖
Documentation
https://platform.openai.com/docs/guides/fine-tuning
📖
Documentation
https://platform.openai.com/docs/api-reference/fine-tuning
📖
Documentation
https://platform.openai.com/docs/guides/images
📖
Documentation
https://platform.openai.com/docs/api-reference/images
📖
Documentation
https://platform.openai.com/docs/guides/image-generation
📖
Documentation
https://platform.openai.com/docs/guides/images-vision
📖
Documentation
https://platform.openai.com/docs/models
📖
Documentation
https://platform.openai.com/docs/api-reference/models
📖
Documentation
https://platform.openai.com/docs/assistants/how-it-works/managing-threads-and-messages
📖
Documentation
https://platform.openai.com/docs/api-reference/threads
📖
Documentation
https://platform.openai.com/docs/api-reference/completions

Specifications

⚙
OpenAPI
https://artifacts.apis.io/openai/openapi/openai-threads-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://artifacts.apis.io/openai/json-schema/openai-chat-completion-schema.json
📊
JSONSchema
https://artifacts.apis.io/openai/json-schema/openai-embedding-schema.json

Other Resources

🔗
JSONLD
https://artifacts.apis.io/openai/json-ld/openai-context.jsonld

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/openai:openai-threads-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openai-threads-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Openai Threads API
  version: 2.0.0
  contact:
    name: OpenAI Support
    url: https://help.openai.com/
  license:
    name: MIT
    url: https://github.com/openai/openai-openapi/blob/master/LICENSE
  termsOfService: https://openai.com/policies/terms-of-use
  description: 'Operations tagged Threads across 2 of this provider''s published API definitions: files-openapi-original.yml, threads-openapi-original.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.openai.com/v1
security:
- ApiKeyAuth: []
tags:


# --- truncated at 32 KB (76 KB total) ---
# Full source: https://artifacts.apis.io/openai/openapi/openai-threads-api-openapi.yml