Authentication

API Keys

Create keys under API keys. The full key is shown once, when you create it; Railwail stores only a hash, so copy it right away. There is one kind of key: every request is real and billed (there are no test keys). For testing, use a separate key with narrow scopes, a low max_tokens and a monthly cap under Spend limits.

Store the key

All examples in these docs read RAILWAIL_API_KEY from the environment:

export RAILWAIL_API_KEY="rw_live_..."

$env:RAILWAIL_API_KEY = "rw_live_..."

RAILWAIL_API_KEY=rw_live_...

Test your key (free)

curl -s "https://railwail.com/api/v1/models?limit=1" \
  -H "Authorization: Bearer $RAILWAIL_API_KEY"

Scopes

A key only reaches the routes of its scopes. New keys get read and chat: for images, video, audio or embeddings tick those scopes (or all) when you create the key, otherwise the answer is 403 insufficient_scope with the message "This API key lacks the 'images' scope". Scopes cannot be changed on an existing key.

IP allowlist

• Optional, up to 50 entries: single IPv4 or IPv6 addresses or CIDR blocks (203.0.113.7, 198.51.100.0/24, 2001:db8::/48).
• An empty list allows every address. A key with a list refuses everything else, and also a request whose address cannot be determined.
• The address checked is the one your request comes from as Cloudflare sees it. If your server connects over IPv6, list its IPv6 address or range too; the 403 ip_not_allowed message tells you which address arrived.

Rate limit, credit limits and expiry

Using the SDK

Pass the key when you create the client of the railwail npm SDK; it sends it with every request.

import railwail from "railwail";

// Recommended: read the key from the environment (the SDK does not do it for you).
const rw = railwail(process.env.RAILWAIL_API_KEY!);

import railwail from "railwail";

// With options: a longer timeout for long answers (default 120 s).
const rw = railwail(process.env.RAILWAIL_API_KEY!, { timeout: 300_000 });

Using the REST API

For direct HTTP requests, send the key as a Bearer token in the Authorization header:

curl https://railwail.com/api/v1/chat/completions \
  -H "Authorization: Bearer $RAILWAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "max_tokens": 300, "messages": [{"role": "user", "content": "Hello!"}]}'

import os
import requests

response = requests.post(
    "https://railwail.com/api/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['RAILWAIL_API_KEY']}"},
    json={
        "model": "gpt-4o-mini",
        "max_tokens": 300,
        "messages": [{"role": "user", "content": "Hello!"}],
    },
    timeout=120,
)
print(response.json())

const response = await fetch("https://railwail.com/api/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RAILWAIL_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "gpt-4o-mini",
    max_tokens: 300,
    messages: [{ role: "user", content: "Hello!" }],
  }),
});

const data = await response.json();
console.log(data.choices?.[0]?.message.content ?? data.error);

With the OpenAI SDK

The chat, image and audio endpoints follow OpenAI's API, so the official SDKs work with the Railwail base URL and key. What works and what does not

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["RAILWAIL_API_KEY"],
    base_url="https://railwail.com/api/v1",
)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.RAILWAIL_API_KEY,
  baseURL: "https://railwail.com/api/v1",
});

Without a key

Two things work without any key and cost nothing:

• The model catalog: GET https://railwail.com/api/v1/models and /models/{slug} (with a key they need read and count toward its limit). Models API
• The read-only tools of the MCP server at https://railwail.com/api/mcp (catalog, prices, docs; 30 requests per minute per IP). MCP server