API
Threads and memory
Keep a conversation on the server, continue it on any model, and read it back.
A thread is a conversation stored on the server, under your account. You send new messages; the server holds the history, rebuilds it for whichever model you name, and tells you the thread's id so you can continue it.
Choosing a thread
The API takes the thread id from the thread_id field in the body or, when that is empty, from the X-Thread-Id request header. The header is a convenience for clients that can set a header but not add a field to the body, or whose request types reject unknown fields; the official OpenAI SDKs can do either (extra_body in Python, extra keys in TypeScript), so use whichever suits your code. When both are present, the body wins.
| You send | What happens |
|---|---|
| No thread id | A new thread is started. Its id comes back in the X-Thread-Id response header. |
| The id of one of your threads | That thread is continued. |
| An id that does not exist yet | A thread is created with that id. A client can generate its own id, a UUID for example, and start sending straight away. |
| An id that belongs to someone else | 404 thread not found. The API does not reveal whether the id exists. |
The same 404 is returned when the thread store cannot be reached while loading or creating a thread, including on a request that sent no id. It is not always permanent: if nothing about the id has changed, retry once before treating the thread as gone.
Threads belong to your account, not to a key: any of your keys can continue them.
Send only the new turn
Many chat front ends, the Vercel AI SDK among them, post the whole transcript on every turn. When a thread id is set, forward only the last message.