Sticky sessions

Use the optional x-session-id header for sticky routing across conversation turns to improve prompt-cache reuse.

Session header

Use the same header for these endpoints at https://api.paperinstruments.com:

HTTP header names are case-insensitive: X-Session-ID and x-session-id work on each endpoint.

Choose an ID for each conversation, such as a UUID. Reuse it across turns, including retries, tool results, and resumed conversations. Use a different ID for each conversation.

SDK examples

Configure your clients using the Chat Completions, Responses, and Messages guides. Pass the header as a request option, replacing your-conversation-id with your conversation's ID.

session_headers = {"x-session-id": "your-conversation-id"}

# OpenAI SDK: Chat Completions
completion = openai_client.chat.completions.create(
    model="ultramarine-1-flash",
    messages=[{"role": "user", "content": "Explain EBITDA."}],
    extra_headers=session_headers,
)

# OpenAI SDK: Responses
response = openai_client.responses.create(
    model="ultramarine-1-flash",
    input="Explain EBITDA.",
    extra_headers=session_headers,
)

# Anthropic SDK: Messages
message = anthropic_client.messages.create(
    model="ultramarine-1-flash",
    max_tokens=8192,
    messages=[{"role": "user", "content": "Explain EBITDA."}],
    extra_headers=session_headers,
)

Use the same request options for streaming calls, including the Anthropic SDK's messages.stream helper.

Without a session header

You can omit x-session-id. For Chat Completions and Responses, you can supply prompt_cache_key in the request body as an affinity hint. A non-empty x-session-id takes precedence. For Messages, use the header; the API rejects prompt_cache_key in the body.

Without either hint, routing uses the conversation's opening system and user messages, plus Chat Completions' user field if you supply it. This does not record a session routing preference.

Routing and cache behavior

Sticky routing is best effort and may change when capacity is unavailable. Keep repeated prompt prefixes stable to improve cache reuse. A session ID does not guarantee a cache hit or store your conversation history.

Send the full history for Chat Completions, Messages, and Responses.