Claude Code Integration¶

Doc Version: 1.0.0 Last Updated: 2026-09-13 Applies To: v3.1+ Git Commit: - Author: Lincoln

Overview¶

Since v3.1, JAiRouter exposes an Anthropic Messages protocol endpoint (POST /v1/messages). Claude Code only needs ANTHROPIC_BASE_URL pointed at JAiRouter to connect with zero code changes: the request goes through API Key authentication → quota → rate limiting / circuit breaking → load balancing to any downstream instance (OpenAI / DeepSeek / vLLM / Ollama / Claude …), and the response is translated back into Anthropic shape.

In one sentence: /api/v1/** (console surface) returns RouterResponse envelopes; /v1/** (native surface) returns downstream-native / protocol-native shapes so that clients such as Claude Code and the OpenAI SDK can use JAiRouter directly.

Prerequisites¶

1. JAiRouter is running (default http://localhost:8080).
2. An API Key has been created in the console (it authenticates both /api/** and /v1/**).
3. The target model is registered as an instance or pool (service type chat), e.g. deepseek-chat or qwen2:7b.
4. Downstream credentials are configured (recommended: in the instance headers, see "Authentication Layers").

Quick Start¶

# 1) Gateway URL: ANTHROPIC_BASE_URL=http://<host>:8080 (no /v1 suffix; replace <host> with the gateway host/IP)
export ANTHROPIC_BASE_URL=http://localhost:8080

# 2) Gateway credential (API Key created in the JAiRouter console)
export ANTHROPIC_API_KEY=<JAiRouter API Key>

# 3) A model name registered in JAiRouter (must match the instance/pool name exactly; no aliases)
export ANTHROPIC_MODEL=deepseek-chat

# 4) Start Claude Code
claude

PowerShell:

$env:ANTHROPIC_BASE_URL = "http://localhost:8080"
$env:ANTHROPIC_API_KEY  = "<JAiRouter API Key>"
$env:ANTHROPIC_MODEL    = "deepseek-chat"
claude

Claude Code sends ANTHROPIC_API_KEY in the x-api-key request header. HTTP header names are case-insensitive, so x-api-key and X-API-Key are equivalent (both verified against the gateway).

Important: inside JAiRouter, x-api-key is a gateway credential. It is consumed by the security layer and never forwarded downstream. Downstream AI service keys must be configured separately — see the next section.

Authentication Layers (read this first)¶

A single /v1/messages request passes through two authentication layers with completely different purposes:

Three rules to remember:

1. x-api-key = gateway credential, not forwarded downstream. If you put a downstream key in x-api-key, the downstream receives a request with no credentials → 401 / unauthenticated failure.
2. Configure the downstream key in instance headers (recommended), or send it per request via Authorization: Bearer <downstream key>. When both are present, instance headers win (instance configuration overrides the incoming Authorization).
3. Credential precedence: Jairouter_Token (JWT) > X-API-Key (API Key). Authorization is unrelated to gateway authentication; it only affects the downstream.

Native-surface limitation (current version): the service call path behind /v1/** only accepts API Key authentication (ApiKeyAuthentication). A native-surface request carrying only Jairouter_Token (no x-api-key) gets an empty response and cannot reach any downstream. For Claude Code, always use ANTHROPIC_API_KEY (i.e. x-api-key). The console surface /api/** is not affected.

Three Ways to Configure Downstream Credentials¶

Option A: downstream key in instance headers (recommended)¶

# DeepSeek example: the downstream key lives in the instance headers (injected by the gateway)
curl -X POST "http://localhost:8080/api/config/instance/add/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <JAiRouter API Key>" \
  -d '{
    "name": "deepseek-chat",
    "baseUrl": "https://api.deepseek.com",
    "path": "/v1/chat/completions",
    "adapter": "normal",
    "headers": {
      "Authorization": "Bearer <DeepSeek API Key>"
    }
  }'

Claude Code then only needs ANTHROPIC_API_KEY=<JAiRouter API Key>; the client neither stores nor sends the downstream key.

Option B: send the downstream key per request (pass-through Authorization)¶

Leave the instance config untouched and let the client carry the downstream key:

curl -N -X POST "http://localhost:8080/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <JAiRouter API Key>" \
  -H "Authorization: Bearer <DeepSeek API Key>" \
  -d '{"model":"deepseek-chat","max_tokens":64,"messages":[{"role":"user","content":"hi"}]}'

If the instance already defines Authorization, the instance configuration wins (the request header is overridden).

Option C: custom downstream header¶

curl -X POST "http://localhost:8080/api/config/instance/add/chat" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <JAiRouter API Key>" \
  -d '{
    "name": "claude-sonnet",
    "baseUrl": "https://api.anthropic.com",
    "path": "/v1/messages",
    "adapter": "claude",
    "headers": {
      "x-api-key": "<Anthropic API Key>"
    }
  }'

Note: this x-api-key lives in the instance headers and targets the downstream Anthropic API. It is unrelated to the x-api-key the client sends to the gateway. With the claude adapter, the anthropic-version header is injected automatically.

Endpoint Examples¶

All examples use x-api-key: <JAiRouter API Key> as the gateway credential.

Non-streaming messages¶

curl -X POST "http://localhost:8080/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <JAiRouter API Key>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "deepseek-chat",
    "max_tokens": 128,
    "system": "You are a concise assistant",
    "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}]
  }'

Response (Anthropic Message shape):

{
  "id": "chatcmpl-xxxxxxxx",
  "type": "message",
  "role": "assistant",
  "model": "deepseek-chat",
  "content": [{"type": "text", "text": "I am an AI assistant ..."}],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {"input_tokens": 10, "output_tokens": 15}
}

usage.input_tokens / output_tokens come from the downstream usage; they are 0 when the downstream does not provide it.

Streaming messages¶

curl -N -X POST "http://localhost:8080/v1/messages" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <JAiRouter API Key>" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "deepseek-chat",
    "max_tokens": 128,
    "stream": true,
    "messages": [{"role": "user", "content": "Count to three"}]
  }'

Content-Type: text/event-stream;charset=UTF-8. The event sequence (each event = an event:<name> line + a data:<json> line + a blank line; the SSE spec allows one space after the colon, the gateway emits none, and clients accept both):

Real output sample (produced by the actual serializer, 7 events; the model returned "1" then "、2、3"):

event:message_start
data:{"type":"message_start","message":{"id":"msg_4976714626ba4577a486e0772f604a87","type":"message","role":"assistant","model":"deepseek-chat","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":6,"output_tokens":0}}}

event:content_block_start
data:{"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event:content_block_delta
data:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"1"}}

event:content_block_delta
data:{"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"、2、3"}}

event:content_block_stop
data:{"type":"content_block_stop","index":0}

event:message_delta
data:{"type":"message_delta","delta":{"stop_reason":"end_turn","stop_sequence":null},"usage":{"output_tokens":2}}

event:message_stop
data:{"type":"message_stop"}

When the downstream fails mid-stream (HTTP 200 already established, SSE already started) the gateway closes with event:error so the client does not just see a truncated stream:

event:error
data:{"type":"error","error":{"type":"api_error","message":"…"}}

error.type is mapped from the downstream status: 401/403 → authentication_error, 429 → rate_limit_error, 400/404/422 → invalid_request_error, otherwise api_error.

Token counting¶

curl -X POST "http://localhost:8080/v1/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <JAiRouter API Key>" \
  -d '{
    "model": "deepseek-chat",
    "system": "You are a concise assistant",
    "messages": [{"role": "user", "content": "Introduce yourself in one sentence"}]
  }'

{"input_tokens": 10}

• The body is the same as /v1/messages, but max_tokens / stream / tools are ignored: only the text blocks in system and messages are counted.
• The value is estimated locally by the gateway (ideographic characters ≈ 2 chars/token, other non-whitespace ≈ 4 chars/token). No downstream call, no quota consumption, and it is the same estimator used for the streaming message_start.usage.input_tokens.
• The estimate is for budgeting/trimming; it is not the official Anthropic tokenizer output.

Model catalog¶

curl -H "x-api-key: <JAiRouter API Key>" "http://localhost:8080/v1/models"

Returns the OpenAI shape {"object":"list","data":[{"id":"deepseek-chat","object":"model",…}]}; each id can be used as the model field.

Current Limitations¶

Troubleshooting¶

Related Documentation¶

• Quick Start — start the gateway, configure your first instance
• API Key Management — create and rotate gateway credentials
• Instance Configuration Examples — downstream templates (including the Claude adapter)
• Universal API — console surface /api/v1/**
• Error Codes — gateway error codes