OpenAI

OpenAI Assistants API

Build Assistants that can call models and use tools.

GitHub OpenAPI

Operations 27

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 /assistants List my assistants · OpenAI Returns a list of assistants #
Ask an LLM
“Which assistants have I already built in my OpenAI account?”
“Can I page through my assistants oldest first instead of newest first?”
Tell an agent
List all of my assistants.
Show me the {limit} most recently created assistants.
POST /assistants Create an assistant · OpenAI Create an assistant with a model and instructions #
Ask an LLM
“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?”
Tell an agent
Create a new assistant named {name} using model {model}.
Build an assistant on {model} with these system instructions: {instructions}.
GET /assistants/{assistant_id} Retrieve an assistant · OpenAI Retrieves an assistant #
Ask an LLM
“What model and instructions is a particular assistant configured with?”
“Where can I see the full settings of one assistant by its ID?”
Tell an agent
Show me the configuration of assistant {assistant_id}.
Fetch assistant {assistant_id} so I can check its tools.
POST /assistants/{assistant_id} Update an existing assistant · OpenAI Modifies an assistant #
Ask an LLM
“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?”
Tell an agent
Change assistant {assistant_id} to use model {model}.
Rewrite the instructions of assistant {assistant_id} to: {instructions}.
DELETE /assistants/{assistant_id} Delete an assistant · OpenAI Delete an assistant #
Ask an LLM
“Can I permanently remove an assistant I no longer use?”
“What happens when I delete an assistant by its ID?”
Tell an agent destructive · confirm first
Delete assistant {assistant_id}.
Remove the assistant {assistant_id} from my account for good.
GET /assistants/{assistant_id}/files List files attached to an assistant · OpenAI Returns a list of assistant files #
Ask an LLM
“Which files are attached to one of my assistants?”
“Can I see every file an assistant has access to, page by page?”
Tell an agent
List the files attached to assistant {assistant_id}.
Show the first {limit} files on assistant {assistant_id}.
POST /assistants/{assistant_id}/files Attach a file to an assistant · OpenAI Create an assistant file by attaching a File to an assistant #
Ask an LLM
“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?”
Tell an agent
Attach file {file_id} to assistant {assistant_id}.
Give assistant {assistant_id} access to uploaded file {file_id}.
GET /assistants/{assistant_id}/files/{file_id} Retrieve a file attached to an assistant · OpenAI Retrieves an AssistantFile #
Ask an LLM
“Is a specific file still attached to my assistant?”
“What details does the assistant-file record hold for one attached file?”
Tell an agent
Get the assistant file {file_id} on assistant {assistant_id}.
Check whether file {file_id} is attached to assistant {assistant_id}.
DELETE /assistants/{assistant_id}/files/{file_id} Detach a file from an assistant · OpenAI Delete an assistant file #
Ask an LLM
“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?”
Tell an agent destructive · confirm first
Detach file {file_id} from assistant {assistant_id}.
Delete the assistant file {file_id} from assistant {assistant_id}.
POST /threads Start a new conversation thread · Create a thread #
Ask an LLM
“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?”
Tell an agent
Create a new empty thread.
Start a thread pre-loaded with these messages: {messages}.
POST /threads/runs Create a thread and run an assistant on it · 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 call?”
“What's the quickest way to get an assistant answering a new conversation in one request?”
Tell an agent
Create a thread and immediately run assistant {assistant_id} on it.
Open a new thread with {thread} and run assistant {assistant_id} on it, streaming the output.
GET /threads/{thread_id} Retrieve a thread · Retrieves a thread #
Ask an LLM
“What metadata and tool resources does one thread have?”
“Can I look up a thread by its ID to confirm it exists?”
Tell an agent
Get thread {thread_id}.
Show the tool resources configured on thread {thread_id}.
POST /threads/{thread_id} Update a thread's metadata or tool resources · Modifies a thread #
Ask an LLM
“Can I add metadata to a thread after it's been created?”
“How do I change the tool resources on an existing thread?”
Tell an agent
Set metadata {metadata} on thread {thread_id}.
Update the tool resources of thread {thread_id} to {tool_resources}.
DELETE /threads/{thread_id} Delete a thread · Delete a thread #
Ask an LLM
“Can I delete a whole conversation thread once it's finished?”
“What's the way to permanently remove a thread by ID?”
Tell an agent destructive · confirm first
Delete thread {thread_id}.
Permanently remove the conversation thread {thread_id}.
GET /threads/{thread_id}/messages List messages in a thread · Returns a list of messages for a given thread #
Ask an LLM
“How do I read back all the messages in a thread?”
“Can I only see the messages that a particular run produced?”
Tell an agent
List the messages in thread {thread_id}.
Show messages in thread {thread_id} created by run {run_id}.
POST /threads/{thread_id}/messages Add a message to a thread · Create a message #
Ask an LLM
“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?”
Tell an agent
Add a {role} message saying {content} to thread {thread_id}.
Post {content} as a user message on thread {thread_id} with attachments {attachments}.
GET /threads/{thread_id}/messages/{message_id} Retrieve a message from a thread · Retrieve a message #
Ask an LLM
“What exactly did one message in a thread say?”
“Can I fetch a single thread message by its ID?”
Tell an agent
Get message {message_id} from thread {thread_id}.
Show me the content of message {message_id} in thread {thread_id}.
POST /threads/{thread_id}/messages/{message_id} Update a message's metadata · Modifies a message #
Ask an LLM
“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?”
Tell an agent
Set metadata {metadata} on message {message_id} in thread {thread_id}.
Tag message {message_id} of thread {thread_id} with metadata {metadata}.
DELETE /threads/{thread_id}/messages/{message_id} Delete a message from a thread · Deletes a message #
Ask an LLM
“Can I remove a single message from a thread without deleting the thread?”
“How do I delete one message I posted by mistake?”
Tell an agent destructive · confirm first
Delete message {message_id} from thread {thread_id}.
Remove the mistaken message {message_id} in thread {thread_id}.
GET /threads/{thread_id}/runs List runs on a thread · Returns a list of runs belonging to a thread #
Ask an LLM
“Which assistant runs have been executed on a thread?”
“Can I see the history of runs for one conversation?”
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 · Create a run #
Ask an LLM
“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?”
Tell an agent
Run assistant {assistant_id} on thread {thread_id}.
Start a run of assistant {assistant_id} on existing thread {thread_id} with extra instructions {additional_instructions}.
GET /threads/{thread_id}/runs/{run_id} Check the status of a run · Retrieves a run #
Ask an LLM
“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?”
Tell an agent
Get the status of run {run_id} on thread {thread_id}.
Check whether run {run_id} in thread {thread_id} has completed.
POST /threads/{thread_id}/runs/{run_id} Update a run's metadata · Modifies a run #
Ask an LLM
“Can I attach my own tracking metadata to an assistant run?”
“Is there a way to label a run after it has started?”
Tell an agent
Set metadata {metadata} on run {run_id} of thread {thread_id}.
Label run {run_id} in thread {thread_id} with metadata {metadata}.
POST /threads/{thread_id}/runs/{run_id}/cancel Cancel an in-progress run · 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's 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 of a run · Returns a list of run steps belonging to a run #
Ask an LLM
“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?”
Tell an agent
List the steps of run {run_id} in thread {thread_id}.
Show every tool call step from run {run_id} on thread {thread_id}.
GET /threads/{thread_id}/runs/{run_id}/steps/{step_id} Retrieve a single run step · Retrieves a run step #
Ask an LLM
“What happened in one specific step of an assistant run?”
“Can I look up a single run step by its step ID?”
Tell an agent
Get step {step_id} of run {run_id} in thread {thread_id}.
Show the details of run step {step_id} for run {run_id} on thread {thread_id}.
POST /threads/{thread_id}/runs/{run_id}/submit_tool_outputs Submit tool outputs to a waiting run · When a run has the `status: "requires_action"` and `required_action.type` is… #
Ask an LLM
“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?”
Tell an agent
Submit tool outputs {tool_outputs} to run {run_id} on thread {thread_id}.
Send my function call results {tool_outputs} back to run {run_id} in thread {thread_id} so it can continue.

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://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-assistants-api-openapi.yml

Schemas & Data

📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/json-schema/openai-chat-completion-schema.json
📊
JSONSchema
https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/json-schema/openai-embedding-schema.json

Other Resources

🔗
JSONLD
https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/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-assistants-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

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-assistants-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Openai Assistants API
  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
  version: '1.0'
  description: 'Operations tagged Assistants across 3 of this provider''s published API definitions: assistants-openapi-original.yml, files-openapi-original.yml, openai-openapi-master.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 (265 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/openai/refs/heads/main/openapi/openai-assistants-api-openapi.yml