Cupcake ad52db8122 feat: D&D SRD 5.2 API — FastAPI app with flat JSON caching

- Data fetched from Open5e API: 3,215 items (339 spells, 330 creatures,
  24 classes, 2,319 magic items, 203 equipment)
- FastAPI app with API key auth (X-API-Key header or ?api_key= param)
- Sliding window rate limiting (60 req/min, 10K req/day)
- Dice rolling endpoint (e.g., /api/dice/roll?spec=2d20+5)
- Full-text search across all resource types
- Pagination, filtering (name, level, school, class, etc.)
- Admin CLI for API key management
- nginx + systemd service ready for deployment

2026-06-03 18:13:00 +00:00

1.8 KiB

Raw Blame History

D&D SRD 5.2 API

An open REST API for the Dungeons & Dragons 5.2 System Reference Document (SRD), served at dnd.jezzahehn.com.

Endpoints

Endpoint	Description
`GET /api`	API root — list all available resources
`GET /api/spells`	List spells (filter by name, level, school, class, etc.)
`GET /api/spells/{key}`	Get a specific spell
`GET /api/creatures`	List creatures/monsters
`GET /api/creatures/{key}`	Get a specific creature
`GET /api/classes`	List classes
`GET /api/classes/{key}`	Get a specific class
`GET /api/magic-items`	List magic items
`GET /api/magic-items/{key}`	Get a specific magic item
`GET /api/equipment`	List equipment
`GET /api/equipment/{key}`	Get specific equipment
`GET /api/dice/roll`	Roll dice (`?spec=2d20+5`)
`GET /api/search`	Search across all resources (`?q=fireball`)
`GET /api/docs`	Interactive API documentation (Swagger UI)

Authentication

Pass your API key via X-API-Key header or ?api_key= query parameter.

curl -H "X-API-Key: your-key-here" https://dnd.jezzahehn.com/api/spells

Running Locally

pip install -r requirements.txt
python scripts/fetch_data.py
uvicorn app.main:app --reload

Managing API Keys

python scripts/manage_keys.py list          # List all keys
python scripts/manage_keys.py create "name"  # Create a new key
python scripts/manage_keys.py revoke <key>   # Revoke a key

Data

Spells: 339
Creatures: 330
Classes: 24
Magic Items: 2,319
Equipment: 203
Total: 3,215 items

Data is fetched from Open5e and cached as flat JSON files in data/.

1.8 KiB Raw Blame History