IsoDelve developer guide
This guide takes you from “what is this” to drawing IsoDelve maps in your own software. It is written for developers using the IsoDelve API. If you just want maps for your own table without writing code, the Map Maker (coming soon) is the easier route.
Every request and response in this guide was run against the live API on 2026-11-14, and every code sample was checked against the API’s source code. The two drawing examples (JavaScript and Python) were tested by comparing their output with the API’s own server renders: the Python version matches pixel for pixel, the canvas version to within 2 color levels of rounding.
What you’ll build
By the end you will be able to:
- Get and protect an API key.
- Generate a dungeon with exactly the size, room count, seed and generator version you want.
- Read every field of the map document.
- Download the free Ink Stone art pack and understand its files.
- Draw a map yourself at any of the four isometric angles, or fetch a server-rendered image (WebP, or lossless PNG).
- Handle limits, errors, caching and attribution properly.
The pages
| Page | What it covers |
|---|---|
| API keys and authentication | Requesting a key, what it looks like, the Authorization header, keeping it secret |
| Endpoints | Every endpoint with real requests and responses |
| Generate parameters | Size, rooms, seed, theme, knobs, packs, pinning generator versions |
| The map JSON | Field-by-field: grid, palette, walls, doors, secret doors, props, coordinates |
| Art packs | Manifest, atlases, sprite frames, the four angles, folder layout, versioning |
| Drawing a map | Projection math, anchors, draw order, full JavaScript and Python examples |
| Limits, errors and retries | Rate limits, quotas, every error code, retry strategy |
| Caching and attribution | What to cache and for how long, the required credit |
| Troubleshooting | Common problems and fixes |
| Glossary | Every IsoDelve term in one place |
The 60-second version
# 1. Public: list art packs (no key)
curl -s https://api.isodelve.com/v1/packs
# 2. Keyed: generate a map
curl -s -X POST https://api.isodelve.com/v1/maps \
-H "Authorization: Bearer $ISODELVE_KEY" -H "Content-Type: application/json" \
-d '{"seed":"my-first-dungeon"}'
# 3. Keyed: fetch a rendered image of it (WebP; use .png for lossless), or draw it yourself from the pack
curl -s -H "Authorization: Bearer $ISODELVE_KEY" -o map.webp \
"https://api.isodelve.com/v1/maps/map_XXXXXXXXXXXXXXXX.webp?angle=iso0&scale=0.25"
What is live and what is coming later
| Feature | Status |
|---|---|
Map generation (gen-1.0.0 to gen-1.3.0, the default), stored maps, usage |
Live |
Ink Stone art pack (ink-stone@1.0.0, ink-stone@1.1.0): sprites at four angles and three scales |
Live, free |
Server-rendered images (/v1/maps/{id}.webp or .png) |
Live for testing; per-plan allowances will be published before billing |
| Self-serve signup | Live for the Free plan: create an account and get a key on your account page |
| Billing for paid plans | Coming later (waiting list) |
| Additional, paid art packs | Coming later (only Ink Stone exists) |
| 3D models (GLB) of each piece | Coming later (the files exist but the API does not serve them yet) |
| Outdoor maps, caves, texture editing | Coming later, see the roadmap |
| The Map Maker web app | Coming soon, see Map Maker |
Ready? Start with API keys and authentication.