# OpenAI Conversations API

**Status:** `DOCUMENTED` + `LIVE_VERIFIED` (full lifecycle 2026-09-18). Machine-readable: `generated/fragments/parameters/openai-conversations.json`, endpoint records in `generated/fragments/endpoints/openai-core.json`, objects in `generated/fragments/objects/openai-responses-objects.json`.

**Sources**
- https://developers.openai.com/api/reference/resources/conversations/methods/create (+ retrieve, update, delete; subresources/items/methods/create, list, retrieve, delete)
- https://developers.openai.com/api/docs/guides/conversation-state#using-the-conversations-api
- OpenAPI `CreateConversationBody`, `UpdateConversationBody`, `ConversationResource`, `ConversationItemList`, `DeletedConversationResource`

**Last verified:** 2026-09-18

## Concept
A conversation is a durable, id-addressable container (`conv_…`) of **items** (the same `Item` union as Responses `input`: messages, tool calls/outputs, reasoning, compaction, item references…). Bind a response to it with `conversation: "conv_…"` on `POST /v1/responses`: the server prepends the conversation's items to the request and appends the response's input **and** output items afterwards. Items in a conversation are **not** subject to the 30-day response TTL. `conversation` and `previous_response_id` are mutually exclusive.

## Endpoints

| Method | Path | Body / query | Returns | Live |
|---|---|---|---|---|
| POST | `/v1/conversations` | `{metadata?: map(≤16), items?: Item[] (≤20)}` | `{id, object:"conversation", created_at, metadata}` | 200 |
| GET | `/v1/conversations/{id}` | — | conversation | 200; after delete → 404 |
| POST | `/v1/conversations/{id}` | `{metadata}` (required) | conversation | 200 |
| DELETE | `/v1/conversations/{id}` | — | `{id, object:"conversation.deleted", deleted:true}` | 200 |
| POST | `/v1/conversations/{id}/items` | `{items: Item[] (≤20)}`, `?include[]` | `ConversationItemList` of created items (ids assigned, `status:"completed"`) | 200 |
| GET | `/v1/conversations/{id}/items` | `limit` 1–100 (20), `order` asc\|desc (**default desc**), `after`, `include[]` | `{object:"list", data[], first_id, last_id, has_more}` | 200 |
| GET | `/v1/conversations/{id}/items/{item_id}` | `?include[]` | item | 200 |
| DELETE | `/v1/conversations/{id}/items/{item_id}` | — | **the parent conversation object** (not a `*.deleted` object) | 200 |

`include[]` values are the Responses ones (`message.input_image.image_url`, `reasoning.encrypted_content`, `message.output_text.logprobs`, `code_interpreter_call.outputs`, `file_search_call.results`, `web_search_call.results`, `web_search_call.action.sources`, `computer_call_output.output.image_url`).

## Live walk-through (k1–k11)

```text
POST /v1/conversations {"metadata":{"atlas":"openai-core"}}          -> conv_6aade90d…
POST …/items {"items":[{type:message, role:user, content:[input_text "Reply with OK."]}]}
                                                                     -> list, 1 item msg_6aade90e… status completed
GET  …/items?limit=10&order=asc                                      -> 1 item, has_more false
GET  …/items/msg_…                                                   -> {"id","type":"message","status":"completed","content":[input_text],"role":"user"}
POST /v1/responses {"model":"gpt-5.4-nano","conversation":conv_…,"input":"Reply with OK once more.","max_output_tokens":32}
                                                                     -> status completed, "conversation":{"id":"conv_…"}, input_tokens 20 (both user msgs counted)
GET  …/items?order=asc                                               -> [message(user "Reply with OK."), message(user "Reply with OK once more."), message(assistant "OK")]
POST /v1/conversations/conv_… {"metadata":{…,"updated":"yes"}}       -> metadata echoed
DELETE …/items/msg_…                                                 -> {"id":"conv_…","object":"conversation","created_at":…,"metadata":{…}}
DELETE /v1/conversations/conv_…                                      -> {"object":"conversation.deleted","deleted":true}
GET  /v1/conversations/conv_…                                        -> 404 "Conversation with id '…' not found."
```

## Notes
- The response object shows `conversation: {"id": …}` and `previous_response_id: null`.
- Assistant items stored in the conversation have `output_text` content; user items `input_text`. The assistant message stored via conversation did **not** carry `phase` in the list output (the same message in the Response object does).
- SDKs: Python `client.conversations.{create,retrieve,update,delete}`, `client.conversations.items.{create,list,retrieve,delete}(item_id, conversation_id=…)`; Node `client.conversations.items.create(convId, {items})`, `.list(convId, {order})`, `.retrieve(itemId, {conversation_id})`.
- No list-conversations endpoint exists (keep your own index).