# D&D Encounter API
> Dungeons & Dragons 5th-edition encounter-building maths as an API, computed locally and deterministically — the XP-budget and difficulty numbers a Dungeon Master balances a fight with. The budget endpoint sums the per-character XP thresholds from the DMG across the party — by party size and level, or a list of mixed levels — to give the easy, medium, hard and deadly budget for one encounter (a party of four 5th-level characters has thresholds of 1,000 / 2,000 / 3,000 / 4,400 XP), plus the total adventuring-day budget. The difficulty endpoint rates an encounter: it sums the monsters' XP, multiplies by the encounter multiplier for the number of monsters (×1.5 for two, ×2 for three to six, up to ×4 for fifteen or more), and compares the adjusted XP to the party thresholds — four 450-XP monsters against that party come to 3,600 adjusted XP, a hard fight. The carry endpoint gives the carrying capacity (Strength × 15, scaled by size), push/drag/lift and the encumbrance thresholds. Everything is computed locally and deterministically, so it is instant and private. Ideal for tabletop, virtual-tabletop, DM-tool and TTRPG app developers, encounter-builder and balance tools, and game-master education. Pure local computation — no key, no third-party service, instant. Uses the DMG tables. Live, nothing stored. 3 compute endpoints. For monster stats and spells use a D&D SRD data API.

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

## Pricing
- **Free** (Free) — 6,650 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 59,500 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 245,000 calls/Mo, 15 req/s
- **Mega** ($38/Mo) — 1,375,000 calls/Mo, 40 req/s

## Endpoints

### Encounter

#### `GET /v1/budget` — Party XP thresholds

**Parameters:**
- `party_size` (query, optional, string) — Number of characters Example: `4`
- `party_level` (query, optional, string) — Character level (1-20) Example: `5`
- `levels` (query, optional, string) — Or comma list of mixed levels Example: `3,4,5,5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dndencounter-api/v1/budget?party_size=4&party_level=5&levels=3%2C4%2C5%2C5"
```

#### `GET /v1/carry` — Carrying capacity

**Parameters:**
- `strength` (query, required, string) — Strength score Example: `15`
- `size` (query, optional, string) — tiny/small/medium/large/huge/gargantuan Example: `medium`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dndencounter-api/v1/carry?strength=15&size=medium"
```

#### `GET /v1/difficulty` — Encounter difficulty

**Parameters:**
- `party_size` (query, optional, string) — Number of characters Example: `4`
- `party_level` (query, optional, string) — Character level Example: `5`
- `levels` (query, optional, string) — Or mixed levels
- `monster_xp` (query, required, string) — Comma list of each monster XP Example: `450,450,450,450`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dndencounter-api/v1/difficulty?party_size=4&party_level=5&monster_xp=450%2C450%2C450%2C450"
```

### Meta

#### `GET /v1/meta` — Spec

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


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