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

Header	Endpoints	Value	Effect	Bad value
Authorization	All endpoints	Bearer <virtual key>	Identifies the project and the key	Missing: 401 missing_key. Not valid or revoked: 401 invalid_key
Content-Type	All POST endpoints	application/json, or a type that ends in +json	Marks the body as JSON	415. On chat/completions the code is unsupported_media_type. On the other endpoints the body is plain text

proxium reads the virtual key from Authorization only. It does not read x-api-key. The word Bearer and one space must come before the key.

Routing and attribution

Header	Endpoints	Value	Default	Effect	Bad value
x-proxium-source	chat/completions, messages, embeddings, moderations, rerank, responses, images/generations, audio/speech, video/*	A name for the calling application, for example support-bot	The project slug	Selects the routing chain and the budget of the application. Records the cost against the application	None. proxium takes any value that is not empty
x-proxium-timeout-ms	chat/completions, messages, embeddings, moderations, rerank, responses	A positive integer, in milliseconds	No limit for the whole chain	Sets a time limit for all attempts of the failover chain together. The maximum is 120000. proxium reduces a larger value to the maximum	proxium ignores a value that is not a positive integer

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

Memory

Header	Endpoints	Value	Default	Effect	Bad value
x-proxium-memory	chat/completions, messages	write, recall or off	write	write: proxium records the call when memory is on. recall: proxium also adds the matching memories to the request, as one system message. off: proxium does not record the call	400 invalid_memory_mode
x-proxium-memory	responses	write, recall or off	write	recall acts as write. off: proxium does not record the call	400 invalid_memory_mode
x-proxium-memory	embeddings, moderations, rerank	write, recall or off	write	No effect	400 invalid_memory_mode
x-proxium-memory-subject	chat/completions, messages, responses	The end user that the call is about. At most 256 characters, with no control characters	The user field of the body	Files the remembered call under this end user	400 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, messages, embeddings, moderations, rerank, responses, images/generations, audio/speech and video/generations.

Header	Value	Bad value
x-proxium-task-id	Your id for a task. GET /usage/me groups the cost by this id in by_task	None
x-proxium-turn-id	Your id for one turn of a conversation	None
x-proxium-agent-id	Your id for the agent that made the call	None
x-proxium-trigger-kind	What started the call, in your own words	None
x-proxium-trigger-detail	More detail about the trigger	None
x-proxium-iteration	An integer, for example the step number of an agent loop	proxium ignores a value that is not an integer
x-proxium-distil-saved	An integer: the tokens that your client removed from the prompt before the call	proxium records 0 for a value that is not an integer

Response headers

The value of retry-after is in seconds.

Header	When proxium sets it	Value
retry-after	429 tenant_capped or source_capped	60
content-type	A streamed answer	text/event-stream
cache-control	A streamed answer	no-cache
x-accel-buffering	A streamed answer	no
content-type	audio/speech and video/download	The media type of the audio or the video

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