IsoDelve

Home › Developer guide › Endpoints, with real requests and responses

Endpoints, with real requests and responses

Developer guide · updated

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, renders and links differ. 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 id added first and renders and links added 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=full draws 10 ft walls as generated; walls=auto lowers only the walls standing in front of floor from that angle.
  • secrets=show is the GM view: every secret door is drawn as a full-height secret door, even with short walls. secrets=hide makes 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-Cache is miss for a fresh render, hit when served from the cache, and shared when 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 at scale=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: 400 for a bad angle, scale, walls, bg or secrets, .jpg, or any quality parameter (with field), 403 plan_limit for a scale above your plan, 402 allowance_exceeded, 429 rate_limited, 422 pack_incomplete if 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.