POST /v1/chat

POST https://gateway.roadie.paroaria.ai/v1/chat
Authorization: Bearer rd_sk_prod_…
Content-Type: application/json

Generate a chat completion. Set stream: true to receive Server-Sent Events. A non-streaming call may carry an optional Idempotency-Key header for safe retries.

Authentication

Authenticated with a secret key (rd_sk_…) or a client token. A client token must carry the ai.chat scope, or the request fails 403 permission_error (insufficient_scope). A publishable key (rd_pk_…) is mint-only and is rejected 403 (publishable_key_mint_only).

Request body

Field	Type	Required	Notes
`model`	string	yes	An alias (e.g. `smart`) or explicit `provider/model` (e.g. `openai/gpt-4o`).
`messages`	Message[]	yes	The conversation (at least one). Roles: `system`, `user`, `assistant`, `tool`.
`stream`	boolean	no	`true` to stream via SSE. Default `false`.
`temperature`	number	no	Sampling temperature, `0`–`2`. Providers with a narrower range (e.g. Anthropic `0`–`1`) clamp.
`max_output_tokens`	integer	no	Positive upper bound on generated tokens.
`response_format`	object	no	`{ type: 'text' }`, `{ type: 'json_object' }`, or `{ type: 'json_schema', json_schema: { name, schema, description?, strict? } }`.
`tools`	ToolDefinition[]	no	Function tools the model may call (at least one when present).
`tool_choice`	string \| object	no	`auto` \| `none` \| `required` \| `{ type: 'function', function: { name } }`.
`user`	`{ id, plan? }`	no	The end user to attribute and limit. On a client token this is taken from the token; a mismatching `user.id` fails `400` (`end_user_mismatch`).
`metadata`	object<string,string>	no	Free-form string tags; `metadata.privacy` may tighten the privacy mode.
`provider_options`	object	no	Per-provider passthrough options, keyed by provider id (e.g. `{ "openai": { … } }`).

A message is { role, content }. content is a string or an array of parts. user messages may include text and image_url parts; system messages take text parts; assistant messages may carry tool_calls; a tool message is { role: 'tool', tool_call_id, content }. Unknown fields are rejected (400 invalid_request_error, with param naming the offending field).

Example

{
  "model": "smart",
  "messages": [
    { "role": "system", "content": "You are a concise assistant." },
    { "role": "user", "content": "Summarize the latest release notes." }
  ],
  "max_output_tokens": 512,
  "user": { "id": "user_42", "plan": "pro" },
  "metadata": { "feature": "release-summary" }
}

Non-streaming response

200 OK — the normalized completion:

{
  "id": "req_01J8…",
  "model": "openai/gpt-4o",
  "provider": "openai",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "…" }],
    "tool_calls": []
  },
  "finish_reason": "stop",
  "usage": { "input_tokens": 412, "output_tokens": 128, "total_tokens": 540, "source": "provider" },
  "cost": { "estimated_usd": 0.00114 },
  "provider_request_id": "req_mock_…",
  "gateway": { "fallback_used": false, "retries": 0, "latency_ms": 912 }
}

finish_reason — stop | length | tool_calls | content_filter.
message.content — always an array of text parts; tool_calls is always present (an empty array when no tool was called).
usage.source — provider (reported) or estimated. May also carry cached_input_tokens, reasoning_tokens, and image_input_tokens (each a subset of input_tokens).
provider_request_id — the upstream provider’s own id, when it returns one (omitted otherwise).
cost.estimated_usd — the gateway’s cost estimate for the call.
gateway — routing metadata: whether a fallback target served the request, retry count, and latency.

The response id equals the X-Request-Id response header.

Streaming response

With stream: true the response is text/event-stream by default; each data: line is one JSON frame, terminated by data: [DONE]. Request Accept: application/x-ndjson for newline-delimited JSON instead (the same frame objects, one per line, no [DONE]). See Streaming for the full event list.

data: {"type":"message_start","model":"openai/gpt-4o"}

data: {"type":"content_delta","index":0,"delta":"Hello"}

data: {"type":"tool_call_delta","index":0,"id":"call_1","name":"get_weather","argumentsDelta":"{\"city"}

data: {"type":"message_end","finish_reason":"stop","usage":{"input_tokens":412,"output_tokens":128,"total_tokens":540,"source":"provider"},"cost":{"estimated_usd":0.00114}}

data: [DONE]

Once the first frame is sent the request is committed — it can no longer fall back or retry. A mid-stream provider failure is delivered as a terminal error frame (no [DONE] follows), and the request finalizes as a stream interruption:

data: {"type":"error","error":{"type":"provider_error","code":"stream_interrupted","message":"…","request_id":"req_01J8…"}}

Idempotency

On a non-streaming request, send Idempotency-Key: <unique-id>. A retried request with the same key and body replays the stored response (with an Idempotency-Replayed: true header) without re-executing or re-metering; the same key with a different body fails 409 idempotency_error (idempotency_conflict). The header is ignored on streaming requests. The SDK sets this header automatically. See Idempotency & retries.

Cancellation

A running request can be aborted with POST /v1/requests/{request_id}/cancel, where request_id is the response id. A canceled request finalizes request_canceled (499).

Errors

Failures use the error envelope. Common cases: 401 authentication_error (bad or missing key), 403 permission_error (model_not_allowed, endpoint_not_allowed, end_user_blocked, insufficient_scope), 404 not_found_error (model_not_found, no_eligible_target), 400 invalid_request_error, 429 rate_limit_error / quota_error, 402 budget_error, 502 / 503 provider_error.

Introduction

Data plane

OpenAI-compatible

Control plane

Errors

Authentication

Request body

Example

Non-streaming response

Streaming response

Idempotency

Cancellation

Errors

​Authentication

​Request body

​Example

​Non-streaming response

​Streaming response

​Idempotency

​Cancellation

​Errors

Authentication

Request body

Example

Non-streaming response

Streaming response

Idempotency

Cancellation

Errors