{"openapi":"3.1.0","info":{"title":"D&D Encounter API","version":"1.0.0","description":"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.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/dndencounter-api","description":"oanor gateway"}],"tags":[{"name":"Encounter"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/budget":{"get":{"operationId":"get_v1_budget","tags":["Encounter"],"summary":"Party XP thresholds","description":"","parameters":[{"name":"party_size","in":"query","required":false,"description":"Number of characters","schema":{"type":"string"},"example":"4"},{"name":"party_level","in":"query","required":false,"description":"Character level (1-20)","schema":{"type":"string"},"example":"5"},{"name":"levels","in":"query","required":false,"description":"Or comma list of mixed levels","schema":{"type":"string"},"example":"3,4,5,5"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/carry":{"get":{"operationId":"get_v1_carry","tags":["Encounter"],"summary":"Carrying capacity","description":"","parameters":[{"name":"strength","in":"query","required":true,"description":"Strength score","schema":{"type":"string"},"example":"15"},{"name":"size","in":"query","required":false,"description":"tiny/small/medium/large/huge/gargantuan","schema":{"type":"string"},"example":"medium"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/difficulty":{"get":{"operationId":"get_v1_difficulty","tags":["Encounter"],"summary":"Encounter difficulty","description":"","parameters":[{"name":"party_size","in":"query","required":false,"description":"Number of characters","schema":{"type":"string"},"example":"4"},{"name":"party_level","in":"query","required":false,"description":"Character level","schema":{"type":"string"},"example":"5"},{"name":"levels","in":"query","required":false,"description":"Or mixed levels","schema":{"type":"string"}},{"name":"monster_xp","in":"query","required":true,"description":"Comma list of each monster XP","schema":{"type":"string"},"example":"450,450,450,450"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Spec","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":6650,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":420,"monthly_call_quota":59500,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":1170,"monthly_call_quota":245000,"rps_limit":15,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":3750,"monthly_call_quota":1375000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/dndencounter-api"}