# API reference

Source: https://router.africa/docs/api-reference

## Base URL

All requests go to `https://api.router.africa`. The paths in this reference start with `/v1`, so the full address of an endpoint is `https://api.router.africa/v1/...`. Use HTTPS only.

New to the API? Start with the [Quickstart](https://router.africa/docs/quickstart).

## Authentication

Send your key as `Authorization: Bearer YOUR_KEY`. Keys start with `sk-ra-`. Never put a key in the URL or the body: the request is refused with `key_not_in_header`.

`POST /v1/messages` also accepts `x-api-key`, so the Anthropic SDK works with its default setup. See [Authentication](https://router.africa/docs/authentication) for key handling and the authentication errors.

## Request and response format

Request bodies are JSON. Send `Content-Type: application/json` on every request that has a body. Responses are JSON, except a streamed response, which is a stream of server-sent events.

Every response, success or error, carries an `x-request-id` header. Quote it when you contact support. Amounts of money are credits, always decimal strings with eight decimal places and no currency code.

## OpenAI and Anthropic compatibility

The API works with the OpenAI SDK and the Anthropic SDK. Change the base URL and the key, and keep the rest of your code. Chat completions and Responses use the OpenAI formats. Messages uses the Anthropic format.

The spec lists only what is supported. Anything not listed is not part of the API, even if it appears to work. See [Compatibility notes](https://router.africa/docs/compatibility-notes), [Messages](https://router.africa/docs/messages) and [Responses](https://router.africa/docs/responses).

## Streaming

Set `"stream": true` to receive the response as server-sent events. Each event is a line that starts with `data:` and holds a JSON chunk. The stream ends with `data: [DONE]`. The endpoints that stream show their events on their own page. See [Streaming](https://router.africa/docs/streaming).

## Errors

Errors use one JSON shape. Branch on the HTTP status for retry logic and on `error.metadata.reason` for the specific cause. `POST /v1/messages` returns errors in Anthropic's format instead. Every error an endpoint can return is listed on its page. See [Errors](https://router.africa/docs/errors) for each status and reason.

```json
{
  "error": {
    "code": 402,
    "message": "This workspace doesn't have enough credits for this request. Add credits at https://app.router.africa.",
    "metadata": {
      "error_type": "payment_required",
      "reason": "insufficient_credits"
    }
  }
}
```

## Rate limits

Each API key has a rate limit. When you reach it you get `429` with a `Retry-After` header, the number of seconds to wait. `Retry-After` is always sent on `429`, `503` and `529`. Rate-limit headers such as `x-ratelimit-remaining` are not sent. See [Rate limits](https://router.africa/docs/rate-limits).

## Idempotency

Send an optional `Idempotency-Key` header, a unique value for each logical request, and reuse it when you retry. Requests with the same key are treated as one request for 24 hours. A stored replay has the header `x-idempotent-replay: true`, and you are not charged again. See [Idempotency and retries](https://router.africa/docs/idempotency-and-retries).

## Download the spec

These pages are built from one OpenAPI 3.1 spec. Use it to generate a client or to import into a tool such as Postman.

[openapi.yaml](https://router.africa/docs/openapi.yaml) and [openapi.json](https://router.africa/docs/openapi.json)

## Chat

- [Create a chat completion](https://router.africa/docs/api-reference/create-chat-completion.md): `POST /v1/chat/completions`

## Models

- [List models](https://router.africa/docs/api-reference/list-models.md): `GET /v1/models`

## Messages

- [Create a message (Anthropic format)](https://router.africa/docs/api-reference/create-message.md): `POST /v1/messages`

## Responses

- [Create a response (OpenAI Responses format)](https://router.africa/docs/api-reference/create-response.md): `POST /v1/responses`

## Generation

- [Look up a past request](https://router.africa/docs/api-reference/get-generation.md): `GET /v1/generation`

## Key

- [Get the current key](https://router.africa/docs/api-reference/get-key.md): `GET /v1/key`