# API reference

Base URL: `https://api.fastertokens.com`. Authenticate with `Authorization: Bearer ft_live_…` (or `X-API-Key`).

## POST /v1/chat/completions

Create a completion. The request and response follow the OpenAI chat completions format.

### Request body

| Field | Notes |
|---|---|
| `model` | `deepseek-v4.1-flash`. May be omitted. |
| `messages` | Required. System, user, assistant and tool messages. |
| `tools`, `tool_choice`, `parallel_tool_calls` | Function tools, as in the OpenAI API. |
| `stream` | `true` for server-sent events. Recommended for voice. |
| `stream_options.include_usage` | Adds a final chunk with token usage. |
| `max_tokens` / `max_completion_tokens` | Default 500, capped at 2,000. |
| `temperature`, `top_p`, `stop`, `presence_penalty`, `frequency_penalty`, `seed`, `response_format` | Passed through. |
| `user` | Used as the session ID when no `X-Session-Id` header is sent. |

Other fields are ignored. Reasoning is always off. The request body may be up to 512 KB.

### Request headers

| Header | Notes |
|---|---|
| `X-Session-Id` | One ID per call. Turns that share it are served consistently and can reuse the cached prompt. |
| `X-First-Token-Deadline-Ms` | How long to wait for the first real output, 300 to 10,000. Default 2,000. |

### Response headers

| Header | Notes |
|---|---|
| `x-request-id` | The request's ID. Quote it when you write to us. |
| `x-ttft-ms` | Milliseconds from the request arriving to the first real output (text or a tool call). |

### Errors

Errors use the OpenAI shape: `{"error": {"message": "…", "type": "…", "code": "…"}}`.

| Status | `code` | Meaning |
|---|---|---|
| 400 | `invalid_request`, `invalid_json`, `model_not_found` | The request is malformed. |
| 401 | `unauthorized`, `invalid_api_key` | Missing, unknown or revoked key. |
| 413 | `request_too_large` | Body over 512 KB. |
| 429 | `rate_limited` | Over the key's requests per minute. |
| 429 | `too_many_concurrent_requests` | Over the key's requests in flight. |
| 429 | `monthly_limit_reached` | The account's monthly allowance is used up. |
| 502 | `upstream_failed` | The request failed upstream before producing output. Safe to retry or fall back. |
| 503 | `capacity_paused` | The preview's capacity for the day is used up. It reopens at 00:00 UTC. |
| 504 | `first_token_timeout` | No output was produced before the deadline. Safe to retry or fall back. |

502 and 504 are returned before any part of a response is sent. If a response is cut off after it has started, a streamed response ends with an `error` event instead of `[DONE]`.

## GET /v1/models

Lists the available model.

## GET /v1/usage

Your completions and tokens by day, your own time-to-first-token percentiles, and the month's allowance.

| Query | Notes |
|---|---|
| `from`, `to` | `YYYY-MM-DD`, UTC. Default: this month to date. |
| `key=this` | Only the key making the request. |

```json
{
  "from": "2026-11-01", "to": "2026-11-13", "requests": 1840,
  "ttft_ms": { "p50": 412, "p95": 655, "completions": 1836 },
  "month": { "used": 1840, "limit": 2000 },
  "days": [{ "date": "2026-11-12", "key_id": "key_…", "requests": 320, "prompt_tokens": 401220, "completion_tokens": 9180 }]
}
```

The numbers in this example are illustrative.

## GET /benchmark

Public, no key. The live benchmark summary shown on the [benchmark page](https://fastertokens.com/benchmark): percentiles overall, by scenario, by day and by hour, with a single provider's figures for comparison.

## Limits

| Limit | Default |
|---|---|
| Requests per minute, per key | 300 |
| Requests in flight, per key | 20 |
| Completions per month, per account (preview) | shown in the dashboard |

Write to [leko@manulabs.xyz](mailto:leko@manulabs.xyz) to raise a limit.

## What is stored

Timings, token counts, the request ID and the key used. Messages and model output are not written to our database or logs.