Skip to main content

Conversation history and state

Keep conversation history in your application or client. A request ID in Primex Usage correlates a request and charge; it is not a conversation ID or a copy of the response. Each new model turn has its own usage and billing.

Choose the continuation format​

API pathHistory your application sends
Chat CompletionsA messages array with the relevant user, assistant and tool messages
Native ResponsesSupported input items, including prior output/tool items when replaying history
MessagesThe relevant user/assistant content blocks, with system sent separately
Responses rewritten to ChatA complete input/history that can be represented as Chat messages; native Responses state is not provided

For a simple Chat conversation, append the returned assistant message, then the next user message to your stored messages. Do not send only the latest question if it depends on earlier turns. Keep enough context for the task while respecting the model's context and current rate limits.

Tool-result continuations​

Preserve the model's tool call and its identifier before executing the tool. Return the result in the same API format:

  • Chat Completions: append the assistant's tool_calls, then a role: "tool" message with the matching tool_call_id.
  • Native Responses: retain the required previous output items and send the matching function_call_output using the original call_id. Custom tools use their own supported output item shape.
  • Messages: retain the assistant's tool_use blocks, then supply matching tool_result blocks with tool_use_id in the next user turn.

Send a result for each tool your application executes. Do not invent new IDs or display tool calls as a completed text answer. See the runnable function-tool loop.

Native Responses state​

Native Responses forwards supported provider-native request fields. State features such as previous_response_id, store and encrypted reasoning depend on the actual model/provider path. Native Responses support alone does not establish that all state features are available.

Primex does not publish a universal conversation-store lifetime, a general Responses retrieval/deletion API, or a guarantee that a saved provider response can continue across a different model or serving account. Keep the history you need for your application; do not use a provider response ID as your only backup. store: false is a provider request option where supported, not a statement about all Primex logs or data retention. See Privacy and team evaluation.

When replaying native output, preserve required reasoning and tool items according to the selected route's contract. Encrypted reasoning/compaction items are opaque: do not modify them or assume they are portable across models/providers.

The separate POST /v1/responses/compact route requires a native Responses model. Compaction is provider model work and can be billed; it is not a free metadata read or a Chat Completions feature. The provider's supported compaction contract applies. Chat-only models return unsupported_responses_compaction.

Files and hosted containers​

Use Primex Files with the correct purpose, ownership and expiry. A temporary file reference does not preserve the surrounding conversation. Claude Files and hosted Skills have a separate contract; the documented Skills workflow requires a fresh container and does not allow container reuse. Generic Messages history does not enable those features.

Recover a failed continuation​

For invalid_encrypted_content, preserve the safe error code and request ID. Start a fresh client session or deliberately rebuild supported plain conversation history with the user. Do not automatically strip opaque items, retry the same payload, or replay tool side effects to conceal a state error.

After a timeout or interrupted stream, inspect Usage before starting another paid turn. Retain already-executed tool outcomes so a recovery does not repeat external actions. See Errors & Limits and Streaming.