# 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).