Endpoints, with real requests and responses
Base URL: https://api.isodelve.com. All responses are JSON unless noted. The /v1 API only ever gains fields; it never removes or renames them.
| Method | Path | Key | Purpose |
|---|---|---|---|
| GET | /healthz |
No | Is the API up, and which generator is current |
| GET | /v1/packs |
No | List art packs and versions |
| GET | /v1/packs/{id} or /v1/packs/{id}@{x.y.z} |
No | One pack’s manifest plus baseUrl |
| GET | /v1/packs/{id}/{version}/manifest.json |
No | The manifest file itself |
| GET | /v1/packs/{id}/{version}/atlases/{facing}/{scale}/atlas-{n}.png and .json |
No | Sprite sheets and their frame data |
| GET | /v1/packs/{id}/{version}/previews/{file} |
No | Pack preview images (Ink Stone ships none yet, so this returns 404 today) |
| POST | /v1/maps (alias /v1/maps/generate) |
Yes | Generate and store a map |
| GET | /v1/maps/{id}.json |
Yes | Fetch a stored map |
| GET | /v1/maps/{id}.webp or .png |
Yes | Server-rendered image of a stored map (WebP recommended, PNG lossless) |
| GET | /v1/usage |
Yes | This month’s usage for your key |
JSON responses of 1 KB or more are sent Brotli- or gzip-compressed when your client allows it (browsers and most HTTP libraries do it automatically; with curl, add --compressed). A map is about seven times smaller on the wire.
Every response carries Access-Control-Allow-Origin: * and exposes the Retry-After and X-IsoDelve-Cache headers to browsers.
GET /healthz
curl -s https://api.isodelve.com/healthz
{"ok":true,"generatorVersion":"gen-1.3.0","generators":[{"version":"gen-1.0.0","status":"stable"},{"version":"gen-1.1.0","status":"stable"},{"version":"gen-1.2.0","status":"stable"},{"version":"gen-1.3.0","status":"default"}]}
generatorVersion is the default generator used when a request doesn’t pin one. generators lists every version you can pin: stable versions never change, and neither does the default once released. A preview version (none today) may still change until it is released.
GET /v1/packs
curl -s https://api.isodelve.com/v1/packs
{
"packs": [
{ "id": "ink-stone", "version": "1.0.0", "ref": "ink-stone@1.0.0", "name": "Ink Stone",
"license": "LicenseRef-IsoDelve-TBD", "pieces": 91,
"manifest": "https://api.isodelve.com/v1/packs/ink-stone/1.0.0/manifest.json" },
{ "id": "ink-stone", "version": "1.1.0", "ref": "ink-stone@1.1.0", "name": "Ink Stone",
"license": "LicenseRef-IsoDelve-TBD", "pieces": 91,
"manifest": "https://api.isodelve.com/v1/packs/ink-stone/1.1.0/manifest.json" }
]
}
Packs are sorted by id, then version. (ink-stone@1.0.0 currently reports 91 pieces; it is meant to hold the original 66 and will be corrected. Use ink-stone@1.1.0 for new maps.)
GET /v1/packs/{ref}
{ref} is ink-stone@1.1.0 for an exact version or plain ink-stone for the newest. The response is the whole manifest plus baseUrl, the folder all the pack’s relative file paths hang off:
curl -s https://api.isodelve.com/v1/packs/ink-stone@1.1.0
{
"specVersion": "isodelve-kit-1", "id": "ink-stone", "version": "1.1.0", "name": "Ink Stone",
"license": "LicenseRef-IsoDelve-TBD", "units": "meters", "upAxis": "Y (glTF)",
"grid": { "cellM": 1.524, "cellFt": 5 },
"facings": ["iso0", "iso90", "iso180", "iso270"],
"sprite": { "cellPx": [256, 128], "pxPerFoot": 31.35, "scales": [1, 0.5, 0.25], "frames": { "…": "…" } },
"atlases": [ { "facing": "iso0", "scale": 1, "image": "atlases/iso0/1/atlas-0.png", "data": "atlases/iso0/1/atlas-0.json", "w": 2048, "h": 3888 }, "… 24 in total …" ],
"pieces": [ { "id": "floor.slab.a", "kind": "floor", "weight": 4, "model": "models/floor.slab.a.glb" }, "… 91 in total …" ],
"baseUrl": "https://api.isodelve.com/v1/packs/ink-stone/1.1.0/"
}
An unknown pack returns 404 {"error":{"code":"pack_not_found",…}}. The art packs page explains every manifest field.
Pack files
B=https://api.isodelve.com/v1/packs/ink-stone/1.1.0
curl -s -o manifest.json $B/manifest.json
curl -s -o atlas-0.json $B/atlases/iso0/0.5/atlas-0.json
curl -s -o atlas-0.png $B/atlases/iso0/0.5/atlas-0.png
Pack files are served with Cache-Control: public, max-age=31536000, immutable, because a published pack version never changes. Only the manifest, atlases and previews are served; anything else under the pack folder, including the 3D models listed in the manifest, returns 404 {"error":{"code":"not_found","message":"not a served pack file"}} in phase 1 (3D comes later).
POST /v1/maps
Generates a map, stores it under a new id and returns it. The body is JSON, at most 16 KB, and every field is optional (see Generate parameters).
curl -s -i -X POST https://api.isodelve.com/v1/maps \
-H "Authorization: Bearer $ISODELVE_KEY" -H "Content-Type: application/json" \
-d '{"seed":"guide-six-rooms","size":{"w":36,"h":30},"rooms":{"min":6,"max":6},"knobs":{"secretRooms":0,"decay":0,"clutter":0.3}}'
Real response (headers trimmed, body shortened; captured when gen-1.2.0 was the default, so the same request now returns a gen-1.3.0 map unless you pin "generatorVersion": "gen-1.2.0"):
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.isodelve.com/v1/maps/map_j98k2wr918byp4vt.json
{
"id": "map_j98k2wr918byp4vt",
"format": "isodelve-map@1",
"generatorVersion": "gen-1.2.0",
"seed": "guide-six-rooms",
"pack": "ink-stone@1.1.0",
"type": "inside-dungeon",
"theme": "crypt",
"params": { "type": "inside-dungeon", "pack": "ink-stone@1.1.0", "theme": "crypt", "size": { "w": 36, "h": 30 },
"rooms": { "min": 6, "max": 6 },
"knobs": { "loopiness": 0.2, "propDensity": 0.5, "require": ["entrance", "boss", "treasure"],
"secretRooms": 0, "decay": 0, "clutter": 0.3 },
"seed": "guide-six-rooms" },
"grid": { "…": "…" }, "rooms": [ "… 6 rooms: entrance, tomb, shrine, boss, treasure, guard …" ],
"corridors": [ "…" ], "doors": [ "… 10 …" ], "props": [ "… 28 …" ], "lights": [ "…" ], "paths": { "…": "…" }, "stats": { "…": "…" },
"renders": {
"iso0": "https://api.isodelve.com/v1/maps/map_j98k2wr918byp4vt.png?angle=iso0",
"iso90": "…?angle=iso90", "iso180": "…?angle=iso180", "iso270": "…?angle=iso270"
},
"links": { "self": "https://api.isodelve.com/v1/maps/map_j98k2wr918byp4vt.json" }
}
Things worth knowing:
- Every call creates a new stored map with a new id, even with the same seed and settings. The map content is identical for identical inputs; only
id,rendersandlinksdiffer. If you need the same map again, fetch it by id or store the JSON yourself instead of generating it again. - The body is the map document with
idadded first andrendersandlinksadded last. The document bytes in between are exactly what the generator produced. - Each successful call counts as one map in
/v1/usage. - Failed calls (4xx) do not create a map.
GET /v1/maps/{id}.json
curl -s -H "Authorization: Bearer $ISODELVE_KEY" \
https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.json
Returns the same JSON as the generate call (200, Cache-Control: private, max-age=31536000, immutable). A stored map never changes.
Maps belong to the key that created them. Any other key, or an id that doesn’t exist, gets (real response):
HTTP/1.1 404 Not Found
{"error":{"code":"map_not_found","message":"no such map for this key"}}
There is no endpoint that lists your maps; keep the ids (or the JSON) you care about.
Only the parts you need: ?fields=
Add ?fields= to this call or to POST /v1/maps to get only some sections of the map. List any of type, theme, params, orientation, grid, rooms, corridors, doors, props, lights, paths, clues and stats, separated by commas. id, format, generatorVersion, seed, pack, renders and links are always included.
curl -s --compressed -H "Authorization: Bearer $ISODELVE_KEY" \
"https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.json?fields=rooms,doors"
The grid is usually more than half of a map, so a room-and-door list for a sidebar or clue tracker is much smaller. An unknown name is a 400 with "field": "fields".
GET /v1/maps/{id}.webp (or .png)
A finished image, composited on the server from the same pack sprites your own code would use. WebP is the recommended format; change the extension to .png for the lossless picture (see Image formats below).
curl -s -H "Authorization: Bearer $ISODELVE_KEY" -o map.webp \
"https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.webp?angle=iso90&scale=0.5&bg=parchment"
| Query | Values | Default |
|---|---|---|
angle |
iso0, iso90, iso180, iso270 |
iso0 |
scale |
1, 0.5, 0.25 (capped by plan) |
0.25 |
walls |
cutaway, full, auto |
cutaway |
bg |
parchment, transparent |
parchment |
secrets |
show, hide |
show |
walls=cutaway(short walls, the default) draws every wall at 3 ft, so you can see into every room from any angle. Doors, arches and portcullises keep their full height.walls=fulldraws 10 ft walls as generated;walls=autolowers only the walls standing in front of floor from that angle.secrets=showis the GM view: every secret door is drawn as a full-height secret door, even with short walls.secrets=hidemakes a player handout: only what the players can reach from the entrance without passing a secret door. Each secret door is drawn as plain wall, and everything behind it (secret rooms, caches, passages, with their props and lights) is left out. The GM and player images of the same map are the same size, with the map in the same place, so you can stack them as layers.
Real response headers for a first request:
HTTP/1.1 200 OK
Content-Type: image/png
Cache-Control: private, max-age=31536000, immutable
ETag: "0cd12fcecc9f22c015e15a4169609e7f"
X-IsoDelve-Cache: miss
Content-Length: 1106384
X-IsoDelve-Cacheismissfor a fresh render,hitwhen served from the cache, andsharedwhen your request joined an identical render already in progress.- Only fresh renders count against your monthly render allowance and render rate limit. Cache hits are free.
- Size guide from real PNG renders of a 30 × 24 map: about 1.1 MB at
scale=0.25(1360 × 740 px) and about 4 MB atscale=0.5(2448 × 1592 px). Full scale is about four times the pixels of half scale. WebP is about a seventh of that. - Each combination of options is cached separately, and the cache key includes the renderer version, so a renderer update never serves an old picture.
- Errors:
400for a badangle,scale,walls,bgorsecrets,.jpg, or anyqualityparameter (withfield),403 plan_limitfor a scale above your plan,402 allowance_exceeded,429 rate_limited,422 pack_incompleteif the map’s pack no longer has every piece.
Image formats
| Extension | What it is | Use it for |
|---|---|---|
.webp |
Recommended. Quality 85, keeps transparency, about 1/7 the size of the PNG | Anything shown on screen: web pages, apps, chat bots, previews |
.png |
Lossless, the reference picture | VTTs (the best presentation), editing, printing, comparing |
Measured on a 48 × 40 map at scale=0.25. PSNR measures how close the picture is to the PNG; above 40 dB is very hard to tell apart.
| Format | Size | Of the PNG | PSNR |
|---|---|---|---|
| PNG | 1.57 MB | 100% | exact |
| WebP (quality 85) | 220 KB | 14% | 41.9 dB |
WebP quality is fixed at 85 and can’t be changed. Lower settings and JPEG blurred the ink lines, so they aren’t offered: .jpg and any quality parameter return 400. The renders links in a map, and the .png URL, stay PNG, so code that already uses them keeps working. Each format is cached separately.
Server renders are live for testing; per-plan render allowances will be published before billing launches. Drawing the map yourself (see Drawing a map) costs nothing per map.
GET /v1/usage
curl -s -H "Authorization: Bearer $ISODELVE_KEY" https://api.isodelve.com/v1/usage
{"month":"2026-11","plan":"dev","maps":5,"renders":6,"rendersAllowance":null}
month is the UTC calendar month the counters belong to. maps counts successful generate calls and renders counts fresh PNG renders. Next: Generate parameters.