---
url: https://docs.freetheai.org/api.md
description: >-
  FreeTheAI API reference - base URL, authentication, the error format, and
  every public endpoint, from the OpenAPI 3.1 contract.
---

# API reference

The FreeTheAI API is an OpenAI-compatible HTTP API with JSON bodies. This reference covers every public endpoint. The machine-readable contract is the OpenAPI 3.1 document at [api.freetheai.org/openapi.json](https://api.freetheai.org/openapi.json), also listed at [freetheai.org/.well-known/api-catalog](https://freetheai.org/.well-known/api-catalog).

## Base URL

```text
https://api.freetheai.org
```

Every path below starts with `/v1`. OpenAI SDKs take `https://api.freetheai.org/v1` as their base URL; the Anthropic SDK takes `https://api.freetheai.org`. See [Endpoints and base URLs](/concepts/endpoints).

## Authentication

Send your API key on every request:

```http
Authorization: Bearer ftai_your_key_here
```

`x-api-key: ftai_your_key_here` works too. Keys are created at **Dashboard > API keys** on freetheai.org; see [Account and API keys](/getting-started/account). Free models also need a confirmed email and today's [check-in](/getting-started/check-in).

## Endpoints

| Method and path | What it does |
| --- | --- |
| [`POST /v1/chat/completions`](/api/chat-completions) | Create a chat completion (OpenAI Chat Completions format) |
| [`POST /v1/responses`](/api/responses) | Create a model response (OpenAI Responses format) |
| [`POST /v1/messages`](/api/messages) | Create a message (Anthropic Messages format) |
| [`GET /v1/models`](/api/models) | List the models your key can use |
| [`POST /v1/search`](/api/search) | Search the web |
| [`POST /v1/answer`](/api/answer) | Answer a question from the web, with sources |
| [`GET /v1/health`](#health) | Service health (no key needed) |

The three inference endpoints accept every free model, stream with `"stream": true`, and support tool calls. Fields this reference does not list are passed through to the model when it supports them, so standard OpenAI and Anthropic parameters work as you would expect.

## Errors

Errors return a JSON body with an HTTP status:

```json
{
  "error": {
    "message": "Daily check-in required for free models. Visit https://freetheai.org/checkin to solve the captcha.",
    "type": "gateway_error"
  }
}
```

| Status | Meaning |
| --- | --- |
| `400` | The request is invalid, uses a setting the model does not accept, or was blocked by the model's content filter (`error.code` `content_filter`). |
| `401` | The API key is missing, incomplete, revoked, or expired. |
| `402` | Paid requests only (paid models are coming soon). |
| `403` | Not allowed: email not confirmed, no check-in today, a key restriction, or an account on hold. |
| `404` | Unknown model (`error.code` `model_not_found`). |
| `413` | The body is larger than 8 MB. |
| `429` | A limit was reached: one request at a time, daily free requests, a usage window, or a rate limit. |
| `502` | The model failed, or a stream broke. Carries `error.error_id` and the `X-Error-ID` header. |
| `503` | The model is busy or paused right now. Not counted against your limits. |

Every message, word for word, with its fix: [Errors](/errors).

## Health {#health}

`GET https://api.freetheai.org/v1/health`

Reports whether the API is reachable. It needs no key.

```bash
curl https://api.freetheai.org/v1/health
```

```json
{ "status": "ok" }
```

For the status of each model, see the [status page](https://freetheai.org/status).

## Conventions

* **JSON in, JSON out.** Send `Content-Type: application/json`. Streams are `text/event-stream`.
* **Model IDs** are case-sensitive and start with `fta/`. Copy them from [the Models page](https://freetheai.org/models) or [`GET /v1/models`](/api/models).
* **Usage** is reported in every response's `usage` object, and in the final chunk of a stream.
* **Privacy.** FreeTheAI does not store prompts or replies.