Node quickstart

This is the 10-minute server integration with the first-party @roadie/sdk. Every snippet below is executed in CI against a live gateway; the runnable sources are in documentation/docs/snippets/node/.

Prefer to keep your existing OpenAI code? Point the official OpenAI SDK at Roadie instead — see the OpenAI drop-in quickstart.

1. Prerequisites

In the dashboard:

Create a project (its development and production environments are created for you).
Add and validate a provider credential (your OpenAI or Anthropic key — BYOK). See Providers & BYOK.
Create a secret key (rd_sk_…) for the environment you want to call.

A secret key grants full access to your project’s data plane. Keep it on your server — never ship it in a browser or mobile app. For client apps, use client tokens.

2. Install

pnpm add @roadie/sdk      # or npm install / yarn add

Set your key in the environment:

export ROADIE_KEY="rd_sk_prod_…"

3. Construct the client

Create the client once and reuse it. Provide baseUrl only if you target a specific gateway host (self-hosted or regional); otherwise the default hosted gateway () is used.

snippets/node/client.ts

import { Roadie } from '@roadie/sdk';

export function createClient(): Roadie {
  return new Roadie({
    apiKey: requireEnv('ROADIE_KEY'),
    // Point the SDK at a specific gateway host (self-hosted, regional, or — in
    // tests — a local stack). Omit `baseUrl` to use the default hosted gateway.
    ...(process.env.ROADIE_BASE_URL !== undefined && {
      baseUrl: process.env.ROADIE_BASE_URL,
    }),
  });
}

function requireEnv(name: string): string {
  const value = process.env[name];
  if (value === undefined || value === '') {
    throw new Error(`Missing required environment variable: ${name}`);
  }
  return value;
}

4. Send a chat completion

roadie.chat.create returns the normalized response: the assistant message, finish_reason, token usage, an estimated cost, and the gateway requestId.

snippets/node/chat.ts

import { createClient } from './client.js';

export async function chatOnce(): Promise<{ text: string; costUsd: number | undefined }> {
  const roadie = createClient();

  const res = await roadie.chat.create({
    model: 'openai/gpt-4o',
    messages: [
      { role: 'system', content: 'You are a concise assistant.' },
      { role: 'user', content: 'In one sentence, what is Roadie?' },
    ],
    // Attribute the call to one of your end users so per-user limits, quotas,
    // and analytics apply. Optional for server-key calls.
    user: { id: 'user_42', plan: 'pro' },
  });

  const text = res.message.content.map((part) => part.text).join('');
  return { text, costUsd: res.cost?.estimated_usd };
}

model accepts an explicit provider/model id (like openai/gpt-4o) or a project alias you configure (like smart) that fails over across providers. See Models, aliases & fallback.

5. Stream the response

Iterate the async-iterable stream with for await. content_delta events carry incremental text; the terminal message_end event carries the final usage and cost.

snippets/node/stream.ts

import type { Usage } from '@roadie/sdk';

import { createClient } from './client.js';

export async function streamOnce(): Promise<{ text: string; usage: Usage | undefined }> {
  const roadie = createClient();

  let text = '';
  let usage: Usage | undefined;

  for await (const event of roadie.chat.stream(
    {
      model: 'openai/gpt-4o',
      messages: [{ role: 'user', content: 'Stream a friendly one-line greeting.' }],
    },
    { timeoutMs: 60_000 },
  )) {
    if (event.type === 'content_delta') {
      text += event.delta;
      process.stdout.write(event.delta);
    } else if (event.type === 'message_end') {
      usage = event.usage;
    }
  }

  return { text, usage };
}

Pass an AbortSignal to cancel a stream (or any call); NDJSON framing is available via { framing: 'ndjson' }. See Streaming.

6. Create embeddings

snippets/node/embeddings.ts

import { createClient } from './client.js';

export async function embedDocuments(): Promise<number[][]> {
  const roadie = createClient();

  const res = await roadie.embeddings.create({
    model: 'openai/text-embedding-3-small',
    input: ['The quick brown fox.', 'A second document to embed.'],
  });

  return res.data.map((entry) => entry.embedding);
}

7. Handle typed errors

Every failure is a RoadieError subclass with a stable code, the requestId, the HTTP status, and (for rate limits) retryAfter. Branch on the class.

snippets/node/errors.ts

import {
  AuthenticationError,
  BudgetError,
  isRoadieError,
  QuotaError,
  RateLimitError,
} from '@roadie/sdk';

import { createClient } from './client.js';

/** How you would react to each failure class in production. */
export function classifyError(err: unknown): string {
  if (err instanceof RateLimitError) {
    // Transient: back off and retry after `err.retryAfter` seconds.
    return 'rate_limited';
  }
  if (err instanceof QuotaError) {
    // A usage window is exhausted; surface a "limit reached" state to the user.
    return 'quota_exhausted';
  }
  if (err instanceof BudgetError) {
    // The project/org budget cap was hit (HTTP 402); alert the account owner.
    return 'budget_exceeded';
  }
  if (err instanceof AuthenticationError) {
    // Your ROADIE_KEY is missing, wrong, or revoked.
    return 'bad_key';
  }
  if (isRoadieError(err)) {
    return `${err.type} (${err.code ?? 'unknown'}) request_id=${err.requestId ?? 'n/a'}`;
  }
  return 'unknown';
}

/** Runs a chat completion, returning the text on success or a classification on failure. */
export async function chatWithErrorHandling(): Promise<
  { ok: true; text: string } | { ok: false; kind: string }
> {
  const roadie = createClient();
  try {
    const res = await roadie.chat.create({
      model: 'openai/gpt-4o',
      messages: [{ role: 'user', content: 'Hello!' }],
    });
    return { ok: true, text: res.message.content.map((part) => part.text).join('') };
  } catch (err) {
    return { ok: false, kind: classifyError(err) };
  }
}

The SDK already retries transient failures (network errors, 429, 5xx) before they reach you, honoring Retry-After. See Errors & retries and the full error reference.

Next steps

Next.js quickstart

Wrap the SDK in a server-side route.

OpenAI drop-in

Keep the OpenAI SDK — change only the base URL and key.

Rate limits, quotas & budgets

Cap spend and usage before it happens.

curl / REST quickstart

The raw HTTP contract, SSE streaming included.

Get started

Core concepts

Guides

SDKs

Node quickstart

1. Prerequisites

2. Install

3. Construct the client

4. Send a chat completion

5. Stream the response

6. Create embeddings

7. Handle typed errors

Next steps

Next.js quickstart

OpenAI drop-in

Rate limits, quotas & budgets

curl / REST quickstart

​1. Prerequisites

​2. Install

​3. Construct the client

​4. Send a chat completion

​5. Stream the response

​6. Create embeddings

​7. Handle typed errors

​Next steps

Next.js quickstart

OpenAI drop-in

Rate limits, quotas & budgets

curl / REST quickstart

1. Prerequisites

2. Install

3. Construct the client

4. Send a chat completion

5. Stream the response

6. Create embeddings

7. Handle typed errors

Next steps