Map Blueprint

Tier 2 · Advanced guide

The HTTP API

Your instance can expose a small HTTP API so scripts, game engines and procedural tools can read and write whole maps, no browser needed. It's how you make Unity generate a map, back maps up on a schedule, or edit them from your own pipeline. Authentication is a single token you control.

Optional, you don't need the API to draw maps. The app works fully without it. Turn the API on only when you want to automate maps from outside the browser. It's off until you create a token.

Enabling the API

Open Settings, find Automation API and press Generate token. Copy the token somewhere safe, it's the key to your maps. You can regenerate it at any time (which instantly invalidates the old one) or disable the API entirely. If you'd rather set it from the environment, provide API_TOKEN and it takes over, the Settings field becomes read-only.

Authentication

Every request carries your token in the Authorization header. Requests without a valid token are refused. Keep the token secret, anyone who has it can read and overwrite your maps.

Authorization: Bearer YOUR_TOKEN

Base URL

Every endpoint lives under /api/v1 on your own instance, wherever you run it (for example http://localhost:8080 when running locally, or your server's domain). The examples below use https://your-instance.example.com as a stand-in, replace it with your address.

Endpoints

List maps

GET /api/v1/maps

Returns every map on the instance with its file size and last-modified time.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.example.com/api/v1/maps

Read a map

GET /api/v1/maps/{name}

Returns the full map as JSON, the same shape you get from an Export. Save it to a file, load it into Unity, or diff it in version control.

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.example.com/api/v1/maps/world -o world.json

Create or replace a map

PUT /api/v1/maps/{name}

Uploads a whole map from the JSON body. If the map is new it's created (201); if it already exists it's replaced (200). Anyone editing that map in a browser is reloaded onto the fresh version. This is how a generator, Unity, or a procedural tool writes a map back.

curl -X PUT \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data @world.json \
  https://your-instance.example.com/api/v1/maps/world

Delete a map

DELETE /api/v1/maps/{name}

Removes a map permanently. There's no undo, so back it up first with a read if you might want it again.

curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-instance.example.com/api/v1/maps/world

Rename & duplicate

POST /api/v1/maps/{name}/rename  ·  POST /api/v1/maps/{name}/duplicate

Rename a map (send { "to": "new-name" }), or copy it under a new name (send { "to": "..." }, or omit it for an automatic -copy name).

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"to":"old-world"}' \
  https://your-instance.example.com/api/v1/maps/world/rename

The map body

Reads and writes use exactly the same JSON as an Export, one object with zones, layers and layerOrder. See the map file format for every field. A write is accepted as long as it contains layers (or a legacy top-level tiles).

Errors & status codes

Errors return a small JSON object like { "error": "..." } with a matching HTTP status:

Example: fetch from Unity

A minimal C# coroutine that pulls a map into Unity with UnityWebRequest. The response text is the full map JSON, ready to parse and turn into terrain.

using UnityEngine;
using UnityEngine.Networking;
using System.Collections;

IEnumerator FetchMap(string baseUrl, string token, string name) {
    using var req = UnityWebRequest.Get($"{baseUrl}/api/v1/maps/{name}");
    req.SetRequestHeader("Authorization", "Bearer " + token);
    yield return req.SendWebRequest();
    if (req.result == UnityWebRequest.Result.Success)
        Debug.Log(req.downloadHandler.text);   // the full map JSON
    else
        Debug.LogError(req.responseCode + " " + req.error);
}

Treat the token like a password: keep it out of shared repositories and public builds, and regenerate it if it ever leaks. Because the API only reads and writes whole maps, the safest automation pattern is read, change, write back.

← Back to all documentation