curl / REST quickstart

Roadie is a plain HTTPS API. Any language or tool that can make a request can use it. The data plane lives at /v1; the TypeScript equivalents of these calls are executed in CI (see documentation/docs/snippets/rest/).

Already speak the OpenAI wire format? A parallel OpenAI-compatible surface serves POST /openai/v1/chat/completions (and embeddings, models, images) at /openai/v1. This page documents Roadie’s native contract.

Authenticate every data-plane call with a secret key in the Authorization header:

Authorization: Bearer rd_sk_prod_…

Non-streaming chat

curl https://gateway.roadie.paroaria.ai/v1/chat \
  -H "Authorization: Bearer $ROADIE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{ "role": "user", "content": "Hello from raw HTTP." }]
  }'

Response (normalized — plan §21.2):

{
  "id": "req_01J8…",
  "model": "openai/gpt-4o",
  "provider": "openai",
  "message": { "role": "assistant", "content": [{ "type": "text", "text": "Hi!" }], "tool_calls": [] },
  "finish_reason": "stop",
  "usage": { "input_tokens": 12, "output_tokens": 6, "total_tokens": 18, "source": "provider" },
  "cost": { "estimated_usd": 0.00012 },
  "gateway": { "fallback_used": false, "retries": 0, "latency_ms": 412 }
}

The same call with fetch (Node 18+, Deno, Bun, browsers via a server proxy):

snippets/rest/chat.ts

export async function rawChat(): Promise<{ text: string; status: number }> {
  const response = await fetch(`${gatewayBaseUrl()}/v1/chat`, {
    method: 'POST',
    headers: {
      authorization: `Bearer ${apiKey()}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      model: 'openai/gpt-4o',
      messages: [{ role: 'user', content: 'Hello from raw HTTP.' }],
    }),
  });

  if (!response.ok) {
    const envelope = (await response.json()) as { error: { type: string; message: string } };
    throw new Error(`${response.status} ${envelope.error.type}: ${envelope.error.message}`);
  }

  const body = (await response.json()) as {
    message: { content: { text: string }[] };
  };
  const text = body.message.content.map((part) => part.text).join('');
  return { text, status: response.status };
}

(gatewayBaseUrl() and apiKey() are the tiny helpers at the top of snippets/rest/chat.ts that read ROADIE_BASE_URL / ROADIE_KEY.)

Streaming (SSE)

Add "stream": true and read Server-Sent Events. Each data: line is one JSON frame tagged with a type; the terminal sentinel is data: [DONE]. Lines beginning with : are heartbeat comments — ignore them.

curl -N https://gateway.roadie.paroaria.ai/v1/chat \
  -H "Authorization: Bearer $ROADIE_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{ "role": "user", "content": "Stream over raw SSE, please." }],
    "stream": true
  }'

A trimmed stream:

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

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

data: {"type":"content_delta","index":0,"delta":" there!"}

data: {"type":"message_end","finish_reason":"stop","usage":{"input_tokens":12,"output_tokens":6,"total_tokens":18,"source":"provider"},"cost":{"estimated_usd":0.00012}}

data: [DONE]

Parsing the stream by hand with fetch:

snippets/rest/chat.ts

export async function rawChatStream(): Promise<{ text: string; done: boolean }> {
  const response = await fetch(`${gatewayBaseUrl()}/v1/chat`, {
    method: 'POST',
    headers: {
      authorization: `Bearer ${apiKey()}`,
      'content-type': 'application/json',
      accept: 'text/event-stream',
    },
    body: JSON.stringify({
      model: 'openai/gpt-4o',
      messages: [{ role: 'user', content: 'Stream over raw SSE, please.' }],
      stream: true,
    }),
  });

  if (response.body === null) {
    throw new Error('response has no body');
  }

  const reader = response.body.getReader();
  const decoder = new TextDecoder();
  let buffer = '';
  let text = '';
  let done = false;

  for (;;) {
    const chunk = await reader.read();
    if (chunk.done) {
      break;
    }
    buffer += decoder.decode(chunk.value, { stream: true });
    let newline: number;
    while ((newline = buffer.indexOf('\n')) !== -1) {
      const line = buffer.slice(0, newline).replace(/\r$/, '');
      buffer = buffer.slice(newline + 1);
      if (!line.startsWith('data: ')) {
        continue; // Skip SSE comments (`:` heartbeats) and blank separators.
      }
      const data = line.slice('data: '.length);
      if (data === '[DONE]') {
        done = true;
        continue;
      }
      const frame = JSON.parse(data) as { type: string; delta?: string };
      if (frame.type === 'content_delta' && frame.delta !== undefined) {
        text += frame.delta;
      }
    }
  }

  return { text, done };
}

Accept: application/x-ndjson negotiates newline-delimited JSON instead of SSE — the same frames, one JSON object per line, no data: prefix and no [DONE] sentinel.

Errors

Non-2xx responses use the uniform envelope. See the error reference.

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_key",
    "message": "The provided key is not valid.",
    "param": null,
    "request_id": "req_01J8…",
    "doc_url": null
  }
}

Get started

Core concepts

Guides

SDKs

curl / REST quickstart

Non-streaming chat

Streaming (SSE)

Errors

Next steps

Node quickstart

Error reference

​Non-streaming chat

​Streaming (SSE)

​Errors

​Next steps

Node quickstart

Error reference

Non-streaming chat

Streaming (SSE)

Errors

Next steps