# Dice API
> A fast, fully-local dice toolkit for games and simulations: roll dice notation (NdM with plus and minus modifiers, multiple dice terms like 1d8+1d6+2, and keep-highest or keep-lowest for advantage and disadvantage such as 2d20kh1), parse and validate a notation, and compute the deterministic minimum, maximum and mean of a roll. Rolls use a cryptographically secure random source. Every endpoint accepts input via the query string or the request body. Pure server-side compute, no third-party upstream, so responses are instant and always available. Ideal for tabletop and RPG tools, Discord and chat bots, virtual tabletops and game backends.

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

## Pricing
- **Free** (Free) — 19,000 calls/Mo, 4 req/s
- **Basic** ($3/Mo) — 310,000 calls/Mo, 12 req/s
- **Pro** ($10/Mo) — 1,750,000 calls/Mo, 40 req/s
- **Mega** ($28/Mo) — 9,200,000 calls/Mo, 130 req/s

## Endpoints

### Dice

#### `GET /v1/parse` — Parse a notation

**Parameters:**
- `notation` (query, required, string) — Dice notation Example: `4d6kh3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dice-api/v1/parse?notation=4d6kh3"
```

**Response:**
```json
{
    "data": {
        "terms": [
            {
                "keep": {
                    "n": 3,
                    "mode": "highest"
                },
                "sign": 1,
                "type": "dice",
                "count": 4,
                "sides": 6
            }
        ],
        "valid": true,
        "notation": "4d6kh3"
    },
    "meta": {
        "timestamp": "2026-05-30T14:35:20.270Z",
        "request_id": "44bb2eb8-6a38-4f2e-bba6-2c02a165b1d5"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/roll` — Roll a dice notation

**Parameters:**
- `notation` (query, required, string) — Dice notation Example: `3d6+2`
- `rolls` (query, optional, string) — Repeat the roll 1-100 Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dice-api/v1/roll?notation=3d6%2B2&rolls=1"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "total": 19,
        "results": [
            {
                "total": 19,
                "breakdown": [
                    {
                        "dice": "3d6",
                        "kept": [
                            6,
                            6,
                            5
                        ],
                        "rolls": [
                            6,
                            6,
                            5
                        ],
                        "subtotal": 17
                    },
                    {
                        "modifier": 2
                    }
                ]
            }
        ],
        "notation": "3d6+2"
    },
    "meta": {
        "timestamp": "2026-05-30T14:35:20.351Z",
        "request_id": "c80dddba-aa49-46dc-89c6-fc1abf6992ba"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```

#### `GET /v1/stats` — Min/max/mean of a notation

**Parameters:**
- `notation` (query, required, string) — Dice notation Example: `3d6+2`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dice-api/v1/stats?notation=3d6%2B2"
```

**Response:**
```json
{
    "data": {
        "max": 20,
        "min": 5,
        "mean": 12.5,
        "notation": "3d6+2",
        "approximate": false
    },
    "meta": {
        "timestamp": "2026-05-30T14:35:20.424Z",
        "request_id": "b65ae95c-ed0c-49f1-bb33-b41eddf0d59d"
    },
    "status": "ok",
    "message": "OK",
    "success": true
}
```


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