OpenAI Assistants API
Build Assistants that can call models and use tools.
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
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.
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}.
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.
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}.
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}.
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}.
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.
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}.
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}.
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}.
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}.
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 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}.
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}.
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}.
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}.
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}.
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.
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}.
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}.
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 · Retrieve 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 · Submit tool outputs to run
#
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
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