> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# Using BeatAPI in Claude Code

> Configure Claude Code to send its requests to BeatAPI, so one key reaches every Claude model on the account.

# Using BeatAPI in Claude Code

Claude Code is a command-line coding agent that reads and writes files, runs commands, and works through a task in the terminal. It speaks the Anthropic Messages format, which BeatAPI serves directly at `POST /v1/messages` — so pointing it at BeatAPI is a base-URL change, not a translation layer.

## Prerequisites

1. **Claude Code installed** — see Step 1 if you have not installed it yet.
2. **A BeatAPI API key** — create one in [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys).

## Step 1: Install Claude Code

#### macOS / Linux

Install with the official script:

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Or with Homebrew:

```bash
brew install --cask claude-code
```

#### Windows

PowerShell:

```powershell
irm https://claude.ai/install.ps1 | iex
```

CMD:

```cmd
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```

#### npm

With Node.js 18 or newer, on any operating system:

```bash
npm install -g @anthropic-ai/claude-code
```

Confirm the install:

```bash
claude --version
```

## Step 2: Point Claude Code at BeatAPI

Three configuration methods, in descending order of durability. Pick one.

### Method 1: settings.json

The most stable approach — configure once and it persists across terminals.

Locate the configuration directory:

* macOS / Linux: `~/.claude`
* Windows: `%userprofile%\.claude`

If it does not exist, run `claude` once and press `Ctrl + C` to exit; the directory is created for you.

Create or edit `settings.json`:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.beatapi.io",
    "ANTHROPIC_AUTH_TOKEN": "<BEATAPI_API_KEY>",
    "ANTHROPIC_MODEL": "claude-fable-5-1",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
  }
}
```

| Variable                                   | Value                                                                         |
| ------------------------------------------ | ----------------------------------------------------------------------------- |
| `ANTHROPIC_BASE_URL`                       | `https://api.beatapi.io` — no `/v1` suffix; the client appends `/v1/messages` |
| `ANTHROPIC_AUTH_TOKEN`                     | Your BeatAPI API key                                                          |
| `ANTHROPIC_MODEL`                          | A model ID from the table below                                               |
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | `1` reduces background requests                                               |

Save the file and restart Claude Code.

### Method 2: Persistent environment variables

#### macOS (zsh)

```bash
echo 'export ANTHROPIC_BASE_URL="https://api.beatapi.io"' >> ~/.zshrc
echo 'export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"' >> ~/.zshrc
echo 'export ANTHROPIC_MODEL="claude-fable-5-1"' >> ~/.zshrc
source ~/.zshrc
```

#### Linux (bash)

```bash
echo 'export ANTHROPIC_BASE_URL="https://api.beatapi.io"' >> ~/.bashrc
echo 'export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"' >> ~/.bashrc
echo 'export ANTHROPIC_MODEL="claude-fable-5-1"' >> ~/.bashrc
source ~/.bashrc
```

#### Windows (PowerShell)

```powershell
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_BASE_URL', 'https://api.beatapi.io', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_AUTH_TOKEN', '<BEATAPI_API_KEY>', 'User')
[System.Environment]::SetEnvironmentVariable('ANTHROPIC_MODEL', 'claude-fable-5-1', 'User')
```

Restart the terminal afterwards.

### Method 3: One terminal only

Useful for a quick test. The values disappear when the terminal closes.

```bash
export ANTHROPIC_BASE_URL="https://api.beatapi.io"
export ANTHROPIC_AUTH_TOKEN="<BEATAPI_API_KEY>"
export ANTHROPIC_MODEL="claude-fable-5-1"
claude
```

## Step 3: Verify and start working

```bash
claude "Hello"
```

A reply means the configuration took effect. A login prompt, a `401`, or a `403` means it did not — see the FAQ below.

Claude Code has two interaction modes:

* **Interactive** — run `claude` for a continuing session, suited to multi-step work.
* **One-shot** — run `claude "your question"` for a single answer.

## Models

Every Claude model on the account is reachable with the same key. Switch with `/model` inside an interactive session, or change `ANTHROPIC_MODEL` and restart.

| Model ID                    | Choose it for                                                     |
| --------------------------- | ----------------------------------------------------------------- |
| `claude-fable-5-1`          | The newest generation — the default for agentic coding            |
| `claude-opus-5`             | The heaviest reasoning tier, for hard architecture and debugging  |
| `claude-sonnet-5-5`         | Coding and agent workflows, with 1M context and up to 128K output |
| `claude-sonnet-5`           | Balanced capability and speed for day-to-day work                 |
| `claude-haiku-4-5-20251001` | Fastest and cheapest, for quick edits and high-volume steps       |

Prices for each are on the [pricing page](https://beatapi.io/pricing); the [Claude API](/text-api/claude/messages) page documents the request shape.

### Configure Sonnet 5.5

Merge these values into `~/.claude/settings.json`, replace the key placeholder, then restart Claude Code:

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.beatapi.io",
    "ANTHROPIC_AUTH_TOKEN": "<BEATAPI_API_KEY>",
    "ANTHROPIC_MODEL": "claude-sonnet-5-5"
  }
}
```

Sonnet 5.5 uses adaptive thinking by default. Let Claude Code manage its thinking and tool settings. See the [Sonnet 5.5 model guide](/text-api/claude/messages) for limits and current token rates.

## Common commands

| Command             | Description                   |
| ------------------- | ----------------------------- |
| `claude`            | Enter interactive mode        |
| `claude "question"` | Single query                  |
| `claude --version`  | Show the version              |
| `/model`            | Switch model inside a session |
| `/help`             | Show help                     |
| `Ctrl + C`          | Exit interactive mode         |

## FAQ

### The login screen still appears after configuring

The configuration did not take effect.

1. Using `settings.json` — check the path is `~/.claude/settings.json` (`%userprofile%\.claude\settings.json` on Windows).
2. Using environment variables — make sure you launched Claude Code from the terminal where the variables were set.
3. Check the JSON is valid: matching braces, no trailing comma, straight quotes rather than typographic ones.

### 401 or 403

| Status | Meaning                                                                                            | What to do                                                                                |
| ------ | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `401`  | `missing_api_key` or `invalid_api_key`: the key is missing, wrong, expired, disabled, or exhausted | Confirm the key is active in [Dashboard → API Keys](https://beatapi.io/dashboard/apikeys) |
| `403`  | `forbidden`: the key or account cannot use this model, for example on free credit                  | Check account status and the requested model                                              |

Also confirm `ANTHROPIC_BASE_URL` is `https://api.beatapi.io` and not the vendor's own address.

### "Auth conflict" on startup

```
Auth conflict: Both a token (claude.ai) and an API key (ANTHROPIC_API_KEY) are set.
```

You are signed in to a first-party account and have an API key set at the same time. Run `/logout` inside Claude Code to drop the session and keep the key.

### 402 insufficient_credits

Insufficient balance: the account balance is zero or below the price of the request. Top up from the dashboard; in-flight requests fail rather than queue.

### 429 rate_limit_exceeded

The key exceeded its request rate. BeatAPI returns `Retry-After` — wait that long before retrying. The per-minute allowance rises with lifetime top-ups and is shown on the dashboard.

### Connection failures

1. Check general connectivity.
2. Re-check `ANTHROPIC_BASE_URL` for a typo or a stray `/v1`.
3. Behind a corporate proxy, allow `api.beatapi.io`.

### Checking usage and spend

The dashboard shows calls, token consumption, and cost per key. The same numbers are available programmatically from [`GET /v1/usage`](/quick-guide).

## Support

Open a support ticket from the [dashboard](https://beatapi.io/dashboard) and include the `request_id` from the failing response — it identifies the exact call in the logs.