Conversations API¶

Keep multi-turn state on the server. A conversation holds the items of an exchange — user messages, model output, reasoning and tool calls — so each new turn only has to send the new message. Pass a conversation ID as conversation on a Responses request and both the request input and the response output are added to it automatically.

Why Choose the Conversations API?¶

Send Only the New Turn
The conversation's items become the input prefix of the next request, so a long exchange stays a one-message request.
Explicit Item Control
Add, list, retrieve and delete items yourself, independently of any model call.
Attached Metadata
Up to 16 key-value pairs per conversation, merged on update and removable key by key.
Cursor Pagination
List items newest- or oldest-first with limit and the after cursor.
No Gateway State
The thread lives in your AWS account, not in a gateway instance, so any instance behind a load balancer serves any conversation.

Available Endpoints¶

Endpoint	Method	What It Does	MCP Tool
`/v1/conversations`	`POST`	Create a conversation	`openai_conversation`
`/v1/conversations/{conversation_id}`	`GET`	Retrieve a conversation	`openai_conversation_get`
`/v1/conversations/{conversation_id}`	`POST`	Update the conversation's metadata	`openai_conversation_update`
`/v1/conversations/{conversation_id}`	`DELETE`	Delete a conversation and its items	`openai_conversation_delete`
`/v1/conversations/{conversation_id}/items`	`POST`	Add items to a conversation	`openai_conversation_items`
`/v1/conversations/{conversation_id}/items`	`GET`	List a conversation's items	`openai_conversation_items_list`
`/v1/conversations/{conversation_id}/items/{item_id}`	`GET`	Retrieve one item	`openai_conversation_item_get`
`/v1/conversations/{conversation_id}/items/{item_id}`	`DELETE`	Delete one item	`openai_conversation_item_delete`

Feature Compatibility¶

Feature	Status	Notes
Conversation
`items`		Up to 20 initial items, prepared before the conversation is created, so a rejected item leaves no empty conversation behind
`metadata`		The limits in Metadata. A key given a `null` value is accepted and dropped rather than stored; on an update that same `null` removes the key
A request with no body		Both fields are optional, and the body itself may be omitted
Retrieve, update, delete		`metadata` is the only field an update takes; a delete removes the conversation and every item it holds
Items
`items` on an add		1 to 20 per request; the response is a `list` envelope of the items added, not the whole conversation
Item shapes		The Responses `input` and `output` items: messages, reasoning items, tool calls and their outputs
A message `content` sent as a string		Expanded into an `input_text` or `output_text` part according to the message's `role`
An `id` sent on a new item		Accepted and ignored — the server mints the identifier, prefixed by the item's type
`item_reference` items		Resolved against the conversation and then dropped rather than stored again, since the item it names is already there; one naming an item that is not answers `404`
Retrieve and delete one item		A delete returns the conversation, and the item leaves both the listing and the prefix of the next Responses turn
Listing items
`order`, `limit`, `after`		Bounds and cursor semantics in Listing
`include`		Accepted on the listing, on a retrieval and on an add. Only `reasoning.encrypted_content` changes the response; every other value is accepted and ignored
`first_id` / `last_id` / `has_more`		Populated on every page; the server never auto-paginates
Lifecycle
Conversation lifetime		30 days from creation, after which every route on it answers `404`. Amazon Bedrock session storage sets the window and it cannot be extended
Adding and deleting items		1,000 requests per conversation — see Limits

Legend:

Supported — Fully compatible with OpenAI API
Partial — Supported with limitations

No model is involved

Every endpoint on this page is state management: items are stored and read back as they were sent. Nothing here embeds, summarises or re-runs an item, so no endpoint takes a model identifier and a conversation behaves the same whatever the deployment's catalog holds. Summarising a long exchange is POST /v1/responses/compact, on the Responses API.

Quick Start¶

from openai import OpenAI

client = OpenAI(base_url="https://your-gateway/v1", api_key="YOUR_API_KEY")

conversation = client.conversations.create(metadata={"topic": "travel"})

first = client.responses.create(
    model="amazon.nova-micro-v1:0",
    input="My favourite city is Lisbon.",
    conversation=conversation.id,
)

second = client.responses.create(
    model="amazon.nova-micro-v1:0",
    input="Which city did I name?",
    conversation=conversation.id,
)
print(second.output_text)

The second request carries no history: the conversation supplies it.

Using a Conversation with the Responses API¶

Request	Effect
`conversation="conv-..."`	The conversation's items are prepended to `input`; the request input and the response output are appended to the conversation.
`conversation={"id": "conv-..."}`	Same; both forms are accepted.
`conversation=...`, `store=false`	The conversation is still used as the input prefix, but nothing is added to it.
`conversation=...`, `stream=true`	Items are added once the stream has ended, and the terminal event carries the conversation.
`conversation=...` and `previous_response_id=...`	Rejected with `400` (`mutually_exclusive_parameters`) — pick one way of continuing the exchange.

The response echoes the conversation it belongs to as "conversation": {"id": "conv-..."}. A response that fails before generating anything adds nothing to the conversation.

conversation is also accepted on /v1/responses/input_tokens, where the conversation's items are counted ahead of input.

Items¶

Items use the same shapes as the Responses API input and output: messages, reasoning items, function calls and their outputs.

Item IDs are assigned by the server. An id sent on a new item is ignored.
Adding items returns the items that were added, as a list envelope — not the whole conversation.
item_reference items point at an item already in the conversation; a reference to an item that is not there returns 404.
Deleting an item returns the conversation, and the item disappears from the listing.
include=reasoning.encrypted_content returns the encrypted content of reasoning items; other include values are accepted and ignored.

Listing¶

Parameter	Default	Notes
`order`	`desc`	`asc` is conversation order.
`limit`	`20`	Up to 100 items per page; `0` returns an empty page.
`after`	—	An item ID; only items strictly after it are returned. An ID that is not in the conversation returns `404`.
`include`	—	Extra item fields to return.

Each page carries first_id, last_id and has_more. Pass the page's last_id as after to read the next page; the server never auto-paginates.

Metadata¶

Limit	Value
Key-value pairs	16
Key length	64
Value length	512

Updating merges: keys that are not sent keep their value, and a key sent as null is removed. metadata is required on update — omitting it returns 400 (missing_required_parameter), and sending null returns 400 (invalid_type).

Limits¶

Limit	Value
Items per add request	20
Invocation steps read when listing a conversation	1,000 — a large item spans several, so a listing can stop early
Conversation lifetime	30 days after creation

A response bound to a conversation counts as one adding request, whatever its number of output items. Start a new conversation to continue an exchange that has reached the limit, and see Troubleshooting if a conversation stops accepting items earlier than expected.

Errors¶

Status	When
`400`	A malformed `conversation_id` or `item_id`, a metadata limit, an empty or oversized `items` list, or `conversation` combined with `previous_response_id`.
`404`	A well-formed identifier that names no conversation or item, including one created on another provider.

Prerequisites¶

Conversations are stored in Amazon Bedrock session storage in your own account. The gateway's IAM role needs the Bedrock Session Storage permissions; without them, conversation requests fail with 503. Set AWS_BEDROCK_SESSION_ENCRYPTION_KEY_ARN to encrypt conversation content with your own AWS KMS key.