Claude Code Integration¶

Doc Version: 1.1.0 Last Updated: 2026-09-14 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 authentication note: /v1/** accepts both X-API-Key (API Key) and Jairouter_Token (JWT). When both are present, JWT takes precedence. JWT must be enabled (jairouter.security.jwt.enabled) and the token must not be expired or revoked. For Claude Code, using ANTHROPIC_API_KEY (i.e. x-api-key) is the simplest approach; if you prefer JWT, make sure the above conditions are met. 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.

Tool use¶

Prerequisite: the downstream (OpenAI / DeepSeek / vLLM / any other OpenAI-compatible service) must support function calling. If it does not, nothing breaks — the gateway still forwards tools, the downstream ignores them and returns plain text, and this endpoint degrades to text chat (content holds only text blocks, stop_reason is end_turn).

Request-side mapping (Anthropic → downstream OpenAI-compatible wire):

Ordering rules:

• within one assistant message: text blocks become content, multiple tool_use blocks become tool_calls in block order (OpenAI structurally puts content first and tool_calls after, so no finer interleaving can be expressed);
• within one user message: tool_result blocks become role:"tool" messages emitted before the text message, so they directly follow the assistant message carrying tool_calls (a hard requirement of OpenAI / DeepSeek).

Non-streaming example¶

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": 512,
    "messages": [{"role": "user", "content": "What is the weather in Beijing today?"}],
    "tools": [{
      "name": "get_weather",
      "description": "Look up the weather of a city",
      "input_schema": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
    }],
    "tool_choice": {"type": "auto"}
  }'

Response (content holds the text block plus each tool_use block in downstream order; stop_reason is tool_use):

{
  "id": "chatcmpl-tool-1",
  "type": "message",
  "role": "assistant",
  "model": "deepseek-chat",
  "content": [
    {"type": "text", "text": "Let me look that up."},
    {"type": "tool_use", "id": "call_0", "name": "get_weather", "input": {"city": "Beijing"}}
  ],
  "stop_reason": "tool_use",
  "stop_sequence": null,
  "usage": {"input_tokens": 88, "output_tokens": 24}
}

After running the tool, the client feeds the result back as a tool_result block inside a user message (Claude Code does this automatically):

{"role": "user", "content": [{"type": "tool_result", "tool_use_id": "call_0", "content": "Sunny, 25C"}]}

Streaming event sequence¶

Tool calls stream as tool_use content blocks whose input arrives as input_json_delta fragments: the text block is always index: 0, tool block indices increment in order of appearance (1, 2, …), and each block's start / delta / stop triple never interleaves with another block.

Real output sample (produced by the actual serializer, 10 events; the model first returned the text "Let me look that up." then streamed get_weather's input {"city":"Beijing"} with arguments arriving in two fragments):

event:message_start
data:{"type":"message_start","message":{"id":"msg_ec73908348944d82b34dfd2ef5516f71","type":"message","role":"assistant","model":"deepseek-chat","content":[],"stop_reason":null,"stop_sequence":null,"usage":{"input_tokens":88,"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":"Let me look that up."}}

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

event:content_block_start
data:{"type":"content_block_start","index":1,"content_block":{"type":"tool_use","id":"call_0","name":"get_weather"}}

event:content_block_delta
data:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"{\"city\":"}}

event:content_block_delta
data:{"type":"content_block_delta","index":1,"delta":{"type":"input_json_delta","partial_json":"\"Beijing\"}"}}

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

event:message_delta
data:{"type":"message_delta","delta":{"stop_reason":"tool_use","stop_sequence":null},"usage":{"output_tokens":24}}

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

stop_reason rules: downstream finish_reason: "tool_calls" → tool_use; a stream that produced tool blocks but ends with stop / no reason is also upgraded to tool_use (Claude Code decides whether to run tools from it); length always stays max_tokens (truncation is more informative). usage.output_tokens semantics are unchanged — downstream usage wins when present, otherwise it is estimated from the accumulated text plus tool arguments fragments.

Tolerance and degradation¶

Claude Code verification¶

# 1) Point at the gateway (the model must be a registered instance/pool whose downstream supports
#    function calling, e.g. deepseek-chat)
export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_API_KEY=<JAiRouter API Key>
export ANTHROPIC_MODEL=deepseek-chat

# 2) Trigger one tool call non-interactively (Claude Code attaches its Read/Bash tool definitions)
claude -p "Use the Bash tool to run pwd and tell me the output verbatim" --allowedTools "Bash"

# 3) Check that it really ran: the answer must contain the command output (e.g. /home/...), not
#    "I cannot execute commands"

Two places to confirm the path end to end:

• gateway logs: the /v1/messages request carries tools, and the downstream request body carries tools / tool_calls (with tracing enabled, the downstream call span carries adapter.api_standard=openai);
• the event stream (curl -N, or Claude Code --verbose): a content_block_start with "type":"tool_use" and a message_delta with "stop_reason":"tool_use".

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