Using BeatAPI in Codex CLI

Codex CLI is a terminal coding agent that reads and writes files, runs commands, and works through a task end to end. It talks to a provider over the OpenAI Responses format, which BeatAPI serves at POST /v1/responses — so BeatAPI is added as a provider rather than proxied.

Prerequisites

1. Node.js installed — the LTS release, v20 or newer.
2. A BeatAPI API key — create one in Dashboard → API Keys.

Step 1: Install Codex CLI

$
npm install -g @openai/codex

Confirm the install:

$
codex --version

Step 2: Add BeatAPI as a provider

Codex CLI keeps provider configuration under ~/.codex/ (C:\Users\<you>\.codex\ on Windows). If the directory does not exist, run codex once and press Ctrl + C; it is created for you.

2.1 The key

Create or edit ~/.codex/auth.json:

1
{
2
  "OPENAI_API_KEY": "<BEATAPI_API_KEY>"
3
}

2.2 The provider

Create or edit ~/.codex/config.toml:

1
# Default model
2
model = "gpt-5.6-sol"
3
# Default provider — must match the id in [model_providers.<id>] below
4
model_provider = "beatapi"
5
6
[model_providers.beatapi]
7
name = "BeatAPI"
8
base_url = "https://api.beatapi.io/v1"
9
wire_api = "responses"
10
requires_openai_auth = true

Restart Codex CLI after saving both files.

Alternative: use an environment variable instead of auth.json

1
[model_providers.beatapi]
2
name = "BeatAPI"
3
base_url = "https://api.beatapi.io/v1"
4
wire_api = "responses"
5
env_key = "BEATAPI_API_KEY"

Then export BEATAPI_API_KEY in your shell profile. auth.json is no longer needed. This keeps the key out of a file that is easy to commit by accident.

Step 3: Verify and start working

$
codex "Introduce yourself in one sentence"

A reply means it is wired up. A sign-in screen, a 401, or a 403 means it is not — see the FAQ.

Run codex on its own for the interactive UI, then describe the task in plain language:

Create an Express.js server with a JSON health check endpoint

Codex analyses the project, writes code, and runs commands, asking before anything sensitive.

Approval modes

Start with Auto. Change it any time with /approvals.

Models

Switch with /model in the interactive UI, or change model in config.toml and restart.

Any text model on the account answers on /v1/responses, so the list is not limited to the ones above — see the Text API. Rates are on the pricing page.

Common commands

FAQ

A sign-in screen appears on launch

The configuration is not being read.

1. Both files must be in ~/.codex/ — not in the project directory.
2. model_provider must exactly match the id in [model_providers.<id>].
3. auth.json must be valid JSON and config.toml valid TOML. Typographic quotes are the usual culprit; use straight quotes.

401 or 403

Also confirm base_url is https://api.beatapi.io/v1 and not a vendor’s own address.

wire_api = "chat" is rejected

Current Codex releases removed the Chat Completions protocol. Set wire_api = "responses" and restart. BeatAPI serves the Responses format, so nothing else changes.

404 on every request

Almost always the base URL. It must end in /v1, with no trailing slash and no further path.

402 insufficient_credits

The balance is exhausted. Add credits from the dashboard.

429 rate_limit_exceeded

The key exceeded its request rate. Honour the Retry-After header. The per-minute allowance rises with lifetime top-ups and is shown on the dashboard.

Tool calls fail

Confirm wire_api = "responses". If a specific model still misbehaves under Codex’s tool protocol, try gpt-5.6-sol, which is the most heavily exercised pairing.

Support

Open a support ticket from the dashboard and include the request_id from the failing response.