Caching and attribution
On this page
What never changes
| Thing | Changes? | Cache header from the API | How long to keep it |
|---|---|---|---|
Pack files (manifest, atlases, previews) under /v1/packs/{id}/{version}/ |
Never | public, max-age=31536000, immutable |
Forever |
A stored map, /v1/maps/{id}.json |
Never | private, max-age=31536000, immutable |
Forever |
A render, /v1/maps/{id}.webp or .png (same query) |
Never | private, max-age=31536000, immutable + ETag |
Forever |
Pack list /v1/packs and /v1/packs/{bare-id} |
When a new version ships | none | Minutes to a day |
/healthz, /v1/usage |
Yes | none | Don’t cache |
public means shared caches and CDNs may keep the file. private means only your own client or server should, because those responses belong to your key.
Practical patterns
- Browser apps: let the browser cache do its job; immutable files are not even revalidated. A service worker can pre-cache the atlases for the scale you use.
- Servers and bots: save each map’s JSON in your own database or storage the moment you generate it, keyed by its
id. There is no “list my maps” endpoint, and storing it yourself is faster than fetching it again. - Pack mirrors: you may download a pack version into your own static hosting or app bundle and serve it from there. Keep the version folder in the path (
ink-stone/1.1.0/…) so a newer version never overwrites an older one. - Server renders: if you serve the same image to many users, save it once and serve your copy instead of passing each request through. Ask for
.webpwhen it is shown on screen; it is about a seventh of the PNG’s size. VTTs should use.pngand cache it: renders never change. - VTT modules: ship the atlases for one scale inside the module and request only the map JSON at play time.
Attribution
The Ink Stone art is free, and in return we ask for a credit. The full rules are on the art license page (a draft until launch). The short version:
- Anywhere IsoDelve art appears publicly (a website, a shared image, a stream, a published PDF, an app screen), show “Map art by IsoDelve” linked to
https://isodelve.com, near the map or in the credits. - In print or video, where a link can’t be clicked, write “Map art by IsoDelve (isodelve.com)”. In an app, a credits or about screen with a working link is enough.
- Private use at your own table needs no credit, though it’s always appreciated.
- What you may do with the maps depends on your plan: Free and Hobby are personal and non-commercial; Creator adds commercial use in products you sell, with the credit “Maps generated with IsoDelve (isodelve.com)”; Business adds use inside software for other people.
- Additional art packs (paid plans, coming later) will carry their own license.
<p class="credit">Map art by <a href="https://isodelve.com">IsoDelve</a></p>
Next: Troubleshooting.