The Legacy Stateful API
The Assistants API was OpenAI's first attempt at stateful AI infrastructure. While now superseded by the Responses API for new projects, many production systems still use it.
Core Concepts
- Assistant: An AI entity with custom instructions, a model choice, and enabled tools.
- Thread: A persistent conversation session. You add Messages to a Thread.
- Message: Text or files added to a Thread by a user or Assistant.
- Run: The execution of an Assistant on a Thread (asynchronous).
The Workflow
- Create an Assistant with instructions and tools.
- Create a Thread when a user starts a conversation.
- Add a User Message to the Thread.
- Create a Run to process the Thread.
- Poll or stream the Run status until complete.
- Retrieve the Assistant's response Messages.
Built-in Tools
| Tool | Purpose |
|---|
| File Search | RAG over uploaded files (up to 10,000 per Vector Store) |
| Code Interpreter | Python sandbox for data analysis and file processing |
| Function Calling | Custom tool execution via requires_action status |
🚨 DEPRECATION (August 26, 2026): The Assistants API is officially deprecated and will be fully shut down on August 26, 2026. After this date, all requests to /v1/assistants, /v1/threads, and related endpoints will fail. Migrate to the Responses API and Conversations API immediately. Azure OpenAI users must migrate to Microsoft Foundry Agents.