Runtime Request Families

Select the gateway route that matches your client and the task: text, vectors, audio, or moderation. A request family is one of these API formats.

The route also controls whether the policy chain runs. Chat Completions, Responses, and Messages run it. Embeddings, audio, moderation, and legacy completions do not run it at this time.

Base URL and authentication

Send each request to the central agent URL of the agent. For a direct local test, use http://127.0.0.1:41002. Put the client API token in the Authorization: Bearer header. Do not use the gateway runtime token as the client credential. For the base URL of the control-plane API, see the API overview.

Request families

Family	Route	Use it for	Response
Chat Completions	POST /v1/chat/completions	OpenAI-style chat clients	JSON or SSE
Responses	POST /v1/responses	Responses-style text clients	JSON or SSE
Messages	POST /v1/messages	Anthropic-style message envelopes and content blocks	JSON or SSE
Embeddings	POST /v1/embeddings	Vector generation	JSON
Audio transcription	POST /v1/audio/transcriptions	Speech to text	JSON
Audio speech	POST /v1/audio/speech	Text to speech	Binary audio
Moderation	POST /v1/moderations	Content moderation through the configured backend	JSON
Legacy completions	POST /v1/completions	Legacy text-completion clients	JSON

Other gateway surfaces

The request family registry does not contain these surfaces. Each one keeps its own authentication, publication, routing, and governance boundary.

Surface	Route	Owning page
Model discovery	GET /v1/models and GET /v1/models/:model_id	Runtime Configuration
WebSocket proxy	GET /v1/chat/completions/ws and GET /v1/responses/ws	WebSocket Gateway
Published-host MCP	GET /mcp and POST /mcp	Gateway MCP Surface

The WebSocket routes apply request and response policy to complete text frames. They reject binary frames and malformed JSON-like text.

Policy stages by family

The stage identifiers below are the stages that the registry declares for each family. Different routes do not necessarily run the same controls.

The gateway evaluates the active policy chain only on the text families. The embeddings, audio, moderation, and legacy completions routes authenticate the request and apply provider access, capability, and budget checks. They do not evaluate the policy chain, so no control inspects their input or output. Do not send content to these routes that a policy control must examine first.

Family	Supported stages	Limit
Chat Completions	pre_request, post_request, pre_response	Full input and output policy path
Responses	pre_request, post_request, pre_response	Full input and output policy path
Messages	pre_request, post_request, pre_response	Same stage identifiers with an Anthropic-shaped body. Policy parity with Chat Completions and Responses is not a commitment.
Embeddings	pre_request	The policy chain is not evaluated
Audio transcription	pre_request	The policy chain is not evaluated
Audio speech	pre_request	The policy chain is not evaluated
Moderation	pre_request	The policy chain is not evaluated
Legacy completions	pre_request	The policy chain is not evaluated. No parity with Chat Completions

Select a text family

• If the client uses the OpenAI chat-completions shape, use /v1/chat/completions.
• If the client uses the Responses API, use /v1/responses.
• If the client must use the Anthropic Messages shape, use /v1/messages.

The three text families share the same stage identifiers. Route shape, streaming translation, structured-output support, and provider support are different. Run tests for the selected family with the active policy chain.

Examples

Structured outputs

Use a model that supports JSON schema output. This complete Chat Completions body specifies an order number:

{
  "model": "gpt-4o-mini",
  "messages": [
    {"role": "user", "content": "Return the order number from: Order 1042 is ready."}
  ],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "order_summary",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {"order_number": {"type": "integer"}},
        "required": ["order_number"],
        "additionalProperties": false
      }
    }
  }
}

Save it as request.json. Use the base URL and application token from the quickstart:

curl --fail-with-body "$VERDICTAN_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $VERDICTAN_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  --data-binary @request.json

The base URL ends in /v1. Replace the model with an allowed model that supports the schema. On success, parse choices[0].message.content as JSON. Make sure that order_number is 1042.

The Messages route does not accept the OpenAI response_format field. Read Format Translation before you use structured outputs through a different provider.

Request-time cache and session hints

Chat Completions and Responses accept these request-time hints when the runtime cache settings allow them. Do not infer equivalent handling on Messages from the shared field names.

Field	Location	Effect
cache_control	Request body	Requests prompt-caching behavior when the runtime policy allows it
session_id	Request body	Groups related requests onto the same session lane
x-session-id	Request header	Header form of the same session identifier

If a request contains session_id and x-session-id, the two values must match. The gateway rejects a mismatch with the reason code session_id_mismatch.

Limits and failure behavior

• The registry matches the exact method and path. A prefix such as /v1/chat/completions/ws is not a Chat Completions request.
• The embeddings, audio, moderation, and legacy completions routes do not evaluate the policy chain. A control in the chain does not block, redact, or record a decision for these requests.
• The provider must support structured output. Run a test of the selected model with the schema before production use.
• Runtime settings such as the default provider, moderation backend, model list, privacy, and response caches are not request-time selections. Configure them in the policy config. See Runtime Configuration.

Next steps

• OpenAI: send the first authenticated request through the Chat Completions family.
• Runtime Configuration: configure moderation, the models endpoint, and caches.
• Streaming and SSE: stream responses on the text families.
• WebSocket Gateway: use the WebSocket routes with policy on text frames.