# Chess Puzzles API
> Serve chess tactics puzzles on demand: a random puzzle (optionally constrained by theme and rating), a single puzzle by id, full search and filtering by tactic theme and difficulty rating, and the complete list of available themes. Every puzzle includes the starting position as FEN, the full solution as UCI moves, the side to move, the difficulty rating, popularity and play count, theme and opening tags and a direct link to train it on Lichess. Built on a curated 20,000-puzzle sample of the open Lichess puzzle database (CC0) spanning 73 themes and ratings from roughly 400 to 3100. Every endpoint accepts input via the query string or the request body and returns lean JSON. Pure server-side data (no third-party upstream), so responses are instant and always available. Ideal for chess apps, training tools, "puzzle of the day" features and games.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/chesspuzzles-api/..."
```

## Pricing
- **Free** (Free) — 18,000 calls/Mo, 3 req/s
- **Basic** ($4/Mo) — 220,000 calls/Mo, 8 req/s
- **Pro** ($11/Mo) — 1,800,000 calls/Mo, 25 req/s
- **Mega** ($31/Mo) — 9,000,000 calls/Mo, 60 req/s

## Endpoints

### Chess

#### `GET /v1/puzzle` — Single puzzle by id

**Parameters:**
- `id` (query, required, string) — Puzzle id Example: `00008`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chesspuzzles-api/v1/puzzle?id=00008"
```

#### `GET /v1/random` — Random puzzle by theme/rating

**Parameters:**
- `theme` (query, optional, string) — Tactic theme Example: `mateIn2`
- `min_rating` (query, optional, string) — Minimum rating Example: `1200`
- `max_rating` (query, optional, string) — Maximum rating Example: `1800`
- `size` (query, optional, string) — 1..10 (default 1) Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chesspuzzles-api/v1/random?theme=mateIn2&min_rating=1200&max_rating=1800&size=1"
```

#### `GET /v1/search` — Search & filter puzzles

**Parameters:**
- `theme` (query, optional, string) — Tactic theme Example: `fork`
- `min_rating` (query, optional, string) — Minimum rating Example: `1000`
- `max_rating` (query, optional, string) — Maximum rating Example: `2000`
- `sort` (query, optional, string) — rating|popularity|plays Example: `popularity`
- `limit` (query, optional, string) — 1..100 (default 20) Example: `20`
- `offset` (query, optional, string) — Offset Example: `0`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chesspuzzles-api/v1/search?theme=fork&min_rating=1000&max_rating=2000&sort=popularity&limit=20&offset=0"
```

#### `GET /v1/themes` — All tactic themes with counts

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chesspuzzles-api/v1/themes"
```


---
Marketplace page: https://www.oanor.com/api/chesspuzzles-api
OpenAPI spec: https://www.oanor.com/api/chesspuzzles-api/openapi.json