Chat completions (OpenAI-compatible)

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

The OpenAI Chat Completions contract, for drop-in use with the OpenAI SDKs — point a stock client at the base URL https://gateway.roadie.paroaria.ai/openai/v1 with a Roadie key. Requests are translated to the unified contract and flow through the same routing, fallback, metering, and enforcement as the native POST /v1/chat; only the wire shape at the edge differs.

Authentication

Authenticated with a secret key (rd_sk_…) or a client token (carrying the ai.chat scope). A publishable key is rejected 403.

Request body

The standard OpenAI Chat Completions body. The gateway reads the fields below and safely ignores unknown ones.

Field	Type	Required	Notes
`model`	string	yes	See model resolution.
`messages`	Message[]	yes	Roles `system`, `developer`, `user`, `assistant`, `tool`, `function`.
`stream`	boolean	no	`true` to stream `chat.completion.chunk` events.
`stream_options`	`{ include_usage }`	no	`include_usage: true` appends a final usage chunk to the stream.
`temperature`	number	no	Passed through.
`max_tokens` / `max_completion_tokens`	integer	no	Mapped to `max_output_tokens`; `max_completion_tokens` wins when both are sent.
`tools` / `tool_choice`	array / string \| object	no	Function tools and choice.
`functions` / `function_call`	array / string \| object	no	Legacy equivalents, used only when the modern fields are absent.
`response_format`	object	no	`text`, `json_object`, or `json_schema`.
`top_p`, `stop`, `presence_penalty`, `frequency_penalty`, `seed`, `logit_bias`	—	no	Forwarded to OpenAI via provider options.
`user`	string	no	Attributed as the end-user id.
`n`	integer	no	Only `n=1` is supported; `n>1` fails `400` (`unsupported_parameter`).

Translation details: developer → system (message name is dropped); a string user becomes the end-user id; the platform-native fields metadata and provider_options are not part of this surface — use the native /v1/chat endpoint for those.

Model resolution

The model you send is resolved deterministically: a project alias (e.g. smart) passes through; a qualified provider/model (e.g. openai/gpt-4o) passes through; a bare OpenAI name (e.g. gpt-4o) resolves to openai/<name> when it is in your catalog, otherwise to a unique catalog entry with that native id. A bare name that matches more than one provider fails 400 (model_ambiguous) — send a qualified id instead.

Example

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "Hello!" }],
  "max_tokens": 256
}

Response

200 OK — an OpenAI chat.completion:

{
  "id": "chatcmpl-req_01J8…",
  "object": "chat.completion",
  "created": 1752931200,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "Hi there!" },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": { "prompt_tokens": 8, "completion_tokens": 3, "total_tokens": 11 }
}

model echoes the string you sent (never the internal provider/model). A tool-only turn carries content: null and a tool_calls array. usage may include prompt_tokens_details.cached_tokens and completion_tokens_details.reasoning_tokens. The gateway request id is available both as the X-Request-Id response header and inside the completion id (chatcmpl-<request_id>).

Streaming

With stream: true, the response is text/event-stream — a sequence of chat.completion.chunk frames terminated by data: [DONE]:

data: {"id":"chatcmpl-req_01J8…","object":"chat.completion.chunk","created":1752931200,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-req_01J8…","object":"chat.completion.chunk","created":1752931200,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"Hi"},"finish_reason":null}]}

data: {"id":"chatcmpl-req_01J8…","object":"chat.completion.chunk","created":1752931200,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

The first chunk is role-only; content and tool-call deltas map 1:1; the terminal chunk carries finish_reason with an empty delta. When stream_options.include_usage is set, a final chunk with choices: [] and a usage block precedes [DONE]. A mid-stream failure is delivered as a data: { "error": … } frame with no [DONE].

Idempotency

Send Idempotency-Key: <unique-id> on a non-streaming request; a retry with the same key and body replays the stored response without re-executing or re-metering (the OpenAI SDKs set this automatically).

Errors

Errors use the OpenAI envelope, which the OpenAI SDKs deserialize into their typed error classes:

{ "error": { "message": "…", "type": "invalid_request_error", "param": "model", "code": "model_not_found" } }

The Roadie error taxonomy is mapped onto OpenAI’s type/code while keeping the HTTP status the SDK uses to pick its error class:

Roadie type	HTTP	OpenAI `type`
`authentication_error`	401	`invalid_request_error` (`code: invalid_api_key`)
`permission_error`	403	`invalid_request_error`
`not_found_error`	404	`invalid_request_error`
`invalid_request_error` / `idempotency_error`	400 / 409	`invalid_request_error`
`rate_limit_error`	429	`rate_limit_error`
`quota_error` / `budget_error`	429	`insufficient_quota` (`code: insufficient_quota`)
`provider_error` / `internal_error`	5xx	`api_error`

Rate-limit, quota, and budget responses carry a Retry-After header.

Introduction

Data plane

OpenAI-compatible

Control plane

Errors

Chat completions (OpenAI-compatible)

Authentication

Request body

Model resolution

Example

Response

Streaming

Idempotency

Errors

​Authentication

​Request body

​Model resolution

​Example

​Response

​Streaming

​Idempotency

​Errors

Authentication

Request body

Model resolution

Example

Response

Streaming

Idempotency

Errors