Conversations API

Use the Conversations API to create, inspect, retag, and delete stored conversations — and the items inside them. These are storage operations — no inference runs. Continue a conversation directly from /v1/responses with the conversation field, or without a stored resource at all via previous_response_id.

Endpoints

The conversation object

Every endpoint except delete returns a conversation object:

{
  "id": "conv_abc123",
  "object": "conversation",
  "created_at": 1751484000,
  "metadata": { "department": "cardiology", "acuity": "unconfirmed" }
}

Create a conversation

POST /v1/conversations

All fields are optional. An empty body creates an untagged conversation.

Seed it with prior history by passing items — up to 20 user messages, text only (see Items to add more later):

{
  "metadata": { "department": "cardiology" },
  "items": [
    { "role": "user", "content": "Patient reports chest pain since this morning." }
  ]
}

Orgs configured for zero data retention cannot create conversations (403 zero_data_retention). Send the full input on each /v1/responses request instead.

Retrieve a conversation

GET /v1/conversations/{conversation_id}

Returns the conversation object. An unknown id, or one that belongs to another organization, returns 404 conversation_not_found.

Update a conversation

POST /v1/conversations/{conversation_id}

metadata is required and replaces the stored tags. Resend every key you want to keep; send {} to clear them.

Delete a conversation

DELETE /v1/conversations/{conversation_id}

Deletes the conversation. Irreversible.

{
  "id": "conv_abc123",
  "object": "conversation.deleted",
  "deleted": true
}

Items

List, add, retrieve, or delete the individual messages, function calls, and web searches inside a conversation.

Add items the same way you seed a conversation — role: "user", text only:

{
  "items": [
    { "role": "user", "content": "Follow-up: any allergies on file?" }
  ]
}

Reasoning and function-call outputs aren't individually addressable — they stay attached to their parent message, unlike OpenAI's API. List paginates with limit (1–100, default 20), order, and an after cursor, same as Files. Delete returns the parent conversation object, not a deletion envelope.

Errors

{
  "error": {
    "message": "Conversation 'conv_abc123' not found.",
    "type": "invalid_request_error",
    "code": "conversation_not_found"
  }
}

See Authentication for auth and credit errors.

Related

• Responses API — continue a stored conversation directly with the conversation field, or chain turns with previous_response_id; every response includes a conversation field either way.
• Authentication — API keys and request headers.