> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llm.kiwi/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Reference for the LLM.kiwi REST API: authentication, chat completion endpoints, request and response fields, headers, and HTTP status codes.

## Base URL

```text theme={null}
https://api.llm.kiwi/v1
```

All endpoint paths documented below begin with `/v1`.

## Authentication

Send an API key as a Bearer token on every request:

```http theme={null}
Authorization: Bearer sk_kiwi_...
```

<Warning>
  Send keys only over HTTPS and only from trusted server-side code. Do not expose them in a browser bundle, mobile app package, screenshot, log, or public repository.
</Warning>

## List models

```http theme={null}
GET /v1/models
```

Returns model IDs currently available through the API.

```bash theme={null}
curl "https://api.llm.kiwi/v1/models" \
  -H "Authorization: Bearer $LLM_KIWI_API_KEY"
```

Example response:

```json theme={null}
{
  "object": "list",
  "data": [
    { "id": "auto", "object": "model", "owned_by": "llm-kiwi" },
    { "id": "hrllm", "object": "model", "owned_by": "llm-kiwi" }
  ]
}
```

## Create a chat completion

```http theme={null}
POST /v1/chat/completions
```

Sends conversation messages to a model and returns an assistant response.

### Request headers

| Header          | Required | Value                 |
| --------------- | -------- | --------------------- |
| `Authorization` | Yes      | `Bearer YOUR_API_KEY` |
| `Content-Type`  | Yes      | `application/json`    |

### Request body

| Field         | Type    | Required | Description                                                               |
| ------------- | ------- | -------- | ------------------------------------------------------------------------- |
| `model`       | string  | Yes      | Model ID such as `auto` or `hrllm`                                        |
| `messages`    | array   | Yes      | Ordered conversation messages                                             |
| `temperature` | number  | No       | Sampling variability; support and defaults can depend on the routed model |
| `max_tokens`  | integer | No       | Maximum number of output tokens                                           |
| `stream`      | boolean | No       | When `true`, returns incremental events instead of one complete response  |

### Message object

| Field     | Type   | Required | Description                      |
| --------- | ------ | -------- | -------------------------------- |
| `role`    | string | Yes      | `system`, `user`, or `assistant` |
| `content` | string | Yes      | Text content of the message      |

### Minimal request

```bash theme={null}
curl "https://api.llm.kiwi/v1/chat/completions" \
  -H "Authorization: Bearer $LLM_KIWI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'
```

### Example response

```json theme={null}
{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1700000000,
  "model": "auto",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 8,
    "total_tokens": 18
  }
}
```

### Response fields

| Field                        | Description                                         |
| ---------------------------- | --------------------------------------------------- |
| `id`                         | Identifier for the completion                       |
| `model`                      | Model value reported for the request                |
| `choices`                    | Generated completion choices                        |
| `choices[0].message.content` | Assistant response text                             |
| `choices[0].finish_reason`   | Why generation stopped; commonly `stop` or `length` |
| `usage`                      | Token counts when provided                          |

## Streaming

Set `stream` to `true` to receive incremental server-sent events:

```json theme={null}
{
  "model": "auto",
  "messages": [{"role": "user", "content": "Write a short story."}],
  "stream": true
}
```

Use an SDK that parses the event stream unless you specifically need to implement SSE parsing. See [Code examples](/examples#stream-a-response).

## HTTP status codes

| Status | Meaning                           | Application behavior                       |
| ------ | --------------------------------- | ------------------------------------------ |
| `200`  | Success                           | Read the response                          |
| `400`  | Invalid request                   | Fix request fields; do not retry unchanged |
| `401`  | Missing or invalid authentication | Check or replace the API key               |
| `403`  | Request is not allowed            | Check account or key access                |
| `404`  | Endpoint or model not found       | Check the URL and model ID                 |
| `429`  | Rate limit reached                | Wait and retry with backoff                |
| `500`  | Server error                      | Retry a limited number of times            |
| `503`  | Service temporarily unavailable   | Retry a limited number of times            |

Example error body:

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}
```

Do not depend on an error message's exact wording. Branch on the HTTP status and a stable error code when one is available.

<CardGroup cols={2}>
  <Card title="Error reference" icon="triangle-exclamation" href="/errors">
    Diagnose each status and choose whether to retry.
  </Card>

  <Card title="Limits and pricing" icon="gauge" href="/limits">
    Review service limits before production use.
  </Card>
</CardGroup>