{ "openapi": "3.1.0", "info": { "title": "proxium API", "description": "The routes that an application calls with the virtual key of a proxium project.\n\nSend the key as a bearer token: `Authorization: Bearer `. The key identifies the project. proxium never reads the identity of the caller from another header.\n\nproxium answers an OpenAI-dialect route with an OpenAI error body (`OpenAiError`), and `/v1/messages` with an Anthropic error body (`AnthropicError`). Before a handler runs, the HTTP framework can answer 400, 413, 415 or 422 with a plain-text body.", "license": { "name": "Elastic License 2.0", "identifier": "Elastic-2.0" }, "version": "0.1.0" }, "servers": [ { "url": "https://proxium.tech" } ], "paths": { "/status/peek": { "get": { "tags": [ "Models and status" ], "summary": "Read the state of the key", "description": "Returns the budget use of the key, the credit state of the project and the circuit breaker of each provider that the project can route to. A client can read it before a call to hold work that proxium will refuse. It uses no call slot. This route has no `/v1` path.", "operationId": "status_peek", "responses": { "200": { "description": "The state of the key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatusPeek" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/usage/me": { "get": { "tags": [ "Usage" ], "summary": "Read the usage of the project", "description": "Returns the spend of the project of the key in the current calendar month, with its monthly cap, and the spend by model and by task. This route has no `/v1` path.", "operationId": "usage_me", "responses": { "200": { "description": "The usage of the project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageMe" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/audio/speech": { "post": { "tags": [ "Media" ], "summary": "Generate speech", "description": "Converts text to audio with the speech provider of the model. proxium reserves the budget, builds the provider request and returns the audio bytes. The cache, failover and the timeout header do not apply to this route.", "operationId": "audio_speech", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/audio/createSpeech", "description": "OpenAI: create speech" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" } ], "requestBody": { "description": "`model` is necessary: a `provider/model` or `provider/voice` id, a tier name of the speech routing policy, or a model of the default speech provider. proxium reads `input` and `voice`. For an OpenAI-shape provider it also reads `response_format` (default `mp3`; `voice` default `alloy`). proxium ignores the other fields.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The audio. The content-type is the one that the provider row sets, and `audio/mpeg` when it sets none.", "content": { "audio/mpeg": { "schema": { "type": "string" } } } }, "400": { "description": "The body is not valid JSON (plain text), the body has no `model` (`missing_model`), or no speech provider serves it or the key may not use it (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "500": { "description": "The configuration of the provider names an unknown response shape (`bad_shape`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "The provider could not be reached (`upstream_failed`), answered with an error status (`upstream_error`), or sent an answer that proxium cannot read (`bad_upstream_response`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/chat/completions": { "post": { "tags": [ "Inference" ], "summary": "Create a chat completion", "description": "Runs an OpenAI chat completion request through the full proxium loop: authentication, memory, the response cache, the budget, routing, failover and cost. A cache hit costs no call slot. The answer is the provider's body without change. With `stream: true`, the answer is server-sent events. A cache hit is sent as events too.", "operationId": "chat_completions", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/chat/create", "description": "OpenAI: create a chat completion" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" }, { "name": "x-proxium-timeout-ms", "in": "header", "description": "The time limit in milliseconds for all attempts of the failover chain\ntogether. The maximum is 120000 on proxium.tech, and proxium reduces a\nlarger value to it.\nproxium ignores a value that is not a positive integer.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 30000 }, { "name": "x-proxium-memory", "in": "header", "description": "`write` (the default): when memory is on for the project and for this\nsource, proxium records the call. `recall`: proxium also puts the\nmemories that match the last user message into the request, as one\nsystem message. `off`: proxium does not record the call. Another value\ngets 400 `invalid_memory_mode`.", "required": false, "schema": { "type": "string", "description": "The values of `x-proxium-memory`.", "enum": [ "write", "recall", "off" ] }, "example": "recall" }, { "name": "x-proxium-memory-subject", "in": "header", "description": "The end user that a remembered call is about. At most 256 characters,\nwith no control characters. When you omit it, proxium uses the `user`\nfield of the body. When memory is on for the project and for this source,\na bad value gets 400 `invalid_memory_subject`.", "required": false, "schema": { "type": "string" }, "example": "user-1234" } ], "requestBody": { "description": "An OpenAI chat completion request. `model` is necessary. proxium resolves a tier name (for example `standard`) or `auto` through the routing policy of the project, and sends a `provider/model` id to that provider. proxium also reads `stream`, and adds `stream_options.include_usage` to a streamed request that it sends to the provider. With `x-proxium-memory: recall`, proxium adds one system message to `messages`. `user` is the memory subject when `x-proxium-memory-subject` is absent. proxium sends the other fields to the provider without change.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The provider's answer without change, or the cached answer.", "content": { "application/json": { "schema": { "type": "object" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The body is not a valid chat request (`bad_json`), a memory header has a bad value (`invalid_memory_mode`, `invalid_memory_subject`), or no model of the route is available to this key (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json` (`unsupported_media_type`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "Each attempt of the failover chain failed (`upstream_failed`). The message gives the reason of the last attempt, or `client deadline exceeded` when `x-proxium-timeout-ms` ran out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/embeddings": { "post": { "tags": [ "Inference" ], "summary": "Create embeddings", "description": "Sends an OpenAI embeddings request through the proxium loop: authentication, the budget, routing, failover and cost.", "operationId": "embeddings", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/embeddings/create", "description": "OpenAI: create embeddings" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" }, { "name": "x-proxium-timeout-ms", "in": "header", "description": "The time limit in milliseconds for all attempts of the failover chain\ntogether. The maximum is 120000 on proxium.tech, and proxium reduces a\nlarger value to it.\nproxium ignores a value that is not a positive integer.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 30000 } ], "requestBody": { "description": "An OpenAI embeddings request. `model` is necessary: a tier name, which proxium resolves through the routing policy of the project, or a `provider/model` id. proxium sends the other fields to the provider without change.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The provider's answer without change.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The body is not valid JSON (plain text), the body has no `model` (`missing_model`), `x-proxium-memory` is not `write`, `recall` or `off` (`invalid_memory_mode`), or no model of the route is available to this key (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "Each attempt of the failover chain failed (`upstream_failed`). The message gives the reason of the last attempt, or `client deadline exceeded` when `x-proxium-timeout-ms` ran out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/images/generations": { "post": { "tags": [ "Media" ], "summary": "Generate an image", "description": "Generates one image with the image provider of the model. proxium reserves the budget, builds the provider request and returns the image in the OpenAI `b64_json` shape for each provider. The routing policy can resolve a tier name in `model`. The cache, failover and the timeout header do not apply to this route.", "operationId": "images_generations", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/images/create", "description": "OpenAI: create an image" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" } ], "requestBody": { "description": "`model` is necessary: a `provider/model` id, a tier name of the image routing policy, or a model of the default image provider. proxium reads `prompt`. For an OpenAI-shape provider it also reads `n` (default 1) and `size` (default `1024x1024`). For an NVIDIA provider it reads `size`, `steps` (default 4), `seed` and `cfg_scale`. proxium ignores the other fields.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The image.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageResult" } } } }, "400": { "description": "The body is not valid JSON (plain text), the body has no `model` (`missing_model`), the model is not a valid id (`bad_model`), or no image provider serves it or the key may not use it (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "500": { "description": "The configuration of the provider names an unknown response shape (`bad_shape`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "The provider could not be reached (`upstream_failed`), answered with an error status (`upstream_error`), or sent an answer that proxium cannot read (`bad_upstream_response`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/memory/episodes/{id}": { "get": { "tags": [ "Memory" ], "summary": "Read a conversation", "description": "Returns one conversation of the project of the key, with the text that the memory worker read from it.", "operationId": "memory_episode", "parameters": [ { "name": "id", "in": "path", "description": "The id of the conversation.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The conversation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeDetail" } } } }, "400": { "description": "The id is not a UUID. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "404": { "description": "The project has no such conversation (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/memory/graph": { "post": { "tags": [ "Memory" ], "summary": "Read the knowledge graph", "description": "Returns the live facts of the knowledge graph of the project. The body is optional.", "operationId": "memory_graph", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/GraphQ" } ] } } } }, "responses": { "200": { "description": "The facts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Triples" } } } }, "400": { "description": "The body is not valid JSON (plain text).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "The JSON does not match the body schema. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/memory/items": { "post": { "tags": [ "Memory" ], "summary": "Write a memory", "description": "Writes one memory of the project of the key. The origin of the memory is `agent`, and its author is `key:`.", "operationId": "memory_remember", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewItem" } } }, "required": true }, "responses": { "201": { "description": "The memory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "The body is missing, `kind` or `importance` or `subject` has a bad value, or the text is empty or too long (`bad_request`). The body is not valid JSON (plain text).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "The key sent `pinned: true` (`forbidden`), or the memory screen blocked the text as a prompt injection (`guardrail_blocked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "409": { "description": "Memory is off for the project (`memory_off`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "The JSON does not match the body schema. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/memory/items/{id}": { "delete": { "tags": [ "Memory" ], "summary": "Remove a memory", "description": "Closes a live memory, so recall does not return it. A key can remove only a memory whose origin is `agent` or `observed`.", "operationId": "memory_forget", "parameters": [ { "name": "id", "in": "path", "description": "The id of the memory.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The memory is closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Removed" } } } }, "400": { "description": "The id is not a UUID. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A person wrote the memory (`forbidden`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "404": { "description": "The project has no such live memory (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } }, "patch": { "tags": [ "Memory" ], "summary": "Correct a memory", "description": "Replaces the text of a live memory. proxium closes the old memory and writes a new one with the new text. A key can change only a memory whose origin is `agent` or `observed`.", "operationId": "memory_correct", "parameters": [ { "name": "id", "in": "path", "description": "The id of the memory.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectReq" } } }, "required": true }, "responses": { "200": { "description": "The new memory.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "The body is missing, or the text is empty or too long (`bad_request`). The id is not a UUID (plain text). The body is not valid JSON (plain text).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A person wrote the memory (`forbidden`), or the memory screen blocked the text as a prompt injection (`guardrail_blocked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "404": { "description": "The project has no such live memory (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "409": { "description": "Memory is off for the project (`memory_off`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "The JSON does not match the body schema. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/memory/items/{id}/rating": { "post": { "tags": [ "Memory" ], "summary": "Rate a memory", "description": "Records whether a memory was useful or wrong when the agent used it.", "operationId": "memory_rate", "parameters": [ { "name": "id", "in": "path", "description": "The id of the memory.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateReq" } } }, "required": true }, "responses": { "200": { "description": "The memory with its new counts.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Item" } } } }, "400": { "description": "The body is missing (`bad_request`). The id is not a UUID (plain text). The body is not valid JSON (plain text).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "404": { "description": "The project has no such live memory (`not_found`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "The JSON does not match the body schema. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/memory/search": { "post": { "tags": [ "Memory" ], "summary": "Search the memory", "description": "Searches the conversations and the memories of the project of the key. When the project embeds, proxium also searches the memories by vector.", "operationId": "memory_search", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeySearchReq" } } }, "required": true }, "responses": { "200": { "description": "The matches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "description": "The body is missing (`bad_request`). The body is not valid JSON (plain text).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "The JSON does not match the body schema. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/memory/subjects/{subject}": { "delete": { "tags": [ "Memory" ], "summary": "Erase an end user", "description": "Erases one end user in one transaction: the memories, the profile page and the conversations of the end user, the stored bodies of the calls of the end user, and the chain parts that only those calls used. proxium keeps a SHA-256 of the subject so that a call already in the queue is discarded. You cannot undo this operation.", "operationId": "memory_erase_subject", "parameters": [ { "name": "subject", "in": "path", "description": "The end user: the `x-proxium-memory-subject` or `user` value of the calls.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The receipt of the erasure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Erased" } } } }, "400": { "description": "The subject is empty, longer than 256 characters, or holds a control character (`bad_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/memory/wake-up": { "post": { "tags": [ "Memory" ], "summary": "Read the memory at the start of a task", "description": "Returns what an agent reads at the start of a task: the pinned and the most trusted memories, the newest conversations, and the pages. The body is optional.", "operationId": "memory_wake_up", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/WakeQ" } ] } } } }, "responses": { "200": { "description": "The memory for the task.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WakeUp" } } } }, "400": { "description": "The body is not valid JSON (plain text).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "422": { "description": "The JSON does not match the body schema. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "500": { "description": "A database query failed (`query_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`), or the gateway has no database (`no_db`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/messages": { "post": { "tags": [ "Inference" ], "summary": "Create a message (Anthropic)", "description": "Accepts an Anthropic Messages request and runs it through the same proxium loop as `/v1/chat/completions`: proxium translates the request to the OpenAI chat shape, routes it to any provider, and translates the answer back to the Anthropic shape. With `stream: true`, the answer is Anthropic server-sent events. Each error body is in the Anthropic shape. The virtual key goes in `Authorization: Bearer`, or in `x-api-key` as the Anthropic SDKs send it.", "operationId": "messages", "externalDocs": { "url": "https://docs.anthropic.com/en/api/messages", "description": "Anthropic: the Messages API" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" }, { "name": "x-proxium-timeout-ms", "in": "header", "description": "The time limit in milliseconds for all attempts of the failover chain\ntogether. The maximum is 120000 on proxium.tech, and proxium reduces a\nlarger value to it.\nproxium ignores a value that is not a positive integer.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 30000 }, { "name": "x-proxium-memory", "in": "header", "description": "`write` (the default): when memory is on for the project and for this\nsource, proxium records the call. `recall`: proxium also puts the\nmemories that match the last user message into the request, as one\nsystem message. `off`: proxium does not record the call. Another value\ngets 400 `invalid_memory_mode`.", "required": false, "schema": { "type": "string", "description": "The values of `x-proxium-memory`.", "enum": [ "write", "recall", "off" ] }, "example": "recall" }, { "name": "x-proxium-memory-subject", "in": "header", "description": "The end user that a remembered call is about. At most 256 characters,\nwith no control characters. When you omit it, proxium uses the `user`\nfield of the body. When memory is on for the project and for this source,\na bad value gets 400 `invalid_memory_subject`.", "required": false, "schema": { "type": "string" }, "example": "user-1234" } ], "requestBody": { "description": "An Anthropic Messages request. `model` and `max_tokens` are necessary. proxium resolves a tier name in `model` (for example `standard`) or `auto` through the routing policy of the project, and sends a `provider/model` id to that provider. proxium translates `system`, `messages`, `tools`, `tool_choice`, `temperature`, `top_p`, `top_k`, `stop_sequences`, `stream` and `metadata.user_id`, and drops the other fields. It drops `thinking`, `redacted_thinking` and `document` blocks.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The answer in the Anthropic shape.", "content": { "application/json": { "schema": { "type": "object" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The body is not valid JSON, `model` or `max_tokens` is missing, the request cannot be translated, a memory header has a bad value, or no model of the route is available to this key (`invalid_request_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "502": { "description": "Each attempt of the failover chain failed. The message gives the reason of the last attempt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnthropicError" } } } } } } }, "/v1/models": { "get": { "tags": [ "Models and status" ], "summary": "List models", "description": "Lists the `provider/model` ids of the project of this key: the endpoints of the project, and the shared endpoints when the project has the platform pool. The list does not apply the `allowed_models` of the key. A client can call this route to validate a key.", "operationId": "models", "responses": { "200": { "description": "The models of this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/moderations": { "post": { "tags": [ "Inference" ], "summary": "Create a moderation", "description": "Sends an OpenAI moderation request through the proxium loop: authentication, the budget, routing, failover and cost.", "operationId": "moderations", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/moderations/create", "description": "OpenAI: create a moderation" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" }, { "name": "x-proxium-timeout-ms", "in": "header", "description": "The time limit in milliseconds for all attempts of the failover chain\ntogether. The maximum is 120000 on proxium.tech, and proxium reduces a\nlarger value to it.\nproxium ignores a value that is not a positive integer.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 30000 } ], "requestBody": { "description": "An OpenAI moderation request. `model` is necessary: a tier name, which proxium resolves through the routing policy of the project, or a `provider/model` id. proxium sends the other fields to the provider without change.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The provider's answer without change.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The body is not valid JSON (plain text), the body has no `model` (`missing_model`), `x-proxium-memory` is not `write`, `recall` or `off` (`invalid_memory_mode`), or no model of the route is available to this key (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "Each attempt of the failover chain failed (`upstream_failed`). The message gives the reason of the last attempt, or `client deadline exceeded` when `x-proxium-timeout-ms` ran out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/rerank": { "post": { "tags": [ "Inference" ], "summary": "Rerank documents", "description": "Sends a rerank request to the `/rerank` path of the provider, through the proxium loop: authentication, the budget, routing, failover and cost.", "operationId": "rerank", "externalDocs": { "url": "https://docs.cohere.com/reference/rerank", "description": "Cohere: the rerank API, the common shape of a rerank request" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" }, { "name": "x-proxium-timeout-ms", "in": "header", "description": "The time limit in milliseconds for all attempts of the failover chain\ntogether. The maximum is 120000 on proxium.tech, and proxium reduces a\nlarger value to it.\nproxium ignores a value that is not a positive integer.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 30000 } ], "requestBody": { "description": "A rerank request in the shape that the provider accepts. `model` is necessary: a tier name, which proxium resolves through the routing policy of the project, or a `provider/model` id. proxium sends the other fields to the provider without change.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The provider's answer without change.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "The body is not valid JSON (plain text), the body has no `model` (`missing_model`), `x-proxium-memory` is not `write`, `recall` or `off` (`invalid_memory_mode`), or no model of the route is available to this key (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "Each attempt of the failover chain failed (`upstream_failed`). The message gives the reason of the last attempt, or `client deadline exceeded` when `x-proxium-timeout-ms` ran out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/v1/responses": { "post": { "tags": [ "Inference" ], "summary": "Create a model response", "description": "Sends an OpenAI Responses request through the proxium loop: authentication, memory, the budget, routing, failover and cost. With `stream: true`, the answer is server-sent events. The response cache does not apply to this route.", "operationId": "responses", "externalDocs": { "url": "https://platform.openai.com/docs/api-reference/responses/create", "description": "OpenAI: create a model response" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" }, { "name": "x-proxium-timeout-ms", "in": "header", "description": "The time limit in milliseconds for all attempts of the failover chain\ntogether. The maximum is 120000 on proxium.tech, and proxium reduces a\nlarger value to it.\nproxium ignores a value that is not a positive integer.", "required": false, "schema": { "type": "integer", "format": "int64", "minimum": 0 }, "example": 30000 }, { "name": "x-proxium-memory", "in": "header", "description": "`write` (the default) and `recall`: when memory is on for the project and\nfor this source, proxium records the call. proxium puts memories into\nchat and Messages calls only. `off`: proxium does not record the call.\nAnother value gets 400 `invalid_memory_mode`.", "required": false, "schema": { "type": "string", "description": "The values of `x-proxium-memory`.", "enum": [ "write", "recall", "off" ] }, "example": "off" }, { "name": "x-proxium-memory-subject", "in": "header", "description": "The end user that a remembered call is about. At most 256 characters,\nwith no control characters. When you omit it, proxium uses the `user`\nfield of the body. When memory is on for the project and for this source,\na bad value gets 400 `invalid_memory_subject`.", "required": false, "schema": { "type": "string" }, "example": "user-1234" } ], "requestBody": { "description": "An OpenAI Responses request. `model` is necessary: a tier name, which proxium resolves through the routing policy of the project, or a `provider/model` id. proxium sends the other fields to the provider without change. proxium reads `stream`. `user` is the memory subject when `x-proxium-memory-subject` is absent.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The provider's answer without change.", "content": { "application/json": { "schema": { "type": "object" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "The body is not valid JSON (plain text), the body has no `model` (`missing_model`), a memory header has a bad value (`invalid_memory_mode`, `invalid_memory_subject`), or no model of the route is available to this key (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "Each attempt of the failover chain failed (`upstream_failed`). The message gives the reason of the last attempt, or `client deadline exceeded` when `x-proxium-timeout-ms` ran out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/video/download": { "post": { "tags": [ "Media" ], "summary": "Download a video", "description": "Downloads a finished video from the provider and returns its bytes. Each download uses one call slot of the budget. This route has no `/v1` path.", "operationId": "video_download", "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" } ], "requestBody": { "description": "`uri` is necessary: the `video_uri` that `/video/operations` returned. It must be an `https` address on `googleapis.com`. `provider` is the value that `/video/generations` returned. Without it, proxium uses the default video provider.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The video. The content-type is the one that the provider row sets, and `video/mp4` when it sets none.", "content": { "video/mp4": { "schema": { "type": "string" } } } }, "400": { "description": "The body is not valid JSON (plain text), the body has no `uri` (`missing_uri`), the address is not a Google API host (`forbidden_target`), or no video provider is configured (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "The provider could not be reached or its answer is too large (`upstream_failed`), or it answered with an error status (`upstream_error`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/video/generations": { "post": { "tags": [ "Media" ], "summary": "Start a video", "description": "Starts a video operation at the video provider of the model, and returns the operation name. Poll it with `/video/operations`. proxium records the call at this step. This route has no `/v1` path.", "operationId": "video_submit", "externalDocs": { "url": "https://ai.google.dev/gemini-api/docs/video", "description": "Google: generate videos with Veo in the Gemini API" }, "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" } ], "requestBody": { "description": "`model` is a `provider/model` id, a tier name of the video routing policy, or a model of the default video provider. proxium reads `prompt`, `aspect_ratio` (default `16:9`), `duration` (seconds as a string, default `8`) and `resolution`. proxium ignores the other fields.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The operation started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoOperation" } } } }, "400": { "description": "The body is not valid JSON (plain text), the model is not a valid id (`bad_model`), or no video provider serves it or the key may not use it (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "403": { "description": "A content rule of the project blocked the request (`guardrail_blocked`). The message names the class and the field. It never holds the matched value. proxium.tech has no content rule on for a project today.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "500": { "description": "The configuration of the provider names an unknown response shape (`bad_shape`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "The provider could not be reached (`upstream_failed`), answered with an error status (`upstream_error`), or sent an answer that proxium cannot read (`bad_upstream_response`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } }, "/video/operations": { "post": { "tags": [ "Media" ], "summary": "Poll a video", "description": "Reads the state of a video operation from the provider. Each poll uses one call slot of the budget. This route has no `/v1` path.", "operationId": "video_poll", "parameters": [ { "name": "x-proxium-source", "in": "header", "description": "A name for the calling application. proxium uses it to select the\nrouting override and the budget of that application, and to attribute\nthe cost. When you omit it, proxium uses the project slug.", "required": false, "schema": { "type": "string" }, "example": "support-bot" } ], "requestBody": { "description": "`operation` is necessary: the value that `/video/generations` returned. `provider` is the value that `/video/generations` returned. Without it, proxium uses the default video provider.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "200": { "description": "The state of the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VideoPoll" } } } }, "400": { "description": "The body is not valid JSON (plain text), the body has no `operation` (`missing_operation`), the poll address is not a Google API host (`forbidden_target`), or no video provider is configured (`no_route`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } }, "text/plain": { "schema": { "type": "string" } } } }, "401": { "description": "The bearer virtual key is missing (`missing_key`), or it is not valid or it is revoked (`invalid_key`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "402": { "description": "The project may not send calls (`subscription_required`). proxium.tech is in open beta and does not return this answer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "413": { "description": "The body is larger than the request body limit, 32 MiB on proxium.tech. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "415": { "description": "The content-type is not `application/json`. The body of this answer is plain text.", "content": { "text/plain": { "schema": { "type": "string" } } } }, "429": { "description": "The key or the source used its budget window (`tenant_capped` or `source_capped`, `retry-after: 60`), or the project reached a monthly cap (`credits_exhausted`, `retry-after: 3600`). No project on proxium.tech has a monthly cap during the open beta.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "500": { "description": "The configuration of the provider names an unknown response shape (`bad_shape`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "502": { "description": "The provider could not be reached (`upstream_failed`), or the operation failed (`video_failed`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } }, "503": { "description": "The key store or the limits store is not available (`keystore_unavailable`, `limits_unavailable`). A deployment that refuses calls while its budget store is down answers `budget_unavailable` with `retry-after: 5`; proxium.tech lets the call through.", "headers": { "retry-after": { "schema": { "type": "string" }, "description": "Seconds to wait before the next call." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenAiError" } } } } } } } }, "components": { "schemas": { "AnthropicError": { "type": "object", "description": "The error body of `/v1/messages`, in the Anthropic shape.", "required": [ "type", "error" ], "properties": { "error": { "$ref": "#/components/schemas/AnthropicErrorDetail" }, "type": { "type": "string", "description": "Always `error`.", "example": "error" } } }, "AnthropicErrorDetail": { "type": "object", "description": "One refusal or failure, in the Anthropic shape.", "required": [ "type", "message" ], "properties": { "message": { "type": "string", "description": "The text for a person." }, "type": { "type": "string", "description": "The Anthropic error type of the HTTP status: `invalid_request_error`\n(400, 415, 422), `authentication_error` (401), `permission_error` (402,\n403), `not_found_error` (404), `request_too_large` (413),\n`rate_limit_error` (429), `overloaded_error` (529) or `api_error`.", "example": "authentication_error" } } }, "BudgetUse": { "type": "object", "description": "How much of the key's budget windows is used, in percent.", "required": [ "calls_pct", "cost_pct" ], "properties": { "calls_pct": { "type": "integer", "format": "int32", "description": "Percent of the rolling calls window. 0 when the budget store is not\navailable.", "minimum": 0 }, "cost_pct": { "type": "integer", "format": "int32", "description": "Percent of the daily cost ceiling. 0 when the budget store is not\navailable.", "minimum": 0 } } }, "CorrectReq": { "type": "object", "description": "The new text of a memory.", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "At most 4,000 characters. proxium blocks a prompt injection in it and\nredacts a credential before it stores the text." } } }, "CreditsOver": { "type": "object", "description": "The monthly cap of the project.", "required": [ "over" ], "properties": { "over": { "type": "boolean", "description": "`true` when the project reached its monthly cap." } } }, "Episode": { "type": "object", "description": "One conversation that memory recorded.", "required": [ "id", "source", "started_at", "last_turn_at", "turns", "pending" ], "properties": { "id": { "type": "string", "format": "uuid" }, "last_turn_at": { "type": "string", "format": "date-time" }, "pending": { "type": "boolean", "description": "`true` while the memory worker has not read the latest turn." }, "source": { "type": "string", "description": "The `x-proxium-source` of the calls." }, "started_at": { "type": "string", "format": "date-time" }, "subject": { "type": [ "string", "null" ], "description": "The end user of the calls: `x-proxium-memory-subject`, or the `user` field." }, "summary": { "type": [ "string", "null" ], "description": "The summary that the memory worker wrote. `null` until it reads the\nconversation." }, "title": { "type": [ "string", "null" ], "description": "The title that the memory worker wrote. `null` until it reads the\nconversation." }, "turns": { "type": "integer", "format": "int32" } } }, "EpisodeDetail": { "allOf": [ { "$ref": "#/components/schemas/Episode" }, { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } ], "description": "One conversation and its messages." }, "Erased": { "type": "object", "description": "The receipt of the erasure of one end user.", "required": [ "erased", "deleted", "total_rows" ], "properties": { "deleted": { "type": "object", "description": "The rows that the erasure deleted, by table.", "additionalProperties": { "type": "integer", "format": "int64" }, "propertyNames": { "type": "string" } }, "erased": { "type": "boolean", "description": "Always `true`." }, "total_rows": { "type": "integer", "format": "int64", "description": "The sum of `deleted`." } } }, "GraphQ": { "type": "object", "description": "A query of the knowledge graph.", "properties": { "entity": { "type": [ "string", "null" ], "description": "The facts of this entity, as the start or the end of a fact. Without it,\nthe newest facts." }, "limit": { "type": [ "integer", "null" ], "format": "int64", "description": "The most facts to return. The default is 100." }, "subject": { "type": [ "string", "null" ], "description": "The facts of this end user and of the project. Without it, the facts of\nthe project only." } } }, "Hit": { "allOf": [ { "$ref": "#/components/schemas/Episode" }, { "type": "object", "required": [ "score" ], "properties": { "score": { "type": "number", "format": "double" }, "snippet": { "type": [ "string", "null" ], "description": "The best matching passage, with each match between « and »." } } } ], "description": "A conversation that matches a search, with its score." }, "ImageData": { "type": "object", "description": "One generated image.", "required": [ "b64_json" ], "properties": { "b64_json": { "type": "string", "description": "The image, base64-encoded." } } }, "ImageResult": { "type": "object", "description": "The answer of `/v1/images/generations`, in the OpenAI image shape, for every\nimage provider.", "required": [ "created", "model", "data" ], "properties": { "created": { "type": "integer", "format": "int64", "description": "Always 0." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ImageData" }, "description": "One image." }, "model": { "type": "string", "description": "The `provider/model` that made the image." } } }, "Item": { "type": "object", "description": "One memory of the project.", "required": [ "id", "kind", "text", "origin", "author", "via", "importance", "pinned", "valid_from", "retrieved_count", "useful_count", "wrong_count", "created_at" ], "properties": { "author": { "type": "string", "description": "The member, or `key:` for a virtual key." }, "created_at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "importance": { "type": "integer", "format": "int32", "description": "0 to 5." }, "kind": { "type": "string", "description": "`fact`, `preference`, `decision`, `event` or `procedure`." }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "origin": { "type": "string", "description": "`human`, `agent` or `observed`. A writer changes only the memories of its\nown origin or a lower one." }, "pinned": { "type": "boolean" }, "retrieved_count": { "type": "integer", "format": "int32" }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "subject": { "type": [ "string", "null" ], "description": "The end user that the memory is about. `null` for a memory of the project." }, "superseded_by": { "type": [ "string", "null" ], "format": "uuid" }, "text": { "type": "string" }, "useful_count": { "type": "integer", "format": "int32" }, "valid_from": { "type": "string", "format": "date-time" }, "valid_to": { "type": [ "string", "null" ], "format": "date-time" }, "via": { "type": "string", "description": "`console`, `mcp` or `api`." }, "wrong_count": { "type": "integer", "format": "int32" } } }, "KeySearchReq": { "type": "object", "description": "A search of the memory of the project.", "required": [ "query" ], "properties": { "limit": { "type": [ "integer", "null" ], "format": "int64", "description": "The most conversations to return. The default is 20." }, "query": { "type": "string", "description": "The words to find." }, "source": { "type": [ "string", "null" ], "description": "Only the conversations of this `x-proxium-source`." }, "subject": { "type": [ "string", "null" ], "description": "Only the conversations of this end user, and only the memories of this\nend user and of the project." } } }, "Message": { "type": "object", "description": "One message of a conversation, as the memory worker read it.", "required": [ "position", "role", "text" ], "properties": { "position": { "type": "integer", "format": "int32" }, "role": { "type": "string" }, "text": { "type": "string" } } }, "ModelEntry": { "type": "object", "description": "One model of the project of the key.", "required": [ "id", "object", "owned_by" ], "properties": { "id": { "type": "string", "description": "The `provider/model` id. Send it as `model` to call this model directly.", "example": "openai/gpt-4o-mini" }, "object": { "type": "string", "description": "Always `model`.", "example": "model" }, "owned_by": { "type": "string", "description": "Always `proxium`.", "example": "proxium" } } }, "ModelList": { "type": "object", "description": "The models of the project of the key, in the OpenAI list shape.", "required": [ "object", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ModelEntry" } }, "object": { "type": "string", "description": "Always `list`.", "example": "list" } } }, "NewItem": { "type": "object", "description": "A memory to write.", "required": [ "text" ], "properties": { "importance": { "type": [ "integer", "null" ], "format": "int32", "description": "0 to 5. The default is 3." }, "kind": { "type": "string", "description": "`fact`, `preference`, `decision`, `event` or `procedure`.", "default": "fact" }, "pinned": { "type": [ "boolean", "null" ], "description": "Only a person can pin. A virtual key that sends `true` gets 403." }, "subject": { "type": [ "string", "null" ], "description": "The end user that the memory is about. Omit it for a memory of the\nproject." }, "text": { "type": "string", "description": "At most 4,000 characters. proxium screens it: a prompt injection blocks\nthe write, and a credential is redacted." } } }, "OpenAiError": { "type": "object", "description": "The error body of every OpenAI-dialect endpoint.\n\nThe OpenAI SDKs read `error.message` and `error.type`. proxium puts the same\nmachine-readable reason in `type` and in `code`.", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/OpenAiErrorDetail" } } }, "OpenAiErrorDetail": { "type": "object", "description": "One refusal or failure.", "required": [ "message", "type", "code" ], "properties": { "code": { "type": "string", "description": "The same value as `type`.", "example": "invalid_key" }, "message": { "type": "string", "description": "The text for a person. It never holds a value that a content rule matched." }, "type": { "type": "string", "description": "The machine-readable reason, for example `invalid_key`, `tenant_capped`,\n`no_route` or `upstream_failed`.", "example": "invalid_key" } } }, "Page": { "type": "object", "description": "A page that the memory worker writes from the memories.", "required": [ "text", "memories", "updated_at" ], "properties": { "memories": { "type": "integer", "format": "int32" }, "subject": { "type": [ "string", "null" ], "description": "`None` is the project's page, a value that end user's profile." }, "text": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ProviderState": { "type": "object", "description": "The circuit breaker of one provider, as the next call of this key sees it.", "required": [ "provider", "state" ], "properties": { "provider": { "type": "string", "example": "openai" }, "state": { "type": "string", "description": "`closed` (calls go through), `open` (calls skip this provider) or\n`half_open` (one trial call goes through).", "example": "closed" } } }, "RateReq": { "type": "object", "description": "A rating of a memory.", "required": [ "rating" ], "properties": { "rating": { "$ref": "#/components/schemas/Rating" } } }, "Rating": { "type": "string", "description": "What the agent found when it used a memory. `useful` and `wrong` each add\none to their count. Two `wrong` marks take a memory that no person reviewed\nout of recall.", "enum": [ "useful", "wrong" ] }, "Removed": { "type": "object", "description": "The memory that a delete closed.", "required": [ "removed" ], "properties": { "removed": { "type": "string", "format": "uuid" } } }, "SearchResult": { "type": "object", "description": "The conversations and the memories that match a search.", "required": [ "query", "results", "memories" ], "properties": { "memories": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "description": "The memories that match, best first. At most 20. Each one counts as\nretrieved." }, "query": { "type": "string", "description": "The query, as it was sent." }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Hit" }, "description": "The conversations that match, best first." } } }, "StatusPeek": { "type": "object", "description": "The state of the calling key before a call. Reading it costs no call slot.", "required": [ "tenant_capped", "budget", "credits", "providers", "any_provider_available" ], "properties": { "any_provider_available": { "type": "boolean", "description": "`true` when at least one of `providers` is not `open`, or when the list is\nempty." }, "budget": { "$ref": "#/components/schemas/BudgetUse" }, "credits": { "$ref": "#/components/schemas/CreditsOver" }, "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ProviderState" }, "description": "The circuit breaker of each provider that the project can route to." }, "tenant_capped": { "type": "boolean", "description": "`true` when the next call will be refused: the key used 100% of its calls\nor cost window, or the project reached its monthly cap." } } }, "Triple": { "type": "object", "description": "One live fact of the knowledge graph: `from` `predicate` `to`.", "required": [ "id", "item_id", "from", "predicate", "to", "valid_from" ], "properties": { "from": { "type": "string" }, "id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid", "description": "The memory that the fact comes from." }, "predicate": { "type": "string" }, "subject": { "type": [ "string", "null" ], "description": "The end user of the fact. `null` for a fact of the project." }, "to": { "type": "string" }, "valid_from": { "type": "string", "format": "date-time" } } }, "Triples": { "type": "object", "description": "The live facts of the knowledge graph that match.", "required": [ "triples" ], "properties": { "triples": { "type": "array", "items": { "$ref": "#/components/schemas/Triple" }, "description": "Newest first." } } }, "UsageByModel": { "type": "object", "description": "The spend of one model this month.", "required": [ "provider", "model", "cost_usd_millicents", "tokens", "requests" ], "properties": { "cost_usd_millicents": { "type": "integer", "format": "int64" }, "model": { "type": "string" }, "provider": { "type": "string" }, "requests": { "type": "integer", "format": "int64" }, "tokens": { "type": "integer", "format": "int64" } } }, "UsageByTask": { "type": "object", "description": "The spend of one task this month.", "required": [ "task_id", "cost_usd_millicents", "tokens", "requests" ], "properties": { "cost_usd_millicents": { "type": "integer", "format": "int64" }, "requests": { "type": "integer", "format": "int64" }, "task_id": { "type": "string", "description": "The `x-proxium-task-id` header that the calls carried." }, "tokens": { "type": "integer", "format": "int64" } } }, "UsageCredits": { "type": "object", "description": "The monthly cap of the project, and how much of it is used. No project on\nproxium.tech has a monthly cap during the open beta.", "required": [ "unlimited", "granted_millicents", "used_millicents", "granted_usd", "used_usd" ], "properties": { "granted_millicents": { "type": "integer", "format": "int64", "description": "The monthly cap. 0 when `unlimited` is `true`." }, "granted_usd": { "type": "number", "format": "double", "description": "`granted_millicents` in USD." }, "remaining_millicents": { "type": [ "integer", "null" ], "format": "int64", "description": "`granted_millicents` minus `used_millicents`, never below 0. `null` when\n`unlimited` is `true`." }, "unlimited": { "type": "boolean", "description": "`true` when the project has no monthly cap." }, "used_millicents": { "type": "integer", "format": "int64", "description": "The real cost of this month's calls." }, "used_usd": { "type": "number", "format": "double", "description": "`used_millicents` in USD." } } }, "UsageMe": { "type": "object", "description": "The calling project's own usage in the current calendar month (UTC).\n\nMoney is in millicents: 100,000 millicents are 1 USD.", "required": [ "tenant_slug", "tier", "period", "credits", "requests", "tokens", "by_model", "by_task" ], "properties": { "by_model": { "type": "array", "items": { "$ref": "#/components/schemas/UsageByModel" }, "description": "Spend by `provider` and `model`, highest cost first." }, "by_task": { "type": "array", "items": { "$ref": "#/components/schemas/UsageByTask" }, "description": "Spend by `x-proxium-task-id`, highest cost first. At most 100 rows." }, "credits": { "$ref": "#/components/schemas/UsageCredits" }, "period": { "type": "string", "description": "Always `month`.", "example": "month" }, "requests": { "type": "integer", "format": "int64", "description": "Calls this month." }, "tenant_slug": { "type": "string", "description": "The project of the key." }, "tier": { "type": "string", "description": "The tier of the key." }, "tokens": { "type": "integer", "format": "int64", "description": "Input, output, cache-read and cache-write tokens this month." } } }, "VideoOperation": { "type": "object", "description": "A started video operation. Send both fields to `/video/operations` to poll it.", "required": [ "operation", "provider" ], "properties": { "operation": { "type": "string", "description": "The provider's operation name." }, "provider": { "type": "string", "description": "The video provider that runs the operation." } } }, "VideoPoll": { "type": "object", "description": "The state of a video operation.", "required": [ "done" ], "properties": { "done": { "type": "boolean", "description": "`false` while the provider renders the video." }, "video_uri": { "type": [ "string", "null" ], "description": "The location of the finished video. It is present only when `done` is\n`true`. Send it as `uri` to `/video/download`." } } }, "WakeQ": { "type": "object", "description": "The end user of a task.", "properties": { "subject": { "type": [ "string", "null" ], "description": "Also read the memories and the profile of this end user." } } }, "WakeUp": { "type": "object", "description": "What an agent reads at the start of a task: the pinned memories, then the most\ntrusted, then the newest conversations' summaries.", "required": [ "memories", "conversations", "pages" ], "properties": { "conversations": { "type": "array", "items": { "$ref": "#/components/schemas/Episode" }, "description": "The newest conversations." }, "memories": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "description": "The pinned memories, then the most trusted. At most 20." }, "pages": { "type": "array", "items": { "$ref": "#/components/schemas/Page" }, "description": "The project's page, and the end user's profile when a subject is named." } } } }, "securitySchemes": { "virtual_key": { "type": "http", "scheme": "bearer", "description": "The virtual key of a proxium project. Create it in the console. It identifies the project, and its allowed models, tier and ceilings apply to each call." } } }, "security": [ { "virtual_key": [] } ], "tags": [ { "name": "Inference", "description": "Chat, Messages, Responses, embeddings, moderation and rerank calls. Each call goes through the request loop of proxium: authentication, budget, routing, failover and cost. The response cache applies to chat and Messages calls only." }, { "name": "Media", "description": "Image, speech and video generation. A vendor adapter of proxium builds the provider request from the fields that each route names." }, { "name": "Models and status", "description": "The models of the project, and the state of the key before a call." }, { "name": "Usage", "description": "The spend of the calling project." }, { "name": "Memory", "description": "The memory of the calling project. Each write with a virtual key is an agent's write." } ] }