Protocol Overview

Protocol Overview

ProxAI separates where data is in the proxy pipeline from which wire protocol that data uses. This page is the protocol guide hub: start here when you need to understand request paths, protocol values, conversion support, or per-protocol walkthroughs.

Two axes

1. 1inbound_requestThe original client request received by ProxAI.
2. 2provider_requestThe request ProxAI prepares for the selected upstream provider.
3. 3upstream_responseThe response returned by the upstream provider.
4. 4outbound_responseThe response ProxAI returns to the client-facing protocol.

Protocol value	Wire behavior
openai_responses	OpenAI Responses API: itemized output[], stable item_id, typed streaming events.
openai_chat_completions	OpenAI Chat Completions API: choices[], assistant messages, tool_calls[], [DONE] streams.
anthropic_messages	Anthropic Messages API: single Message, flat content[] blocks, content_block streaming events.

Routing is not translation

A route may select a provider whose protocol differs from the inbound request protocol. That requires an explicit translation pair; unsupported pairs fail explicitly.

Read by task

I need to configure routingUse this when you are deciding which provider handles which model or request endpoint.I need protocol behaviorUse this when you need request/response shape, streaming behavior, or interaction examples.I need conversion internalsUse this when maintaining `src/translation/` or reviewing cross-protocol semantics.I need exact protocol namesUse this as the stable lookup page for config values, request paths, and supported pairs.I need stop reason mappingUse this when comparing status, finish_reason, stop_reason, and terminal streaming events.

Protocol docs

Choose a protocolDecide inbound and provider protocols before configuring pass-through or conversion routes.Lossiness and fidelityUnderstand where cross-protocol conversion can preserve behavior but not exact source shape.OpenAI Responses overviewResponses request/response model and output item semantics.OpenAI Responses interaction exampleFunction tools, hosted tools, item ids, content parts, and terminal response events.OpenAI Chat Completions overviewChat completion choices, messages, deltas, and tool calls.OpenAI Chat Completions interaction exampleFunction tools, tool messages, `tool_calls[].index`, finish reasons, and `[DONE]`.Anthropic Messages overviewAnthropic message content blocks, stop reasons, and streaming events.Anthropic Messages interaction exampleLocal tools, server tools, content block indices, message deltas, and `message_stop`.Streaming behaviorTerminal events, SSE expectations, and stalled tool-call timeout behavior.

Choose the protocol path

Client calls	Detected request protocol	Start with
/v1/responses	openai_responses	OpenAI Responses
/v1/chat/completions	openai_chat_completions	OpenAI Chat Completions
/v1/messages	anthropic_messages	Anthropic Messages

Conversion support

Inbound \ Provider	Responses	Chat	Anthropic
openai_responses	Pass-through	Supported	Supported
openai_chat_completions	Unsupported	Pass-through	Supported
anthropic_messages	Supported	Unsupported	Pass-through

Unsupported pairs fail explicitly until implemented. The authoritative lookup lives in Protocols Reference.