# API reference

> A consolidated reference for ScaleMax model discovery, generation, token counting, and usage endpoints.

The machine-readable OpenAPI 3.1 description is available at [`/openapi.json`](https://docs.scalemax.pro/openapi.json). Treat model availability as key-specific: use the authenticated `GET /v1/models` response instead of hard-coding a model list.

## Choose the server for your key

| Key mode | API origin | OpenAI-compatible base URL |
| --- | --- | --- |
| API credit | `https://api.scalemax.pro` | `https://api.scalemax.pro/v1` |
| Token budget | `https://api.scalemax.pro/token` | `https://api.scalemax.pro/token/v1` |

The paths below are relative to the selected API origin. Do not add the `/token` prefix to an API-credit key, and do not omit it for a token-budget key.

## Authentication

Send the secret from a trusted server environment. OpenAI-compatible routes and the usage route use `Authorization: Bearer $SCALEMAX_API_KEY`. Anthropic-compatible routes accept that bearer header or `x-api-key: $SCALEMAX_API_KEY`. Send one authentication method, not both, and never expose a key in browser JavaScript or a public repository.

**macOS / Linux**

select-key-mode.sh:

```bash
# API-credit key
export SCALEMAX_API_ORIGIN="https://api.scalemax.pro"

# Token-budget key (use this instead for a token key)
# export SCALEMAX_API_ORIGIN="https://api.scalemax.pro/token"

export SCALEMAX_API_KEY="YOUR_SCALEMAX_API_KEY"
```

**Windows PowerShell**

select-key-mode.ps1:

```powershell
# API-credit key
$env:SCALEMAX_API_ORIGIN = "https://api.scalemax.pro"

# Token-budget key (use this instead for a token key)
# $env:SCALEMAX_API_ORIGIN = "https://api.scalemax.pro/token"

$env:SCALEMAX_API_KEY = "YOUR_SCALEMAX_API_KEY"
```

These variables last for this PowerShell window. Use `setx NAME "value"` to keep one for new windows (then open a new terminal).

## Endpoints

| Method | Path | Purpose |
| --- | --- | --- |
| GET | `/v1/models` | Discover models available to a key. |
| POST | `/v1/chat/completions` | Create an OpenAI-compatible chat completion. |
| POST | `/v1/responses` | Create an OpenAI-compatible Responses API result. |
| POST | `/v1/messages` | Create an Anthropic-compatible message. |
| POST | `/v1/messages/count_tokens` | Count input tokens for an Anthropic request. |
| GET | `/v1/usage` | Read the authenticated key’s usage summary. |

## GET `/v1/models`

Returns the public catalog when no credential is supplied. With a valid credential, the response is filtered to that key’s provider scope and entitlements. If an authentication header is present but invalid, the request fails instead of falling back to the public catalog.

**macOS / Linux**

list-models.sh:

```bash
curl "$SCALEMAX_API_ORIGIN/v1/models" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY"
```

**Windows PowerShell**

list-models.ps1:

```powershell
curl.exe "$env:SCALEMAX_API_ORIGIN/v1/models" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY"
```

The response is an OpenAI-style list object. Copy the exact `data[].id` value into generation requests.

## POST `/v1/chat/completions`

Creates an OpenAI-compatible chat completion. Required fields are `model` and a non-empty `messages` array. Optional fields include `stream`, `max_tokens`, and supported OpenAI-format tools.

**macOS / Linux**

chat-completion.sh:

```bash
curl "$SCALEMAX_API_ORIGIN/v1/chat/completions" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with hello."}],
    "max_tokens": 32
  }'
```

**Windows PowerShell**

chat-completion.ps1:

```powershell
@'
{
  "model": "YOUR_AUTHENTICATED_MODEL_ID",
  "messages": [{"role": "user", "content": "Reply with hello."}],
  "max_tokens": 32
}
'@ | Set-Content -Path body.json

curl.exe "$env:SCALEMAX_API_ORIGIN/v1/chat/completions" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

PowerShell changes quotes inside a JSON argument, so the request body goes into body.json first and curl.exe sends that file. Type curl.exe, not curl: in Windows PowerShell 5.1, curl is a different command.

## POST `/v1/responses`

Creates an OpenAI-compatible Responses API result. Supply `model` and `input`. Use `max_output_tokens` to cap output and `stream: true` for server-sent events.

**macOS / Linux**

responses.sh:

```bash
curl "$SCALEMAX_API_ORIGIN/v1/responses" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "input": "Reply with hello.",
    "max_output_tokens": 32
  }'
```

**Windows PowerShell**

responses.ps1:

```powershell
@'
{
  "model": "YOUR_AUTHENTICATED_MODEL_ID",
  "input": "Reply with hello.",
  "max_output_tokens": 32
}
'@ | Set-Content -Path body.json

curl.exe "$env:SCALEMAX_API_ORIGIN/v1/responses" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

PowerShell changes quotes inside a JSON argument, so the request body goes into body.json first and curl.exe sends that file. Type curl.exe, not curl: in Windows PowerShell 5.1, curl is a different command.

## POST `/v1/messages`

Creates an Anthropic-compatible message. Supply `model` and a non-empty `messages` array. `max_tokens` defaults to 1,024 when omitted and is capped at the selected model’s published output limit.

**macOS / Linux**

messages.sh:

```bash
curl "$SCALEMAX_API_ORIGIN/v1/messages" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with hello."}],
    "max_tokens": 32
  }'
```

**Windows PowerShell**

messages.ps1:

```powershell
@'
{
  "model": "YOUR_AUTHENTICATED_MODEL_ID",
  "messages": [{"role": "user", "content": "Reply with hello."}],
  "max_tokens": 32
}
'@ | Set-Content -Path body.json

curl.exe "$env:SCALEMAX_API_ORIGIN/v1/messages" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "anthropic-version: 2023-06-01" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

PowerShell changes quotes inside a JSON argument, so the request body goes into body.json first and curl.exe sends that file. Type curl.exe, not curl: in Windows PowerShell 5.1, curl is a different command.

## POST `/v1/messages/count_tokens`

Returns an `input_tokens` estimate for a valid Anthropic-format request without creating a model response or deducting model-generation usage.

**macOS / Linux**

count-tokens.sh:

```bash
curl "$SCALEMAX_API_ORIGIN/v1/messages/count_tokens" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_AUTHENTICATED_MODEL_ID",
    "messages": [{"role": "user", "content": "Reply with hello."}]
  }'
```

**Windows PowerShell**

count-tokens.ps1:

```powershell
@'
{
  "model": "YOUR_AUTHENTICATED_MODEL_ID",
  "messages": [{"role": "user", "content": "Reply with hello."}]
}
'@ | Set-Content -Path body.json

curl.exe "$env:SCALEMAX_API_ORIGIN/v1/messages/count_tokens" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY" `
  -H "anthropic-version: 2023-06-01" `
  -H "Content-Type: application/json" `
  --data-binary "@body.json"
```

PowerShell changes quotes inside a JSON argument, so the request body goes into body.json first and curl.exe sends that file. Type curl.exe, not curl: in Windows PowerShell 5.1, curl is a different command.

## GET `/v1/usage`

Returns the authenticated key’s status, billing mode, provider scope, rate limit, request count, token totals, and credit or token balance. The response uses `object: "usage.summary"` and is intended for server-side account and diagnostics views.

**macOS / Linux**

usage.sh:

```bash
curl "$SCALEMAX_API_ORIGIN/v1/usage" \
  -H "Authorization: Bearer $SCALEMAX_API_KEY"
```

**Windows PowerShell**

usage.ps1:

```powershell
curl.exe "$env:SCALEMAX_API_ORIGIN/v1/usage" `
  -H "Authorization: Bearer $env:SCALEMAX_API_KEY"
```

## Streaming, retries, and errors

- Generation routes return JSON by default and server-sent events when `stream` is true.
- Supply a stable `Idempotency-Key` when a client may retry the same logical POST request.
- Do not retry after response content has started. For a `429` or safe transient failure, respect `Retry-After`.
- Record the `x-request-id` response header when contacting support. OpenAI-compatible and Anthropic-compatible routes use their respective error envelope shapes.

## Detailed guides

- [Chat Completions fields and tool use](https://docs.scalemax.pro/docs/chat-completions)
- [OpenAI compatibility boundaries](https://docs.scalemax.pro/docs/openai-compatibility)
- [Streaming event handling](https://docs.scalemax.pro/docs/streaming)
- [Authentication and key modes](https://docs.scalemax.pro/docs/authentication)
- [Error codes and recovery](https://docs.scalemax.pro/docs/error-codes)
- [Rate limits, headers, and retry behavior](https://docs.scalemax.pro/docs/rate-limits)
- [Model IDs, context limits, and pricing](https://docs.scalemax.pro/docs/models)

## Runnable examples

- [cURL examples](https://docs.scalemax.pro/docs/examples/curl) — model discovery and a first chat completion from a terminal.
- [Python SDK examples](https://docs.scalemax.pro/docs/examples/python) — OpenAI-compatible client setup and streaming.
- [JavaScript SDK examples](https://docs.scalemax.pro/docs/examples/javascript) — Node and TypeScript client setup.
- [OpenAI SDK examples](https://docs.scalemax.pro/docs/examples/openai-sdk) — Chat Completions and Responses through the official SDK.