IsoDelve

Home › API docs

API docs and quickstart

The IsoDelve API is a small REST API. You need a base URL and an API key, and one request returns a complete map. Pack listings and pack files are public; maps and renders need a key. Every example on this page was run against the live API, and the responses shown are real (trimmed where noted).

Base URL today: https://api.isodelve.com. Free API keys are self-serve: create a free account and get your key on the account page. For the full step-by-step wiki (every endpoint and parameter, the map JSON field by field, art packs, drawing maps in JavaScript and Python, limits and troubleshooting), read the developer guide.

Quickstart

1. See which art packs exist (no key needed)

curl -s https://api.isodelve.com/v1/packs
{
  "packs": [
    { "id": "ink-stone", "version": "1.1.0", "ref": "ink-stone@1.1.0", "name": "Ink Stone",
      "pieces": 91, "manifest": "https://api.isodelve.com/v1/packs/ink-stone/1.1.0/manifest.json", … },
    …
  ]
}

2. Generate a map

Send your key as Authorization: Bearer <key>. Keys start with iso_live_ or iso_test_. Keep them on your server, never in browser code.

export ISODELVE_KEY=iso_live_...   # your key; keep it server-side

curl -s -X POST https://api.isodelve.com/v1/maps \
  -H "Authorization: Bearer $ISODELVE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pack":"ink-stone@1.1.0","seed":"my-first-dungeon","size":{"w":30,"h":24}}'

The API answers 201 Created with the map document. On Windows PowerShell, use curl.exe with the same arguments.

3. Fetch a rendered image (optional)

curl -s -H "Authorization: Bearer $ISODELVE_KEY" -o map.webp \
  "https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.webp?angle=iso90&scale=0.5"

Or draw the map yourself from the cached art pack, which costs nothing per map.

JavaScript (Node 18+ or any server)

const BASE = "https://api.isodelve.com";
const auth = { Authorization: `Bearer ${process.env.ISODELVE_KEY}` };

const res = await fetch(`${BASE}/v1/maps`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ pack: "ink-stone@1.1.0", seed: "my-first-dungeon" }),
});
if (!res.ok) throw new Error((await res.json()).error.message); // 401, 402, 429…
const map = await res.json();            // grid, rooms, doors, props, lights, paths
const png = await fetch(map.renders.iso0, { headers: auth }); // optional server render

The map document

This is the real response to the request above, with long arrays shortened. The full document is about 16 KB (under 2 KB gzipped). The article Reading an IsoDelve map file explains every field.

{
  "id": "map_1t2nde66019682yc",
  "format": "isodelve-map@1",
  "generatorVersion": "gen-1.2.0",
  "seed": "my-first-dungeon",
  "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": 30,
      "h": 24
    },
    "rooms": {
      "min": 4,
      "max": 5
    },
    "knobs": {
      "loopiness": 0.2,
      "propDensity": 0.5,
      "require": [
        "entrance",
        "boss",
        "treasure"
      ],
      "secretRooms": 1,
      "decay": 0.3,
      "clutter": 0.5
    },
    "seed": "my-first-dungeon"
  },
  "grid": {
    "w": 30,
    "h": 24,
    "cellFt": 5,
    "palette": [
      "",
      "floor.slab.a",
      "floor.slab.d",
      "floor.cracked.a",
      "floor.slab.b",
      "floor.slab.c",
      "…"
    ],
    "floor": [
      "… 720 palette indexes …"
    ],
    "floorRot": [
      "…"
    ],
    "edgeH": [
      "… 750 …"
    ],
    "edgeV": [
      "… 744 …"
    ],
    "vertex": [
      "… 775 …"
    ],
    "vertexRot": [
      "…"
    ]
  },
  "rooms": [
    {
      "id": "r1",
      "type": "treasure",
      "bounds": [
        10,
        1,
        3,
        3
      ],
      "doors": [
        "d7",
        "d9",
        "d11"
      ],
      "contents": [
        "prop.chest.a",
        "prop.bookshelf.a",
        "prop.chest.a"
      ]
    },
    {
      "id": "r2",
      "type": "entrance",
      "bounds": [
        26,
        2,
        3,
        4
      ],
      "doors": [
        "d1"
      ],
      "contents": [
        "prop.stairs-up.a",
        "light.torch.a",
        "prop.crate.a"
      ]
    },
    {
      "…": "4 more rooms"
    }
  ],
  "corridors": [
    {
      "id": "c1",
      "connects": [
        "r2",
        "r3"
      ],
      "cells": [
        [
          27,
          6
        ],
        [
          27,
          7
        ]
      ]
    },
    {
      …
    }
  ],
  "doors": [
    {
      "id": "d1",
      "edge": {
        "x": 27,
        "y": 6,
        "dir": "h"
      },
      "piece": "portal.arch.open",
      "between": [
        "r2",
        "c1"
      ],
      "state": "open",
      "locked": false
    },
    {
      "id": "d11",
      "edge": {
        "x": 10,
        "y": 2,
        "dir": "v"
      },
      "piece": "portal.secret.closed",
      "between": [
        "r1",
        "s1"
      ],
      "state": "secret",
      "locked": false,
      "secret": true,
      "trigger": {
        "piece": "prop.bookshelf.a",
        "cell": [
          10,
          1
        ]
      }
    },
    {
      …
    }
  ],
  "props": [
    {
      "piece": "prop.chest.a",
      "at": [
        12,
        3
      ],
      "rot": 2,
      "room": "r1"
    },
    {
      "piece": "prop.bookshelf.a",
      "at": [
        10,
        1
      ],
      "rot": 3,
      "room": "r1"
    },
    {
      "…": "33 more props"
    }
  ],
  "lights": [
    {
      "at": [
        28.5,
        4.5
      ],
      "radiusFt": 20,
      "color": "#ffb46b",
      "piece": "light.torch.a"
    },
    {
      …
    }
  ],
  "paths": {
    "critical": [
      "r2",
      "r3",
      "r1",
      "r4"
    ],
    "branches": [
      [
        "r3",
        "r5"
      ]
    ],
    "deadEnds": [],
    "secret": [
      [
        "r1",
        "s1"
      ]
    ],
    "breaches": []
  },
  "stats": {
    "attempts": 1,
    "floorCells": 200
  },
  "renders": {
    "iso0": "https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.png?angle=iso0",
    "iso90": "https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.png?angle=iso90",
    "iso180": "https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.png?angle=iso180",
    "iso270": "https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.png?angle=iso270"
  },
  "links": {
    "self": "https://api.isodelve.com/v1/maps/map_1t2nde66019682yc.json"
  }
}

Endpoints

MethodPathKeyReturns
GET/healthzNo{ ok, generatorVersion, generators } (every version with its status: default, stable or preview)
GET/v1/packsNoAll art packs and versions
GET/v1/packs/{id}@{x.y.z}NoA pack manifest plus baseUrl for its sprite atlases
POST/v1/maps (alias /v1/maps/generate)YesA new map document (body up to 16 KB)
GET/v1/maps/{id}.jsonYesA stored map
GET/v1/maps/{id}.webp or .pngYesA server-composited image: WebP (recommended, quality 85) or lossless PNG, cached after the first request
GET/v1/usageYesThis month's maps and renders for your key

Generate request body

Every field is optional. Send only what you want to pin.

{
  "pack": "ink-stone@1.1.0",        // bare "ink-stone" = newest; omitted = the generator's default
  "seed": "crypt-7",                // string or number; omitted = random, returned in the map
  "theme": "crypt",
  "size": { "w": 30, "h": 24 },     // squares per side, 12 to 64 (capped by plan)
  "rooms": { "min": 4, "max": 5 },
  "knobs": {
    "loopiness": 0.2, "propDensity": 0.5, "require": ["entrance", "boss", "treasure"],
    "secretRooms": 1,               // 0 to 3 hidden rooms (default 1)
    "decay": 0.3,                   // 0 pristine to 1 ruin (default 0.3)
    "clutter": 0.5,                 // 0 sparse to 1 busy furniture groups (default 0.5)
    "secretDoors": 0.15,            // gen-1.3.0+: bookshelf doors, hallway caches, secret passages (0 to 1)
    "secrets": true,                // gen-1.3.0+: false = no secret rooms, caches, passages or secret doors at all
    "props": true                   // gen-1.3.0+: false = no props (only the entrance stairs)
  },
  "generatorVersion": "gen-1.3.0"   // the default; pin an older version to keep its maps
}

PNG options

Generator versions and packs

Same seed, parameters, generator version and pack always give the same map. Older generator versions stay callable, so stored maps never change.

GeneratorDefault packWhat changed
gen-1.0.0ink-stone@1.0.0Launch generator
gen-1.1.0ink-stone@1.0.0Required props unique per room; feast table and dais kept clear of doors
gen-1.2.0ink-stone@1.1.0Secret rooms, wall decay and breaches, broken props, furniture groups and secret-door triggers
gen-1.3.0 (default)ink-stone@1.1.0Bookshelf doors, hallway caches, secret passages (knobs.secretDoors), doors[].opens, and on/off switches knobs.secrets and knobs.props. Output may still change until it becomes the default.

Art packs are immutable once published. ink-stone@1.1.0 has 91 pieces, each rendered at four angles and three scales.

Errors and limits

Errors always look like { "error": { "code", "message", "field"? } }. A request without a key, for example:

HTTP/1.1 401 Unauthorized
{"error":{"code":"unauthorized","message":"send Authorization: Bearer iso_test_... or iso_live_..."}}
StatusCodeMeaning
400bad_request, bad_json, pack_not_foundFix the request
401unauthorizedMissing or wrong key
402allowance_exceededMonthly allowance used up
403plan_limitThe request is bigger than your plan allows
413too_largeBody over 16 KB
422generation_failed, pack_incompleteThe map could not be built with that pack or settings
429rate_limitedSlow down; see the Retry-After header

Monthly allowances and rate limits per plan are on the pricing page.

Drawing maps yourself

Each pack manifest lists sprite atlases per angle and scale (atlases/iso0/0.5/atlas-0.png plus a JSON file with every sprite's position and anchor). Download them once, cache them, and place sprites by palette id. Floors are 256 × 176 px frames at full scale and walls, doors and props 256 × 512 px, all anchored so a piece lands on its cell. Rotating the map means switching to the next angle's atlases. The free Ink Stone license covers using these sprites to display IsoDelve maps.