# AtmoRouter — API reference

Source: https://atmorouter.dev/docs/endpoints

Explore request fields, response examples, errors, and copyable SDK samples. All examples are illustrative; discover current model IDs and prices from the catalog.

[Download inference OpenAPI 3.1](https://atmorouter.dev/openapi.json)[Compatibility matrix](https://atmorouter.dev/docs/compatibility)

Base URL: `https://atmorouter.dev`. Use `/v1` for OpenAI SDKs and the bare host for Anthropic SDKs. Dashboard APIs require a separate login session.

**POST /v1/chat/completions**

## Create a chat completion

OpenAI Chat Completions passthrough with account billing. Additional fields are forwarded; support depends on the selected model. An OpenAI-compatible API does not imply support for the Responses API.

Authentication: Bearer ar- key or x-api-key

| Request field | Type | Description |
| --- | --- | --- |
| modelRequired | string | Enabled model ID from GET /v1/models, or a private combo/<slug> alias owned by the API key account. Normal member permissions, budgets, pricing, and balance checks apply. |
| messagesRequired | array | Conversation messages. Content blocks and tools depend on the model. |
| max_tokens | integer | Requested output limit. Affordability and context caps apply; upstream enforcement varies. |
| stream | boolean | Return OpenAI-format SSE, ending with data: [DONE]. |
| stream_options | object | See the request schema. |
| temperature | number | Sampling setting forwarded to the model; support varies. |
| top_p | number | Nucleus sampling setting; support varies. |
| stop | Union | Stop sequence(s), when supported. |
| tools | array | OpenAI function definitions; model must support tools. |
| tool_choice | Union | Tool selection policy, if supported. |
| response_format | object | Structured output settings forwarded to the upstream; capability is model-specific. |

### curl example

```
curl -X POST 'https://atmorouter.dev/v1/chat/completions' \
  -H "Authorization: Bearer $ATMOROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "cbcn/glm-5.3",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "max_tokens": 128
}'
```

### 200 response example

```json
{
  "id": "chatcmpl-example",
  "object": "chat.completion",
  "model": "cbcn/glm-5.3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello!"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 2,
    "total_tokens": 11,
    "cached_tokens": 0,
    "cost": 0.00002
  }
}
```

**Full request schema**

```json
{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Enabled model ID from GET /v1/models, or a private combo/<slug> alias owned by the API key account. Normal member permissions, budgets, pricing, and balance checks apply."
    },
    "messages": {
      "type": "array",
      "minItems": 1,
      "description": "Conversation messages. Content blocks and tools depend on the model.",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "description": "Message role."
          },
          "content": {
            "description": "Text or model-supported content blocks.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            ]
          }
        },
        "required": [],
        "additionalProperties": true
      }
    },
    "max_tokens": {
      "type": "integer",
      "minimum": 1,
      "description": "Requested output limit. Affordability and context caps apply; upstream enforcement varies."
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "Return OpenAI-format SSE, ending with data: [DONE]."
    },
    "stream_options": {
      "type": "object",
      "properties": {
        "include_usage": {
          "type": "boolean",
          "description": "Request usage frames. The gateway enables this when stream_options is omitted."
        }
      },
      "required": [],
      "additionalProperties": true
    },
    "temperature": {
      "type": "number",
      "description": "Sampling setting forwarded to the model; support varies."
    },
    "top_p": {
      "type": "number",
      "description": "Nucleus sampling setting; support varies."
    },
    "stop": {
      "description": "Stop sequence(s), when supported.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "OpenAI function definitions; model must support tools."
    },
    "tool_choice": {
      "description": "Tool selection policy, if supported.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object"
        }
      ]
    },
    "response_format": {
      "type": "object",
      "description": "Structured output settings forwarded to the upstream; capability is model-specific.",
      "additionalProperties": true
    }
  },
  "required": [
    "model",
    "messages"
  ],
  "additionalProperties": true
}
```

**Response schema**

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "type": "string"
    },
    "model": {
      "type": "string"
    },
    "choices": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "usage": {
      "$ref": "#/components/schemas/OpenAIUsage"
    }
  },
  "required": [],
  "additionalProperties": true
}
```

### HTTP outcomes

**200**

Completed JSON response or SSE stream. Examples are illustrative; upstream-specific fields can vary.

**400**

Invalid request: inspect the body and correct it.

**401**

Missing, invalid, revoked, or ineligible API key.

**402**

Local balance, affordability, or promotional eligibility gate. Inspect the message; only payment eligibility issues are resolved by a top-up.

**403**

The key does not allow this model.

**404**

The model is not enabled or priced for inference.

**405**

Method not allowed; use POST.

**424**

Billing settlement pending. Generation may have completed; do not automatically resend. Check Usage first. X-Should-Retry: false. Error code billing_settlement_pending; retryable: false.

**429**

Account rate limit, concurrency limit, quota, or upstream rate limit. Back off; use Retry-After when supplied.

**500**

Gateway error. Record the request ID when available and contact support if it persists.

**502**

Upstream request failed. Retry conservatively before output only. Incomplete or invalid model billing metadata uses billing_metadata_unavailable and is not charged.

**503**

Temporary service or upstream availability failure.

**POST /v1/messages**

## Create an Anthropic-format message

Use https://atmorouter.dev as the Anthropic SDK base URL; raw HTTP uses the full /v1/messages path. The model must support the requested features.

Authentication: Bearer ar- key or x-api-key

| Request field | Type | Description |
| --- | --- | --- |
| modelRequired | string | Enabled model ID from GET /v1/models, or a private combo/<slug> alias owned by the API key account. Normal member permissions, budgets, pricing, and balance checks apply. |
| max_tokensRequired | integer | Required positive integer. Context and affordability caps apply. |
| messagesRequired | array | Conversation messages. Content blocks and tools depend on the model. |
| system | Union | System prompt text or Anthropic content blocks. |
| stream | boolean | Native Anthropic SSE ending in message_stop. |
| tools | array | Anthropic tool definitions, when supported. |
| tool_choice | object | Anthropic tool selection, when supported. |
| temperature | number | Forwarded sampling setting; model-specific. |
| stop_sequences | array | Forwarded stop sequences; model-specific. |

### curl example

```
curl -X POST 'https://atmorouter.dev/v1/messages' \
  -H "Authorization: Bearer $ATMOROUTER_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -d '{
  "model": "cbcn/glm-5.3",
  "messages": [
    {
      "role": "user",
      "content": "Hello!"
    }
  ],
  "max_tokens": 128
}'
```

### 200 response example

```json
{
  "id": "msg-example",
  "type": "message",
  "role": "assistant",
  "model": "cbcn/glm-5.3",
  "content": [
    {
      "type": "text",
      "text": "Hello!"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 9,
    "output_tokens": 2
  }
}
```

**Full request schema**

```json
{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Enabled model ID from GET /v1/models, or a private combo/<slug> alias owned by the API key account. Normal member permissions, budgets, pricing, and balance checks apply."
    },
    "max_tokens": {
      "type": "integer",
      "minimum": 1,
      "description": "Required positive integer. Context and affordability caps apply."
    },
    "messages": {
      "type": "array",
      "minItems": 1,
      "description": "Conversation messages. Content blocks and tools depend on the model.",
      "items": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "description": "Message role."
          },
          "content": {
            "description": "Text or model-supported content blocks.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            ]
          }
        },
        "required": [],
        "additionalProperties": true
      }
    },
    "system": {
      "description": "System prompt text or Anthropic content blocks.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "object"
          }
        }
      ]
    },
    "stream": {
      "type": "boolean",
      "default": false,
      "description": "Native Anthropic SSE ending in message_stop."
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Anthropic tool definitions, when supported."
    },
    "tool_choice": {
      "type": "object",
      "description": "Anthropic tool selection, when supported."
    },
    "temperature": {
      "type": "number",
      "description": "Forwarded sampling setting; model-specific."
    },
    "stop_sequences": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Forwarded stop sequences; model-specific."
    }
  },
  "required": [
    "model",
    "messages",
    "max_tokens"
  ],
  "additionalProperties": true
}
```

**Response schema**

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "type": "string"
    },
    "role": {
      "type": "string"
    },
    "model": {
      "type": "string"
    },
    "content": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true
      }
    },
    "stop_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "usage": {
      "type": "object",
      "properties": {
        "input_tokens": {
          "type": "integer"
        },
        "output_tokens": {
          "type": "integer"
        }
      },
      "required": [],
      "additionalProperties": true
    }
  },
  "required": [],
  "additionalProperties": true
}
```

### HTTP outcomes

**200**

Completed JSON response or SSE stream. Examples are illustrative; upstream-specific fields can vary.

**400**

Invalid request: inspect the body and correct it.

**401**

Missing, invalid, revoked, or ineligible API key.

**402**

Local balance, affordability, or promotional eligibility gate. Inspect the message; only payment eligibility issues are resolved by a top-up.

**403**

The key does not allow this model.

**404**

The model is not enabled or priced for inference.

**405**

Method not allowed; use POST.

**424**

Billing settlement pending. Generation may have completed; do not automatically resend. Check Usage first. X-Should-Retry: false. Error code billing_settlement_pending; retryable: false.

**429**

Account rate limit, concurrency limit, quota, or upstream rate limit. Back off; use Retry-After when supplied.

**500**

Gateway error. Record the request ID when available and contact support if it persists.

**502**

Upstream request failed. Retry conservatively before output only. Incomplete or invalid model billing metadata uses billing_metadata_unavailable and is not charged.

**503**

Temporary service or upstream availability failure.

**GET /v1/models**

## List the retail model catalog

Public retail catalog and pricing in USD per million tokens. A valid owner API key also includes that account’s private combo/<slug> aliases. Unauthenticated responses contain ordinary models only. Catalog presence does not guarantee every model modality or feature can be called.

Authentication: Public; no key required

### curl example

```
curl 'https://atmorouter.dev/v1/models'
```

### 200 response example

```json
{
  "object": "list",
  "data": [
    {
      "id": "cbcn/glm-5.3",
      "object": "model",
      "owned_by": "atmorouter",
      "family": "CodeBuddy CN",
      "pricing": {
        "input": 0.1,
        "output": 0.2,
        "cached_input": 0.01
      },
      "context_length": 128000,
      "max_output_tokens": 8192,
      "modality": "text",
      "supports_cache": true
    }
  ]
}
```

**Response schema**

```json
{
  "type": "object",
  "properties": {
    "object": {
      "type": "string",
      "const": "list"
    },
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "object": {
            "type": "string"
          },
          "owned_by": {
            "type": "string"
          },
          "family": {
            "type": "string"
          },
          "pricing": {
            "type": "object",
            "properties": {
              "input": {
                "type": "number"
              },
              "output": {
                "type": "number"
              },
              "cached_input": {
                "type": "number"
              }
            },
            "required": [],
            "additionalProperties": true
          },
          "context_length": {
            "type": "integer"
          },
          "max_output_tokens": {
            "type": "integer"
          },
          "modality": {
            "type": "string"
          },
          "supports_cache": {
            "type": "boolean"
          }
        },
        "required": [],
        "additionalProperties": true
      }
    }
  },
  "required": [],
  "additionalProperties": true
}
```

### HTTP outcomes

**200**

Current catalog. Values below are illustrative, not live prices.

**500**

Catalog unavailable.

## Dashboard & public endpoint directory

Follow an endpoint for its detailed parameters and examples. Session credentials are separate from inference keys.

- [POST /api/dashboard/playground/chat](https://atmorouter.dev/docs/observability)

  Dashboard session authentication; same inference and billing core · Login session
- [POST /api/dashboard/register](https://atmorouter.dev/docs/management-api#post-api-dashboard-register)

  Email-first signup; verification required before sign-in · Public
- [POST /api/dashboard/login](https://atmorouter.dev/docs/management-api#post-api-dashboard-login)

  Sign in and receive an HttpOnly session cookie · Public
- [POST /api/dashboard/resend-verification](https://atmorouter.dev/docs/account-security)

  Request another verification email; cooldown applies · Public
- [POST /api/dashboard/complete-registration](https://atmorouter.dev/docs/account-security)

  Complete signup with token and password; sign in separately · Public
- [GET/POST /api/dashboard/keys](https://atmorouter.dev/docs/management-api#get-post-api-dashboard-keys)

  Rate limit 1..1000; default 500 when omitted · Login session
- [GET/PUT/DELETE /api/dashboard/budgets](https://atmorouter.dev/docs/budgets#get-api-dashboard-budgets)

  Model rate caps for the account and individual API keys; current per-request minimum · Login session
- [PUT/DELETE /api/dashboard/budget-rules](https://atmorouter.dev/docs/budgets#put-api-dashboard-budget-rules)

  Percentage-off official rate caps for all models, a family, or a model; optional API key scope · Login session
- [DELETE /api/dashboard/keys/{id}](https://atmorouter.dev/docs/management-api#delete-api-dashboard-keys)

  Immediate revocation; see C-no-rotate · Login session
- [GET /api/dashboard/usage](https://atmorouter.dev/docs/management-api#get-api-dashboard-usage)

  Account-scoped request history; see C-usage · Login session
- [GET /api/dashboard/usage-stats](https://atmorouter.dev/docs/management-api#get-api-dashboard-usage-stats)

  Account totals by model and family; see C-usage · Login session
- [GET /api/dashboard/catalog](https://atmorouter.dev/docs/management-api#get-api-dashboard-catalog)

  Public read filter; see C-catalog · Public
- [GET /api/dashboard/market](https://atmorouter.dev/docs/management-api#get-api-dashboard-market)

  Public JSON snapshot, not SSE; see C-market · Public
- [GET /api/dashboard/balance](https://atmorouter.dev/docs/management-api#get-api-dashboard-balance)

  Prepaid account balance in USD · Login session
- [GET /api/dashboard/deposits](https://atmorouter.dev/docs/management-api#get-api-dashboard-deposits)

  Combined deposit history; see Billing · Login session
- [GET/POST/DELETE /api/dashboard/combos](https://atmorouter.dev/docs/combos)

  Manage private callable combos; dashboard CRUD only; see C-behavior-hardening · Login session
- [POST /api/dashboard/reset-password](https://atmorouter.dev/docs/account-security)

  Current password required; revokes other sessions and all API keys · Login session
- [POST /api/dashboard/logout](https://atmorouter.dev/docs/account-security)

  Destroy the current session and clear its cookie · Login session
- [GET /api/dashboard/me](https://atmorouter.dev/docs/management-api#get-api-dashboard-me)

  Session identity, account status, and balance · Login session
- [POST /api/dashboard/delete-account/request](https://atmorouter.dev/docs/account-security)

  Password confirmation and a time-limited email token · Login session
- [POST /api/dashboard/delete-account/confirm](https://atmorouter.dev/docs/account-security)

  Confirm account deletion; seven-day cancellation window · Login session
- [POST /api/dashboard/delete-account/cancel](https://atmorouter.dev/docs/account-security)

  Cancel pending deletion and receive a fresh session · Login session
- [GET /api/dashboard/export](https://atmorouter.dev/docs/account-security)

  Account data, redacted key previews, and recent usage · Login session
- [GET /api/dashboard/deposit/info](https://atmorouter.dev/docs/management-api#get-api-dashboard-deposit-info)

  Available payment methods and current limits · Login session
- [POST /api/dashboard/deposit/epusdt/create](https://atmorouter.dev/docs/management-api#post-api-dashboard-deposit-epusdt-create)

  Create a hosted cryptocurrency checkout order · Login session
- [GET /api/dashboard/deposit/epusdt/status](https://atmorouter.dev/docs/management-api#get-api-dashboard-deposit-epusdt-status)

  Read and reconcile an order; see Billing · Login session
- [GET /api/dashboard/deposit/epusdt/list](https://atmorouter.dev/docs/management-api#get-api-dashboard-deposit-epusdt-list)

  Recent hosted checkout orders · Login session
- [POST /api/dashboard/topup/qris](https://atmorouter.dev/docs/management-api#post-api-dashboard-topup-qris)

  Create a QRIS invoice in IDR · Login session
- [GET /api/dashboard/topup/status](https://atmorouter.dev/docs/management-api#get-api-dashboard-topup-status)

  Read the stored QRIS invoice status · Login session
- [GET /api/dashboard/topups](https://atmorouter.dev/docs/management-api#get-api-dashboard-topups)

  Recent QRIS invoices · Login session
- [GET/POST /api/dashboard/affiliate](https://atmorouter.dev/docs/affiliate)

  Referral summary, payout requests, referrals, and ledger · Login session
- [GET /api/public/stats](https://atmorouter.dev/docs/management-api#get-api-public-stats)

  Aggregate statistics for the public website · Public
- [GET /api/public/status](https://atmorouter.dev/docs/management-api#get-api-public-status)

  Overall and upstream availability with measured timing samples · Public
- [GET /api/announcement](https://atmorouter.dev/docs/management-api#get-api-announcement)

  Current public website announcement · Public

## Compatibility notes

Use an AtmoRouter ar- key; credentials are not interchangeable across providers.

Create a replacement key, update your clients, then revoke the old key. No rotation grace period is built in.

The Anthropic SDK base is https://atmorouter.dev. Raw HTTP still calls /v1/messages.

Retry transient 429/502/503 failures with backoff before output. Retrying a partial answer can duplicate work and charges.

Failed requests before output are refunded. Interrupted requests can be billed for processed tokens.

Inference uses ar- keys; dashboard APIs use a login session. Public catalog/status endpoints need no credential.

Usage is account-scoped. Duration, first byte, and first answer text measure different points in the response.

Available payment methods, exchange rates, and eligibility come from the dashboard; inspect the invoice before paying.

The catalog can list non-text modalities. Image/video generation and embeddings endpoints are not implemented here.

The catalog all=1 parameter is a read filter, not a way to enable a model.

Market data is a public JSON snapshot, not an SSE subscription.

Combo management supports GET/POST/DELETE only. Call private combo/<slug> aliases through Chat Completions or Messages with an owner API key.