# Sudoku API
> Generate, solve and validate Sudoku puzzles through a fast, fully-local API. Create fresh puzzles at four difficulty levels (easy, medium, hard, expert), each guaranteed to have exactly one solution, returned as both an 81-character string and a 9x9 grid alongside the full solution. Solve any valid puzzle with a backtracking engine that also reports whether the solution is unique, and validate a grid to detect rule conflicts and completeness. Inputs accept an 81-character string (0 or . for blanks) or a 9x9 array, by GET or JSON POST. Pure server-side compute with no third-party upstream, so responses are instant and the service is always available. Ideal for puzzle apps and games, newspapers and printables, tutors and training-data generation.

## 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/sudoku-api/..."
```

## Pricing
- **Free** (Free) — 200 calls/Mo, 2 req/s
- **Basic** ($2/Mo) — 10,000 calls/Mo, 5 req/s
- **Pro** ($8/Mo) — 75,000 calls/Mo, 15 req/s
- **Mega** ($24/Mo) — 400,000 calls/Mo, 40 req/s

## Endpoints

### Sudoku

#### `GET /v1/generate` — Generate a puzzle

**Parameters:**
- `difficulty` (query, optional, string) — easy | medium | hard | expert Example: `medium`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sudoku-api/v1/generate?difficulty=medium"
```

**Response:**
```json
{
    "data": {
        "clues": 34,
        "puzzle": "007000500000700800652800039069050200320070400400069305190000600073040000046080057",
        "solution": "837692514914735862652814739769453281325178496481269375198527643573946128246381957",
        "difficulty": "medium",
        "puzzle_grid": [
            [
                0,
                0,
                7,
                0,
                0,
                0,
                5,
                0,
                0
            ],
            [
                0,
                0,
                0,
                7,
                0,
                0,
                8,
                0,
                0
            ],
            [
                6,
                5,
                2,
                8,
                0,
                0,
                0,
                3,
                9
            ],
            [
                0,
                6,
                9,
                0,
                5,
                0,
                2,
                0,
                0
            ],
            [
                3,
                2,
                0,
                0,
                7,
                0,
                4,
                0,
                0
            ],
            [
                4,
                0,
                0,
                0,
                6,
                9,
                3,
                0,
                5
            ],
    
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/solve` — Solve a puzzle

**Parameters:**
- `grid` (query, required, string) — 81-char string (0/. for blanks) or 9x9 array Example: `530070000600195000098000060800060003400803001700020006060000280000419005000080079`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sudoku-api/v1/solve?grid=530070000600195000098000060800060003400803001700020006060000280000419005000080079"
```

**Response:**
```json
{
    "data": {
        "solved": true,
        "unique": true,
        "solution": "534678912672195348198342567859761423426853791713924856961537284287419635345286179",
        "given_clues": 30,
        "solution_grid": [
            [
                5,
                3,
                4,
                6,
                7,
                8,
                9,
                1,
                2
            ],
            [
                6,
                7,
                2,
                1,
                9,
                5,
                3,
                4,
                8
            ],
            [
                1,
                9,
                8,
                3,
                4,
                2,
                5,
                6,
                7
            ],
            [
                8,
                5,
                9,
                7,
                6,
                1,
                4,
                2,
                3
            ],
            [
                4,
                2,
                6,
                8,
                5,
                3,
                7,
                9,
                1
            ],
            [
                7,
                1,
                3,
                9,
                2,
                4,
                8,
                5,
                6
            ],
            [
                9,
                6,
                1,
            
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/validate` — Validate a grid

**Parameters:**
- `grid` (query, required, string) — 81-char string or 9x9 array Example: `530070000600195000098000060800060003400803001700020006060000280000419005000080079`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/sudoku-api/v1/validate?grid=530070000600195000098000060800060003400803001700020006060000280000419005000080079"
```

**Response:**
```json
{
    "data": {
        "valid": true,
        "complete": false,
        "conflicts": [],
        "empty_cells": 51,
        "filled_cells": 30
    },
    "meta": {
        "timestamp": "2026-05-30T18:17:11.874Z",
        "request_id": "28528651-bac7-4c9f-a3e0-d34000258b58"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```


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