# claude-server API guide (for agents and developers)

claude-server speaks the **Anthropic Messages API**. Requests are served by the Claude Code CLI on a
Claude subscription instead of paid API credits. Point any Anthropic SDK at it and most code works
unchanged. This guide covers what's supported and how to spend as few tokens as possible.

- Base URL: `https://raspberrypi.tail29964a.ts.net`
- This guide: `GET https://raspberrypi.tail29964a.ts.net/v1/guide` (also `/llms.txt`). No key needed.

## Quick start

```bash
export ANTHROPIC_BASE_URL=https://raspberrypi.tail29964a.ts.net
export ANTHROPIC_API_KEY=cs_...        # a claude-server key (ask the owner), not an Anthropic key
```

```python
import anthropic
client = anthropic.Anthropic()          # reads the two env vars above
msg = client.messages.create(
    model="lite", max_tokens=300,
    messages=[{"role": "user", "content": "Summarise: ..."}])
print(msg.content[0].text)
```

```bash
curl https://raspberrypi.tail29964a.ts.net/v1/messages -H "x-api-key: $ANTHROPIC_API_KEY" -H "content-type: application/json" \
  -d '{"model":"lite","max_tokens":200,"messages":[{"role":"user","content":"hi"}]}'
```

Auth is `x-api-key: cs_...` or `Authorization: Bearer cs_...`. The `anthropic-version` and
`anthropic-beta` headers are accepted and ignored.

## Endpoints

| Method | Path | |
|---|---|---|
| POST | `/v1/messages` | Messages API: streaming, tools, images, structured output |
| POST | `/v1/messages/count_tokens` | **estimate** (~3.5 chars/token), not exact |
| GET | `/v1/models`, `/v1/models/{id}` | enabled models |
| GET | `/v1/usage` | your key's requests and tokens, today and last 7 days |
| GET | `/health` | `{"ok":true}`; with a key: concurrency, live sessions, subscription utilisation |
| POST | `/v1/complete` | simpler non-Anthropic JSON API (see README) |
| GET | `/v1/guide`, `/llms.txt` | this document |

## Models: pick the cheapest one that works

| `model` | What runs | Thinking | Use for |
|---|---|---|---|
| `lite` (= `claude-haiku-4-5`) | Haiku 4.5 | **off** | extraction, classification, formatting, short answers. **Cheapest for one-shot tasks.** |
| `haiku`, `claude-haiku-5-5` | newest Haiku | always on (can't be disabled) | better quality at low cost |
| `sonnet`, `claude-sonnet-5-5` | newest Sonnet | always on | harder reasoning and coding |
| `opus`, `claude-opus-5-5` | newest Opus | always on | only when Sonnet isn't enough |

- Full ids pass through unchanged. If one is retired or unknown (e.g. `claude-3-5-sonnet-20241022`), the
  server retries with the newest model of the same family. Old projects keep working.
- The response's `model` field says which model actually answered.
- The 5.5 models always spend output tokens on hidden thinking (a few hundred even for trivial tasks).
  The server adds 4096 tokens of headroom above your `max_tokens` for them so the answer isn't cut off.
  Thinking blocks are only returned if you ask for them with `thinking`.

## Token-efficiency rules

Measured on this server. Tokens per task; "cost" is an index in input-token equivalents (cache write
1.25×, cache read 0.1×, output 5×, which is how API pricing weighs them):

| Workload | `lite` | `haiku` (5.5) | `sonnet` (5.5) |
|---|---|---|---|
| one-sentence answer | 300 in, 39 out · **cost 495** | 367 in, 66 out · 697 | 369 in, 86 out · 799 |
| structured extraction | 910 in, 103 out · **1425** | 798 cache-write, 539 out · 3694 | 800 cache-write, 116 out · 1582 |
| 2-step tool loop | 1786 in, 95 out · 2261 | 794 write + 725 read, 80 out · **1469** | 796 write + 727 read, 78 out · **1462** |
| 3-turn chat | 993 in, 21 out · **1098** | 1218 in, 38 out · 1408 | 1222 in, 39 out · 1417 |

1. **One-shot and short tasks: use `lite`.** It's the only model with thinking off, so output stays
   small. Haiku 5.5 can spend hundreds of thinking tokens even on a tiny extraction.
   **Multi-step tool loops and long prompts: use `haiku` or `sonnet`.** Their prompt cache kicks in at
   under 1k tokens, so each loop step reads the history at 0.1×. Haiku 4.5 (`lite`) only caches prefixes
   of 4096+ tokens, so short loops re-send everything at full price. At low effort Sonnet often thinks
   *less* than Haiku 5.5, so try it before assuming Haiku is cheaper.
2. **Batch small tasks into one request.** Every new conversation carries ~300 tokens of fixed CLI
   context (environment, model, date) that is usually too small to be cached. Ten classifications in one
   prompt cost that once; ten separate requests cost it ten times. Ask for a JSON array of results.
3. **Continue conversations exactly.** Send the assistant's `content` back unchanged, including
   `tool_use` ids, and append only the new user turn. The server then continues the same live session and
   the prompt cache is read instead of rebuilt. Editing, reordering or trimming earlier messages
   (or changing `system`, `tools`, `model`, `thinking` or effort mid-conversation) starts a fresh session
   and replays the history as text.
4. **Keep `system` and `tools` byte-identical across requests.** They're part of the cache prefix and the
   session match. Put variable data (dates, IDs, documents) in the user message, not the system prompt.
5. **Set `max_tokens` close to what you need.** It bounds the visible answer. For the 5.5 models, thinking
   comes on top (see above).
6. **Structured output costs one call.** Use `output_config: {"format": {"type": "json_schema", "schema": …}}`
   or `tool_choice: {"type": "tool", "name": …}`. Both run as a single forced tool call. Don't add
   "respond in JSON" retries.
7. **Leave effort at the default** (`low`). Raise `output_config.effort` only if quality needs it.
8. **Cache repeated identical requests** (test suites, fixtures): send `x-cache-ttl: 3600`. An identical
   request (same key, body and model) within the TTL is answered from memory and uses no subscription
   tokens.
9. **Prompt cache TTL is 5 minutes by default** (cheaper writes). If the same large prefix is reused at
   intervals longer than 5 minutes, mark a block with `"cache_control": {"type": "ephemeral", "ttl": "1h"}`.
   Other `cache_control` markers are ignored: the CLI places its own breakpoints. Prefixes below the
   model's minimum cacheable size (roughly 1–4k tokens) aren't cached at all.
10. **Don't fan out many new conversations in parallel.** The server runs 3 requests at once (others
    queue) and starting a conversation spawns a CLI process (~2–5 s on the Pi). Follow-ups in a live
    session start in under a second.
11. **Stream long outputs** (`stream: true`). You see tokens immediately and can stop early by closing
    the connection.

## Request reference (`POST /v1/messages`)

| Field | Support |
|---|---|
| `model`, `max_tokens` (required), `messages` | ✅ |
| `system`: string or text blocks | ✅ |
| content blocks: `text`, `image` (base64 png/jpeg/gif/webp ≤5 MB, or url), `document` | ✅ Images in *earlier* turns become `[image]` placeholders when history has to be replayed |
| `tools` (client tools: `name`, `description`, `input_schema`) | ✅ Tools run in **your** code |
| `tool_choice`: `auto`, `any`, `none`, `{"type":"tool","name"}`, `disable_parallel_tool_use` | ✅ `any` and `disable_parallel_tool_use` are instructed, not enforced |
| `tool_result` blocks (string or text/image content, `is_error`) | ✅ |
| `stream` | ✅ Real event sequence: `message_start`, `ping`, `content_block_*`, `message_delta`, `message_stop` |
| `stop_sequences` | ✅ `stop_reason: "stop_sequence"` |
| `thinking`: `{"type":"enabled","budget_tokens"}` / `{"type":"adaptive"}` | ✅ Thinking blocks returned only when requested |
| `output_config.effort`: `low`…`max` | ✅ (default `low`) |
| `output_config.format` / `output_format` json_schema | ✅ |
| `temperature`, `top_p`, `top_k`, `metadata`, `service_tier` | accepted, ignored |
| assistant prefill (last message from `assistant`) | ❌ 400 |
| server tools (`web_search`, code execution, …), Files API, Batches | ❌ 400 / not available |

Response: the standard `message` object (`id`, `type`, `role`, `model`, `content`, `stop_reason`,
`stop_sequence`, `usage` with `input_tokens`, `output_tokens`, `cache_creation_input_tokens`,
`cache_read_input_tokens`). `stop_reason` is `end_turn`, `tool_use`, `max_tokens` or `stop_sequence`.

### Tool loop

```python
msgs = [{"role": "user", "content": "Weather in Toronto?"}]
while True:
    r = client.messages.create(model="lite", max_tokens=500, tools=TOOLS, messages=msgs)
    msgs.append({"role": "assistant", "content": r.content})        # unchanged → live session reused
    if r.stop_reason != "tool_use":
        break
    msgs.append({"role": "user", "content": [
        {"type": "tool_result", "tool_use_id": b.id, "content": run_tool(b.name, b.input)}
        for b in r.content if b.type == "tool_use"]})
```

Return results for **all** `tool_use` blocks in the next request. A live session waits 15 minutes for
tool results, and 30 minutes between turns, before it's dropped. After that the conversation still
works but is replayed once.

## Errors

Same shape as the Anthropic API: `{"type":"error","error":{"type":…,"message":…}}`.

| Status | `error.type` | Meaning / what to do |
|---|---|---|
| 400 | `invalid_request_error` | bad request (missing `max_tokens`, prefill, unknown tool in `tool_choice`, server tools) |
| 401 | `authentication_error` | missing or wrong `cs_` key |
| 403 | `permission_error` | model not allowed for this key |
| 413 | `request_too_large` | prompt or image too large |
| 429 | `rate_limit_error` | key limit (per minute / per day) **or** the subscription's usage limit: back off |
| 502/504 | `api_error` | CLI failure or timeout (600 s per response): retry once |
| 529 | `overloaded_error` | server busy (all slots in use): retry with backoff |

The SDKs retry 429/5xx automatically. Errors that happen before streaming starts are returned as real
HTTP errors, not as an SSE `error` event.

## Limits and privacy

- Per-key limits (default 30 requests/min, 1500/day) and the owner's subscription limits apply. Check
  `GET /v1/usage`.
- Reachable only on the owner's Tailscale network. Requests run with **no** tools or file access on the
  server. Your tools run in your code.
