# 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" ``` **Response:** ```json { "data": { "note": "Per-character XP thresholds (DMG) summed across the party set the easy/medium/hard/deadly budget for one encounter. The daily XP budget is the total adventuring-day allowance.", "inputs": { "levels": [ 3, 4, 5, 5 ], "party_size": 4 }, "xp_thresholds": { "easy": 700, "hard": 2100, "deadly": 3100, "medium": 1400 }, "daily_xp_budget": 9900 }, "meta": { "timestamp": "2026-06-06T07:14:07.612Z", "request_id": "d1176ae5-cd47-4ff6-abad-fc02a21ebcb8" }, "status": "ok", "message": "XP budget", "success": true } ``` #### `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" ``` **Response:** ```json { "data": { "note": "Carrying capacity = Strength × 15 (× size). Push/drag/lift is double that. The optional encumbrance variant flags speed penalties at ×5 and ×10 Strength.", "inputs": { "size": "medium", "strength": 15 }, "push_drag_lift": 450, "encumbered_over": 75, "carrying_capacity": 225, "heavily_encumbered_over": 150 }, "meta": { "timestamp": "2026-06-06T07:14:07.697Z", "request_id": "184d7c77-7f0c-41ec-a85b-f753c737bcd7" }, "status": "ok", "message": "Carrying capacity", "success": true } ``` #### `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" ``` **Response:** ```json { "data": { "note": "Adjusted XP = total monster XP × the count multiplier (1.5 for two, 2 for 3–6, up to 4 for 15+). Compare to the party thresholds for the difficulty. XP for the reward is the unadjusted total.", "inputs": { "levels": [ 5, 5, 5, 5 ], "party_size": 4, "monster_count": 4 }, "difficulty": "hard", "multiplier": 2, "adjusted_xp": 3600, "xp_thresholds": { "easy": 1000, "hard": 3000, "deadly": 4400, "medium": 2000 }, "total_monster_xp": 1800 }, "meta": { "timestamp": "2026-06-06T07:14:07.795Z", "request_id": "6251dd74-f20a-41f1-8300-4d02ce3fa685" }, "status": "ok", "message": "Encounter difficulty", "success": true } ``` ### Meta #### `GET /v1/meta` — Spec **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/dndencounter-api/v1/meta" ``` **Response:** ```json { "data": { "notes": "Party as party_size + party_level, or a 'levels' list for mixed parties (1–20). Monster XP as a comma list. Uses the DMG thresholds and encounter multipliers.", "service": "dndencounter-api", "endpoints": { "GET /v1/meta": "This document.", "GET /v1/carry": "Carrying capacity, push/drag/lift and encumbrance from Strength and size.", "GET /v1/budget": "Easy/medium/hard/deadly XP thresholds and the daily budget for a party.", "GET /v1/difficulty": "Adjusted XP and difficulty rating for a set of monsters vs a party." }, "description": "D&D 5e encounter maths: party XP thresholds, encounter difficulty with the monster-count multiplier, and carrying capacity." }, "meta": { "timestamp": "2026-06-06T07:14:07.890Z", "request_id": "33022ed8-44cb-4ff8-8b27-9b487e6c79d2" }, "status": "ok", "message": "Meta", "success": true } ``` --- Marketplace page: https://www.oanor.com/api/dndencounter-api OpenAPI spec: https://www.oanor.com/api/dndencounter-api/openapi.json