Protocol · Claude Messages

Claude Messages API with RouterLab

Connect your application to POST /v1/messages using a RouterLab key. Claude Messages is the protocol; select a compatible model separately from the catalog, then check your access with GET /v1/models. A public model page does not guarantee account access.

Request contractready
Base URL
https://api.routerlab.ch
Endpoint
POST /v1/messages
Authentication
x-api-key: $ROUTERLAB_API_KEY · anthropic-version: 2023-06-01
Model IDs
GET /v1/models

Get started in four steps

Use this route only for models whose catalog entry carries the Claude Messages badge.

  1. 01

    Create a key

    Generate a RouterLab key and keep it in a server-side environment variable.

  2. 02

    Check the route

    In the catalog, choose a model explicitly compatible with Claude Messages.

  3. 03

    Build the message

    Send model, max_tokens and messages using the Messages format.

  4. 04

    Handle the response

    Read the content blocks and usage information returned by the route.

Examples ready to adapt

These examples use anthropic-version: 2023-06-01, the contract currently published by RouterLab. Install the Anthropic Python SDK 1.x (anthropic>=1,<2): major version 2 defaults to API version 2026-10-21, which is newer than this contract. Set ROUTERLAB_API_KEY in your server environment; the Messages SDK base URL does not include /v1.

Python SDK 1.x shell

python -m pip install "anthropic>=1,<2"

Python · Anthropic SDK 1.x python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ROUTERLAB_API_KEY"],
    base_url="https://api.routerlab.ch",
    max_retries=0,
)

message = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=128,
    messages=[{"role": "user", "content": "Hello RouterLab"}],
)

text = "".join(block.text for block in message.content if block.type == "text")
print(text)
print("input_tokens:", message.usage.input_tokens)
print("output_tokens:", message.usage.output_tokens)

cURL shell

curl https://api.routerlab.ch/v1/messages \
  -H "x-api-key: $ROUTERLAB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":128,"messages":[{"role":"user","content":"Hello RouterLab"}]}'

TypeScript · fetch typescript

const response = await fetch("https://api.routerlab.ch/v1/messages", {
  method: "POST",
  headers: {
    "x-api-key": process.env.ROUTERLAB_API_KEY!,
    "anthropic-version": "2023-06-01",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "claude-sonnet-5-5",
    max_tokens: 512,
    messages: [{ role: "user", content: "Hello" }],
  }),
});

if (!response.ok) throw new Error("HTTP " + response.status);
const data = await response.json();
const text = data.content.filter((block: { type: string }) => block.type === "text")
  .map((block: { text: string }) => block.text).join("");
console.log(text, data.usage);

Python · requests python

import os
import requests

response = requests.post(
    "https://api.routerlab.ch/v1/messages",
    headers={"x-api-key": os.environ["ROUTERLAB_API_KEY"], "anthropic-version": "2023-06-01"},
    json={
        "model": "claude-sonnet-5-5",
        "max_tokens": 512,
        "messages": [{"role": "user", "content": "Hello"}],
    },
)
response.raise_for_status()
print(response.json())

From your first call to your application

Start with a short request, check its response and usage, then add only the features published for the selected model.

Choose an accessible model

GET /v1/models with your RouterLab key lists the IDs available to your account. A public model page does not guarantee access on your plan. The trial is limited to models marked Trial.

Keep the protocol consistent

POST /v1/messages uses x-api-key, anthropic-version and max_tokens. Do not just change the path of a chat/completions request: response blocks and tools have a different format.

Tools and structured outputs

Check the model badges before adding tools or an output format. Your application executes tools and validates returned data. Support depends on the model and route.

Check completion and budget

Streaming requires the Streaming badge. An interrupted connection does not prove the call completed. On 429, distinguish a rate limit from an exhausted budget; do not automatically repeat a generation that already returned partial output.

Stream with the example model shell

curl -N https://api.routerlab.ch/v1/messages \
  -H "x-api-key: $ROUTERLAB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5-5","max_tokens":128,"messages":[{"role":"user","content":"Hello RouterLab"}],"stream":true}'

Illustrative response

Structure example without a real call: text and counts are fictional. Responses can contain multiple blocks; extract only text blocks and read usage.input_tokens and usage.output_tokens. A tool_use block requires execution by your application and a tool_result reply; it is not display text.

HTTP 200 · application/json json

{
  "id": "msg_example",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5-5",
  "content": [
    {
      "type": "text",
      "text": "Hello! How can I help?"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 8,
    "output_tokens": 12
  }
}

What this route represents

Claude Messages is an exchange format. The model remains a separate choice controlled by its identifier and capabilities.

Messages format

The request uses messages, max_tokens and the content blocks expected by this protocol.

Declared route

Only use models showing the Claude Messages badge in the catalog.

Variable capabilities

Tools, vision, context and reasoning depend on the selected model.

Another protocol is available

If your SDK expects chat/completions, use the OpenAI-compatible guide.

Claude Code uses ScioNos

For the Claude Code tool, use the ScioNos wrapper: it configures the terminal and authentication. This page documents the direct HTTP API.

Common errors

First check the Messages format and the model route compatibility.

HTTPLikely causeAction
400A required field is missing or content is malformed.Check model, max_tokens and messages in particular.
401Missing, invalid or revoked key.Check x-api-key and anthropic-version as shown in this page’s examples.
404Unknown or unavailable model.Choose an identifier exposed by GET /v1/models.
429Rate or credit limit reached.Reduce request rate and review the RouterLab account.
503Route temporarily unavailable.Retry with backoff or select another compatible route.

Official references

Anthropic documentation describes the protocol and SDK. RouterLab capabilities remain those published for the route and model; Messages compatibility does not guarantee beta, batch, files APIs or hosted tools.

Need Claude Code or Codex CLI?

ScioNos is the dedicated integration for terminal coding agents. It avoids rebuilding their configuration by hand.

Configure agents with ScioNos

Audience measurement

Allow Google Analytics and RouterLab to measure public visits and link campaign sources to your signup? This is optional and can be changed at any time. If you decline, only anonymous visit totals are kept.