Conversations API¶

Keep multi-turn state on the server, in Amazon Bedrock session storage in your own AWS account. 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.

At a glance¶

• Send only the new turn. Pass a conversation ID as conversation on a Responses request: the conversation's items become the input prefix, and both the request input and the response output are added back to it.
• Explicit item control. Add, list, retrieve and delete items yourself, independently of any model call — 1 to 20 items per add request.
• 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, up to 100 per page, with 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.
• Differs from OpenAI: a conversation expires 30 days after it is created, the window Amazon Bedrock session storage sets.

curl -X POST "$BASE/v1/conversations" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"topic": "travel"}}'

Endpoints¶

Feature compatibility¶

The Notes column says what happens to a field this API does not honor: accepted and ignored when the field only annotates the request, rejected with 400 when honoring it is the request.

Working with conversations¶

Using a Conversation with the Responses API¶

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 in the order they were sent — not the whole conversation.
• item_reference items ask for an item that already exists to be brought into the conversation. One naming an item the conversation already holds is refused with 400 item_already_in_conversation; send the item itself to add a second copy. An item held by another conversation or by a stored response cannot be reached here and returns 404.
• An item that configures a request rather than recording history — a compaction_trigger — is accepted and left out of the conversation: no conversation item type can express it, so it never appears in a listing, in a retrieval, or in the page counts. Every other item of the same request is stored.
• 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¶

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¶

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 and behaviour to know¶

Adding and deleting items is never rejected on a count: past 1,000 invocation steps a listing stops early instead, so it returns only part of the conversation and the prefix handed to the next Responses turn is truncated with it. Start a new conversation to continue an exchange that has reached the limit, and see Troubleshooting if a listing stops returning items earlier than expected.

Past the 30-day lifetime every route on a conversation answers 404, so an exchange that has to outlive the window keeps its own copy of the items.

Errors¶

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.

Try it¶

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.

Next steps¶

Next: Responses API · Session storage settings · IAM permissions