Skip to main content

Request headers

Header names are not case-sensitive. The endpoint names below leave out the /v1 prefix where an endpoint has one.

Authentication and body​

HeaderEndpointsValueEffectBad value
AuthorizationAll endpointsBearer <virtual key>, or Bearer <token> with the token that proxium token printsA key identifies the project and the key. A token identifies you, and your projectMissing: 401 missing_key. A key that is not valid or revoked: 401 invalid_key. A token that is not valid or expired: 401 invalid_token
x-proxium-projectAll endpoints, with a token of proxium tokenThe slug of a project that you are a member ofThe one project of the tokenSelects the project of the call. Proxium ignores it with a virtual key, because a key names its project
x-api-key/v1/messages<virtual key> or a token of proxium tokenThe same as Authorization, as the Anthropic SDKs send it. Authorization wins when a request has bothAs for Authorization
Content-TypeAll POST endpointsapplication/json, or a type that ends in +jsonMarks the body as JSON415. On chat/completions the code is unsupported_media_type. On the other endpoints the body is plain text

The word Bearer and one space must come before the key in Authorization.

Routing and attribution​

HeaderEndpointsValueDefaultEffectBad value
x-proxium-sourcechat/completions, completions, messages, embeddings, moderations, rerank, responses, images/generations, audio/speech, audio/transcriptions, audio/translations, video/*A name for the calling application, for example support-botThe project slugSelects the routing chain and the budget of the application. Records the cost against the applicationNone. Proxium takes any value that is not empty
x-proxium-timeout-mschat/completions, completions, messages, embeddings, moderations, rerank, responsesA positive integer, in millisecondsNo limit for the whole chainSets a time limit for all attempts of the failover chain together. Proxium reduces a value above the maximum to the maximumProxium ignores a value that is not a positive integer
x-opencode-sessionchat/completions, messages, responsesThe session id that OpenCode sendsNoneProxium sends it on to an OpenCode Go vendor, which asks a proxy to keep it. Other vendors do not get itNone
x-proxium-keepchat/completions, messagesA mode: off, cut, extract, summarise or facts, then ; model=<tier or provider/model>The mode of the app settingShortens the long tool results of this call in that mode, with that helper model. It wins over the classification document and over the app setting. See shorten long tool results400 invalid_keep_mode, with the mode or the parameter that is not valid
x-proxium-cost-tierchat/completions, messageslow, medium, high, xhigh or maxThe cost tier of the project, set on Routing. No limit when the project sets noneProxium calls no model whose price is above the ceiling of the tier. The OpenRouter field plugins: [{"id": "auto-router", "cost_tier": …}] in the body wins over the header. When no model of the route is under the ceiling, the call fails with 400 cost_tier_too_low400 invalid_cost_tier

If the time limit of x-proxium-timeout-ms ends, Proxium stops the chain. It answers 503 upstream_failed, and the message starts with client deadline exceeded.

Memory​

HeaderEndpointsValueDefaultEffectBad value
x-proxium-memorychat/completions, messageswrite, recall or offwritewrite: Proxium records the call when memory is on. Sent explicitly, Proxium also learns from the conversation when it is one call with no end user. recall: Proxium also adds the matching memories to the request, as one system message. off: Proxium does not record the call400 invalid_memory_mode
x-proxium-memoryresponseswrite, recall or offwriterecall acts as write. off: Proxium does not record the call400 invalid_memory_mode
x-proxium-memoryembeddings, moderations, rerankwrite, recall or offwriteNo effect400 invalid_memory_mode
x-proxium-memory-subjectchat/completions, messages, responsesThe end user that the call is about. At most 256 characters, with no control charactersThe user field of the bodyFiles the remembered call under this end user400 invalid_memory_subject, only when Proxium records the call

The values of x-proxium-memory are not case-sensitive. An empty value is the same as write.

Proxium records a call only when memory is on for the project and for the application. recall and x-proxium-memory-subject have an effect only on a call that Proxium records. For how memory works, refer to Memory.

Correlation​

Proxium stores these values with the usage record of the call. They let you group calls by task, turn or agent. They have no effect on routing or budgets.

Endpoints: chat/completions, completions, messages, embeddings, moderations, rerank, responses, images/generations, audio/speech, audio/transcriptions, audio/translations and video/generations.

HeaderValueBad value
x-proxium-task-idYour id for a task. GET /usage/me groups the cost by this id in by_taskNone
x-proxium-turn-idYour id for one turn of a conversationNone
x-proxium-agent-idYour id for the agent that made the callNone
x-proxium-trigger-kindWhat started the call, in your own wordsNone
x-proxium-trigger-detailMore detail about the triggerNone
x-proxium-iterationAn integer, for example the step number of an agent loopProxium ignores a value that is not an integer
x-proxium-distil-savedAn integer: the tokens that your client removed from the prompt before the callProxium records no saving for a value that is not an integer

Example: the cost of one task​

Send the same x-proxium-task-id on each call of one task:

Terminal
for step in plan write check; do
curl -s https://proxium.tech/v1/chat/completions \
-H "Authorization: Bearer $PROXIUM_KEY" \
-H "Content-Type: application/json" \
-H "x-proxium-source: support-bot" \
-H "x-proxium-task-id: ticket-4812" \
-d "{\"model\": \"standard\", \"messages\": [{\"role\": \"user\", \"content\": \"$step\"}]}" > /dev/null
done
curl -s https://proxium.tech/usage/me -H "Authorization: Bearer $PROXIUM_KEY" | jq '.by_task[] | select(.task_id == "ticket-4812")'

The last command prints the cost, the tokens and the calls of the task.

Response headers​

The value of retry-after is in seconds.

HeaderWhen Proxium sets itValue
retry-after429 tenant_capped or source_capped60
content-typeA streamed answertext/event-stream
cache-controlA streamed answerno-cache
x-accel-bufferingA streamed answerno
content-typeaudio/speech and video/downloadThe media type of the audio or the video
x-proxium-classificationA chat/completions or messages call that a classification document classifiedA JSON object of the answers, by question name; tier, reasoning and model as the rules decided them; and flagged: the flags of the rules that held

For the error codes, refer to Errors. The API reference lists the headers of each endpoint.