Maps | Dezfil

`/api/maps`

GETList maps

Sign-in Session cookie or Bearer tokenMCP tool list_maps

A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing.

Parameters

projectQuery
Narrow to one project's members by project id: any project the caller reaches, its own or one shared with it, whoever owns what is filed there; "none" narrows to the caller's own items filed in no project at all (one still filed in a project the caller no longer reaches is not none). Omitted, everything the caller reaches answers. An unknown or unreached project is not found, never an empty list.
string

Responses

200
Success.
application/json
MapList
401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways GET, HEAD, OPTIONS, POST

Examples

List the maps of a new account

Needs a token. A new account reaches no map yet.

curl

curl -s http://localhost:3000/api/maps \
  -H "Authorization: Bearer <YOUR_TOKEN>"

JavaScript

const response = await fetch("http://localhost:3000/api/maps", {
  headers: { Authorization: "Bearer <YOUR_TOKEN>" },
});
console.log(JSON.stringify(await response.json(), null, 2));

Answers 200 application/json

[]

List the maps once World cities exists

Needs a token. Lists the quickstart's map after its basemap changed and it was unpublished.

curl

curl -s http://localhost:3000/api/maps \
  -H "Authorization: Bearer <YOUR_TOKEN>"

JavaScript

const response = await fetch("http://localhost:3000/api/maps", {
  headers: { Authorization: "Bearer <YOUR_TOKEN>" },
});
console.log(JSON.stringify(await response.json(), null, 2));

Answers 200 application/json

[
  {
    "id": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34",
    "name": "World cities",
    "viewport": {
      "lng": 0,
      "lat": 40,
      "zoom": 1.3,
      "pitch": 0,
      "bearing": 0
    },
    "basemap": "light",
    "customBasemap": null,
    "basemapLayers": null,
    "note": null,
    "legendCorner": null,
    "legendOrder": null,
    "timeline": null,
    "widgets": [],
    "widgetsPublished": true,
    "publishToken": null,
    "publishedAt": null,
    "published": false,
    "createdAt": "2026-10-20T09:00:01.507Z",
    "updatedAt": "2026-10-20T09:00:01.530Z",
    "editRevision": "2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c",
    "lastChangedAt": "2026-10-20T09:00:01.530Z",
    "lastChangedBy": {
      "name": "Ana Diaz",
      "sqlName": "ana_diaz"
    },
    "projectId": null,
    "owner": {
      "name": "Ana Diaz",
      "sqlName": "ana_diaz"
    },
    "home": "ana_diaz",
    "layerCount": 1,
    "layerColors": [
      "rgba(18, 147, 154, 1)"
    ],
    "pictureState": "waiting",
    "pictureVersion": null,
    "hasThumbnail": false,
    "thumbnailBasemap": null
  }
]

POSTCreate a map

Sign-in Session cookie or Bearer tokenMCP tool create_map

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Optionally filed into a project at birth: an unknown project refuses and creates nothing. A new map takes the instance's defaults for its basemap, starting view and legend corner (defaults in the runtime configuration).

Request body (optional)

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

namestring
projectIdstringor null
The project the new map joins; omitted or null, it starts unfiled. It must be a project the caller owns or edits, whose owner is active: one the caller only views refuses with forbidden, and one they cannot reach refuses as an unknown one.

Responses

201
Created.
application/json
MapCreated
401403404413503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways GET, HEAD, OPTIONS, POST

Example

Create the map World cities

Needs a token. The answer's editRevision is what the next change to the map sends.

curl

curl -s http://localhost:3000/api/maps \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "World cities"}'

JavaScript

const response = await fetch("http://localhost:3000/api/maps", {
  method: "POST",
  headers: {
    Authorization: "Bearer <YOUR_TOKEN>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "World cities" }),
});
console.log(JSON.stringify(await response.json(), null, 2));

Answers 201 application/json

{
  "id": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34",
  "name": "World cities",
  "viewport": {
    "lng": 0,
    "lat": 40,
    "zoom": 1.3
  },
  "basemap": null,
  "customBasemap": null,
  "basemapLayers": null,
  "note": null,
  "legendCorner": null,
  "legendOrder": null,
  "timeline": null,
  "widgets": [],
  "widgetsPublished": true,
  "publishToken": null,
  "publishedAt": null,
  "published": false,
  "createdAt": "2026-10-20T09:00:01.507Z",
  "updatedAt": "2026-10-20T09:00:01.507Z",
  "editRevision": "4f1c9a7e2b0d4c6e8a1f3b5d7c9e0a2b",
  "lastChangedAt": "2026-10-20T09:00:01.507Z",
  "lastChangedBy": {
    "name": "Ana Diaz",
    "sqlName": "ana_diaz"
  },
  "projectId": null,
  "owner": {
    "name": "Ana Diaz",
    "sqlName": "ana_diaz"
  },
  "home": "ana_diaz"
}

HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS, POST
Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

`/api/maps/{id}/transfer`

POSTTransfer a map to someone who reaches it

Sign-in Session cookie or Bearer tokenMCP tool transfer_map

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Transfer is the only change of ownership any operation makes, and it is always the current owner's own act. The new owner is named by their SQL name and must be an active account. The owner's authority, the recipient, the ownership change and everything that moves with it commit together, or nothing changes. Datasets and connections have no transfer. Makes another active person who already reaches the map its owner: the owner of the project it is filed in, or one of that project's people. An unfiled map is refused with invalid_request: file the map in a project first. The map keeps its SQL home, so its SQL means what it meant, and it keeps its layers, history, card images and its publication, which becomes the new owner's and renders with the new owner's reach: a dataset the new owner cannot reach fails on the link rather than drawing anything else. Anyone else who reaches it is refused with forbidden. A recipient who is deactivated, not yet redeemed, unknown, the owner, or does not reach it is refused with invalid_request, and nothing changes. Answers the map's identity and its new owner.

Parameters

X-Edit-RevisionHeaderrequired
Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.
stringpattern ^[0-9a-f]{32}$
Opaque durable revision paired with this document state. Camera and derived writes do not change it.
idPathrequired
Map id.
string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

tostringrequiredmin length 1
The new owner's SQL name.

Responses

200
Success.
application/json
DocumentTransfer
400401403404409413503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

`/api/basemap/inspect`

POSTInspect a custom basemap style URL

Sign-in Session cookie or Bearer tokenMCP tool inspect_basemap_style

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. One bounded fetch through the egress policy, answering valid | not_style | unreachable | blocked with a summary and attribution preview. Advisory: the map write re-inspects before saving. Verdicts are 200s — a dead URL is a normal thing to ask about.

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

urlstringrequired

Responses

200
Success.
application/json
StyleInspection
401403413503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

`/api/maps/{id}`

GETRead a map with its layers

Sign-in Session cookie or Bearer tokenMCP tool get_map

A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing.

Parameters

idPathrequired
Map id.
string

Responses

200
Success.
application/json
MapWithLayers
401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways DELETE, GET, HEAD, OPTIONS, PATCH

Examples

Read the published map with its layer

Needs a token and the map World cities, published. The answer carries the editRevision the next change sends.

curl

curl -s http://localhost:3000/api/maps/2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34 \
  -H "Authorization: Bearer <YOUR_TOKEN>"

JavaScript

const response = await fetch("http://localhost:3000/api/maps/2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", {
  headers: { Authorization: "Bearer <YOUR_TOKEN>" },
});
console.log(JSON.stringify(await response.json(), null, 2));

Answers 200 application/json

{
  "id": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34",
  "name": "World cities",
  "viewport": {
    "lng": 0,
    "lat": 40,
    "zoom": 1.3,
    "pitch": 0,
    "bearing": 0
  },
  "basemap": null,
  "customBasemap": null,
  "basemapLayers": null,
  "note": null,
  "legendCorner": null,
  "legendOrder": null,
  "timeline": null,
  "widgets": [],
  "widgetsPublished": true,
  "publishToken": "<PUBLISH_TOKEN>",
  "publishedAt": "2026-10-20T09:00:01.521Z",
  "published": true,
  "createdAt": "2026-10-20T09:00:01.507Z",
  "updatedAt": "2026-10-20T09:00:01.521Z",
  "editRevision": "9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90",
  "lastChangedAt": "2026-10-20T09:00:01.521Z",
  "lastChangedBy": {
    "name": "Ana Diaz",
    "sqlName": "ana_diaz"
  },
  "layers": [
    {
      "id": "9b1c4e7f-2a5d-4c83-8f06-3e7a1b9d5c20",
      "mapId": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34",
      "name": "Big cities",
      "sql": "SELECT name, population, geometry FROM world_cities WHERE population > 10000000",
      "style": {
        "fill": {
          "type": "constant",
          "color": {
            "r": 18,
            "g": 147,
            "b": 154,
            "a": 1
          }
        },
        "fillOpacity": 0.72,
        "stroke": {
          "r": 12,
          "g": 16,
          "b": 24,
          "a": 1
        },
        "strokeOpacity": 0.85,
        "strokeWidth": 0,
        "pointRadius": 3,
        "opacity": 1
      },
      "visible": true,
      "tooltip": null,
      "popup": null,
      "publishedFields": null,
      "inLegend": true,
      "viz": {
        "type": "points"
      },
      "filters": [],
      "legendTitle": null,
      "legendLabels": null,
      "legendAttrs": null,
      "ordinal": 0,
      "createdAt": "2026-10-20T09:00:01.515Z",
      "updatedAt": "2026-10-20T09:00:01.515Z",
      "editRevision": "9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90",
      "lastChangedAt": "2026-10-20T09:00:01.521Z",
      "lastChangedBy": {
        "name": "Ana Diaz",
        "sqlName": "ana_diaz"
      }
    }
  ],
  "projectId": null,
  "owner": {
    "name": "Ana Diaz",
    "sqlName": "ana_diaz"
  },
  "home": "ana_diaz"
}

Read a map that does not exist

Needs a token. A map your account does not reach answers the same.

curl

curl -s http://localhost:3000/api/maps/no-such-map \
  -H "Authorization: Bearer <YOUR_TOKEN>"

JavaScript

const response = await fetch("http://localhost:3000/api/maps/no-such-map", {
  headers: { Authorization: "Bearer <YOUR_TOKEN>" },
});
console.log(JSON.stringify(await response.json(), null, 2));

Answers 404 application/json

{
  "error": {
    "code": "not_found",
    "message": "The requested resource was not found."
  }
}

PATCHUpdate a map

Sign-in Session cookie or Bearer tokenMCP tool update_map

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Any of name, viewport, basemap (dark | light | streets | satellite, or null for Auto — the builder follows the app theme; published views follow the publication's effective theme, unless a deployment override pins Auto), basemapLayers (per-group basemap visibility; null shows everything), legendCorner (null = bottom-left), legendOrder (the manual legend arrangement; null follows the layer panel), timeline (the docked playback timeline; null undocks), widgets (the ordered widget list, notes included), widgetsPublished (whether widgets ship with the published view), or layer order. The former note field retired into a note widget.

Parameters

idPathrequired
Map id.
string
X-Change-GroupHeader
Optional group marker: consecutive edits in a group form a step on the map's undo timeline, and an edit from outside the group between them starts a new one. One turn can span several steps. Grouping never crosses actors. The in-product assistant stamps each turn automatically; any agent may group its own related edits the same way.
stringpattern ^[\w-]{1,64}$
X-Edit-RevisionHeader
Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal. Required for any content field, including a no-op or content combined with viewport. Viewport-only writes need no revision and change no edit revision, history or attribution.
stringpattern ^[0-9a-f]{32}$
Opaque durable revision paired with this document state. Camera and derived writes do not change it.

Request body (optional)

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

MapUpdate

Responses

200
Success.
application/json
MapWithLayers
400401403404409413503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways DELETE, GET, HEAD, OPTIONS, PATCH

Example

Change the map's basemap to Light

Needs the map World cities with its newest editRevision, here the one reading the published map answered.

curl

curl -s -X PATCH http://localhost:3000/api/maps/2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34 \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Edit-Revision: 9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90" \
  -d '{"basemap": "light"}'

JavaScript

const response = await fetch("http://localhost:3000/api/maps/2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34", {
  method: "PATCH",
  headers: {
    Authorization: "Bearer <YOUR_TOKEN>",
    "Content-Type": "application/json",
    "X-Edit-Revision": "9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90",
  },
  body: JSON.stringify({ basemap: "light" }),
});
console.log(JSON.stringify(await response.json(), null, 2));

Answers 200 application/json

{
  "id": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34",
  "name": "World cities",
  "viewport": {
    "lng": 0,
    "lat": 40,
    "zoom": 1.3,
    "pitch": 0,
    "bearing": 0
  },
  "basemap": "light",
  "customBasemap": null,
  "basemapLayers": null,
  "note": null,
  "legendCorner": null,
  "legendOrder": null,
  "timeline": null,
  "widgets": [],
  "widgetsPublished": true,
  "publishToken": "<PUBLISH_TOKEN>",
  "publishedAt": "2026-10-20T09:00:01.521Z",
  "published": true,
  "createdAt": "2026-10-20T09:00:01.507Z",
  "updatedAt": "2026-10-20T09:00:01.529Z",
  "editRevision": "e7a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9",
  "lastChangedAt": "2026-10-20T09:00:01.529Z",
  "lastChangedBy": {
    "name": "Ana Diaz",
    "sqlName": "ana_diaz"
  },
  "layers": [
    {
      "id": "9b1c4e7f-2a5d-4c83-8f06-3e7a1b9d5c20",
      "mapId": "2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34",
      "name": "Big cities",
      "sql": "SELECT name, population, geometry FROM world_cities WHERE population > 10000000",
      "style": {
        "fill": {
          "type": "constant",
          "color": {
            "r": 18,
            "g": 147,
            "b": 154,
            "a": 1
          }
        },
        "fillOpacity": 0.72,
        "stroke": {
          "r": 12,
          "g": 16,
          "b": 24,
          "a": 1
        },
        "strokeOpacity": 0.85,
        "strokeWidth": 0,
        "pointRadius": 3,
        "opacity": 1
      },
      "visible": true,
      "tooltip": null,
      "popup": null,
      "publishedFields": null,
      "inLegend": true,
      "viz": {
        "type": "points"
      },
      "filters": [],
      "legendTitle": null,
      "legendLabels": null,
      "legendAttrs": null,
      "ordinal": 0,
      "createdAt": "2026-10-20T09:00:01.515Z",
      "updatedAt": "2026-10-20T09:00:01.515Z",
      "editRevision": "e7a1c3e5b7d9f1a3c5e7b9d1f3a5c7e9",
      "lastChangedAt": "2026-10-20T09:00:01.529Z",
      "lastChangedBy": {
        "name": "Ana Diaz",
        "sqlName": "ana_diaz"
      }
    }
  ],
  "projectId": null,
  "owner": {
    "name": "Ana Diaz",
    "sqlName": "ana_diaz"
  },
  "home": "ana_diaz"
}

DELETEDelete a map

Sign-in Session cookie or Bearer tokenMCP tool delete_map

A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing.

Parameters

idPathrequired
Map id.
string
X-Edit-RevisionHeaderrequired
Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.
stringpattern ^[0-9a-f]{32}$
Opaque durable revision paired with this document state. Camera and derived writes do not change it.

Responses

204
Deleted.
400401403404409503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways DELETE, GET, HEAD, OPTIONS, PATCH

HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow DELETE, GET, HEAD, OPTIONS, PATCH
Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

`/api/maps/{id}/picture/refresh`

POSTRefresh a map picture

Sign-in Session cookie or Bearer tokenMCP tool refresh_map_picture

A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Ask the server to picture the saved drawing as its owner. The owner or a project Editor may ask; a Viewer receives forbidden. Repeated requests coalesce with pending work. The previous complete picture stays served. This changes no edit revision, history or Last edited timestamp and requires no edit revision. Answers queued after admission to the quiet wait, or unavailable when the renderer is absent. Basemap services may be contacted by the background attempt.

Parameters

idPathrequired
Map id.
string

Responses

200
The renderer is unavailable.
application/json
object
- outcomestringalways unavailablerequired
- pictureStatestringalways unavailablerequired
202
Queued or coalesced.
application/json
object
- outcomestringalways queuedrequired
- pictureStatestringalways waitingrequired
401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

`/api/maps/{id}/thumbnail`

GETRead a map's snapshot

Sign-in Session cookie or Bearer token

History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. The last complete PNG the server made for this map, the maps screen's card image. 404 while no picture is served. A map whose basemap follows the theme carries one image per theme: name the theme to read that one. The fallback order: the named theme's image, then the map's single image, then the other theme's; a request naming no theme answers the light image, then dark, then the single image. An image the reader may not be served (one that drew a dataset beyond their reach, or an unattributed one read by anyone but the owner) is passed over like a missing one; when none is left the answer is the same 404 as for a map with no image at all. The maps listing's hasThumbnail says beforehand whether there is one. Naming a shape or a width answers one of the sizes the server keeps of that picture, as WebP: the narrowest at least that wide, else the widest; a shape alone answers the widest. The sizes share one proportion, 968 by 494, which a card's box crops to its own; a picture kept earlier in two shapes answers the one named, and a width alone its card shape. A picture made before sizes were kept answers its PNG whatever is named. Every answer carries an entity tag of its bytes and Cache-Control: private, no-cache, so a client may keep it but asks again before each use; a request whose If-None-Match names the current tag is answered 304 without the bytes, after the same serving checks as a full read.

Parameters

idPathrequired
Map id.
string
themeQuery
The viewer's theme, "light" or "dark". Any other value is refused.
string
One of light, dark
shapeQuery
The shape to answer. The server keeps every picture in one shape, which "card" and "wide" both name; a picture kept earlier in two shapes answers the one named until it is made again. Any other value is refused.
string
One of card, wide
widthQuery
The width in screen pixels the image will cover. Anything but a positive whole number is refused.
integerminimum 1maximum 999999999

Responses

200
The snapshot: the PNG, or with a shape or a width named, a kept size.
image/png
stringformat binary
image/webp
stringformat binary
- ETagHeader
  The entity tag of these bytes.
  string
- Cache-ControlHeader
  private, no-cache
  stringalways private, no-cache
304
The picture this reader is served is unchanged: its entity tag matches If-None-Match.
400
A theme, shape or width the read does not take (invalid_request).
application/json
Error
401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways GET, HEAD, OPTIONS, PUT

PUTRefuse a retired browser picture upload

Sign-in Session cookie or Bearer token

History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Compatibility change: this operation no longer accepts browser pixels. An authorized owner receives 410 picture_upload_retired without the handler reading the body or changing any image. Use POST /api/maps/{id}/picture/refresh. Theme, cycle and revision query values do not restore the former operation.

Parameters

idPathrequired
Map id.
string

Responses

401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways GET, HEAD, OPTIONS, PUT
410
Browser picture upload retired (picture_upload_retired).
application/json
Error

HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 304, 400, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS, PUT
Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

`/api/maps/{id}/widget-values`

POSTRead the map's widget values

Sign-in Session cookie or Bearer tokenMCP tool read_widget_values

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Layers and widgets follow their map: everyone who reaches the map reads and evaluates them, and its owner, the project's owner and its editors change them. Layer SQL saved by anyone but the map's owner must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Unreached, missing or mismatched parent/child identities return not_found before query evaluation, artifact access or protected changes. New widget, timeline and layer-order references must belong to the exact map. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Every visible widget computed server-side over its layer's effective query, under an optional ephemeral selection set — cross-filter state that lives on the request and is never stored. Classic crossfilter semantics: a widget's own selection never filters itself. Also returns per-layer constrained/total row counts. A read, despite the POST — the body carries the selections. An optional draft widget previews an unsaved editor state: validated like a stored widget, it replaces its stored self by id (or joins as a new card) for this computation only — nothing is written.

Parameters

idPathrequired
Map id.
string

Request body (optional)

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

selectionsWidgetSelections
draftMapWidget

Responses

200
Success.
application/json
WidgetValues
401403404413503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

`/api/maps/{id}/search`

GETSearch the map

Sign-in Session cookie or Bearer tokenMCP tool search_map

A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. One search over the map's own data and, on request, places : visible layers matched by name, attribute values matched case-insensitively in genuine text columns of each visible layer's effective (filtered) result — one row per matching feature, at most 20 across layers, on the hardened read-only path — and every plausible reading of a pasted decimal coordinate pair. With places=1 and a configured provider endpoint, Nominatim-compatible place results join, carrying the provider's attribution; unconfigured, the places group answers unconfigured and everything local still works. Value and place rows carry the geometry a client needs to fly or fit without a second request. Never builder actions.

Parameters

idPathrequired
Map id.
string
qQueryrequired
The search text.
string
placesQuery
Ask for places too — the submitted search. Omitted, the provider is never contacted (the per-keystroke path).
string
One of 1

Responses

200
Success.
application/json
SearchResults
401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways GET, HEAD, OPTIONS

HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS
Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

`/api/maps/{id}/dependencies`

GETThe datasets a map draws from

Sign-in Session cookie or Bearer tokenMCP tool get_map_dependencies

A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Each layer's references resolve to dataset identities in the map's SQL home within the caller's reach, and each one is listed with its owner and the name the caller would type: a dataset the caller cannot reach is left out rather than named, and a same-named dataset of the caller's own never stands in for the map's. Memberships name the projects the caller reaches, and on the caller's own datasets every project they are in, one the caller no longer reaches included; producers only workflows the caller reaches, each marked with whether the caller owns it. The 14-A filing checklist's subject: every registered dataset used by at least one of the map's saved layers, exactly once, with its source, row count, project memberships, and the workflow-origin recipe that currently produces it (null otherwise), and its geometry column and sampled geometry type (both null for a non-spatial dataset; a column with no sampled type is still spatial). A layer whose statement cannot be analyzed fails the whole read with dependencies_unresolved — a partial answer never presents as a complete checklist.

Parameters

idPathrequired
Map id.
string

Responses

200
Success.
application/json
MapDependencies
401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways GET, HEAD, OPTIONS

HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS
Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

`/api/maps/{id}/duplicate`

POSTDuplicate a map

Sign-in Session cookie or Bearer tokenMCP tool duplicate_map

Created resources belong to the authenticated account. Submitted owner identities cannot assign or transfer ownership. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Full copy — viewport, basemap, note, legend, timeline dock, and every layer under fresh ids — named "<name> copy", always an unpublished draft. Edit history does not carry over.

Parameters

idPathrequired
Map id.
string

Responses

201
Created.
application/json
MapWithLayers
401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

`/api/maps/{id}/history`

GETUndo/redo availability

Sign-in Session cookie or Bearer tokenMCP tool get_history

History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Whether the map currently has anything to undo or redo. Every qualifying change (style, viz, filters, names, visibility, layer add/delete, basemap, note, legend, layer order, timeline dock) lands on one per-map history, whoever made it; viewport moves, publish state, and a playing timeline do not.

Parameters

idPathrequired
Map id.
string

Responses

200
Success.
application/json
History
401403404503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways GET, HEAD, OPTIONS

HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS
Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

`/api/maps/{id}/undo`

POSTUndo the newest change

Sign-in Session cookie or Bearer tokenMCP tool undo_change

History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Reverts the latest step on the map's history. Consecutive edits in a group form a step, and an edit from outside the group between them starts a new one, so one turn's edits can span several steps. Grouping never crosses actors. Restores are verbatim: exactly the values stored before the change. Returns the refreshed map with fresh availability and a fresh editRevision; 409 invalid_request when there is nothing to undo, or 409 stale_revision when the seen revision is no longer current, including during SQL admission. Redo re-applies the stored change. A replay that would change a publication setting (the widget publication toggle or a layer's published fields) is the map owner's alone: anyone else is refused whole with forbidden, and nothing is restored.

Parameters

idPathrequired
Map id.
string
X-Edit-RevisionHeaderrequired
Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.
stringpattern ^[0-9a-f]{32}$
Opaque durable revision paired with this document state. Camera and derived writes do not change it.

Responses

200
Success.
application/json
MapWithHistory
400401403404409503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

`/api/maps/{id}/redo`

POSTRedo the newest undone change

Sign-in Session cookie or Bearer tokenMCP tool redo_change

History follows its map: everyone who reaches the map reads its availability, and undo and redo are content changes. Thumbnails are rendered by the server as the map's owner and record the datasets each image drew: an image is served, and copied into a duplicate, only for someone who reaches the map and can now reach every one of them, an unattributed image for the owner alone; anyone else reads no snapshot. Replay checks every target and parent reference before changing the whole gesture; unreached, missing or mismatched references return not_found and leave history and artifacts unchanged. A deleted layer can be restored under its recorded identity and parent. Picture publication rechecks owner standing, the drawing generation and consumed inputs after waiting and before publication. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Re-applies the most recently undone step exactly as it was stored. Consecutive edits in a group form a step, and an edit from outside the group between them starts a new one. One turn can span several steps. Grouping never crosses actors. Any fresh edit after an undo discards the redo branch. Returns a fresh editRevision, never an older token even when values match. 409 invalid_request when there is nothing to redo, or 409 stale_revision when the seen revision is no longer current, including during SQL admission. A replay that would change a publication setting (the widget publication toggle or a layer's published fields) is the map owner's alone: anyone else is refused whole with forbidden, and nothing is restored.

Parameters

idPathrequired
Map id.
string
X-Edit-RevisionHeaderrequired
Read the document first and send its editRevision. Missing or malformed: 400 invalid_request. Stale: 409 stale_revision, with no changes. Chain accepted results; reload explicitly after refusal.
stringpattern ^[0-9a-f]{32}$
Opaque durable revision paired with this document state. Camera and derived writes do not change it.

Responses

200
Success.
application/json
MapWithHistory
400401403404409503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST

Also on this path: OPTIONS under System.

`/api/maps/look`

POSTLook at a map: one bounded rendered image with its facts

Sign-in Session cookie or Bearer tokenMCP tool look_at_map

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. The model-facing check of a map: the map's stored state rendered through the same server-side road as the image export, at 1024 by 640 pixels, and answered as a PNG of at most 384 KiB together with the render's facts. The image is derived from that one render downwards through 768 by 480 and 512 by 320 when the byte bound is missed; still over it at 512 by 320 the answer is look_image_too_large and no image. The facts carry the render's identity, the bounded state identity of what the renderer actually drew (the map, the camera, the visible layers with a digest of their stored filters, the legend and the widgets, the appearance), the image's pixel and byte sizes, the source size, the attribution credited, the composition's truthful failures and any abandoned external requests, and the elapsed time. The appearance is an explicit input, light when absent; mapId names the map, and a call naming none answers look_target_missing. Read-only: the map's stored state stays as it is; the image is retained in process for GET /api/maps/look/{renderId} under documented bounds. Bounded by its own budget (30 s by default, DEZFIL_ASSISTANT_LOOK_TIMEOUT_S), queue wait, render and image preparation included; past it the answer is render_timeout. Without a renderer browser on the instance the answer is render_unavailable.

Request body (optional)

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

mapIdstring
The map to look at. The assistant supplies the contextual map when the model names none; a headless call without one answers look_target_missing.
appearancestring
The theme to render with. Light when absent.
One of light, dark

Responses

200
The image and the render's facts.
application/json
MapLook
400
No map named (look_target_missing), or a malformed map id or appearance (invalid_request).
401403413503default
Error with a machine-readable code and human message.
application/json
Error
404
No such map (not_found).
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST
408
The check's budget was exceeded (render_timeout).
502
The render failed or the renderer did not report what it drew (render_failed).

Also on this path: OPTIONS under System.

`/api/maps/look/{renderId}`

GETRead the retained image of a map check

Sign-in Session cookie or Bearer tokenMCP tool read_map_look_image

Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. Exactly the PNG a check handed the model, or the thumbnail derived from it at retention, as an attachment. Renders are retained in process under documented bounds, 256 renders and 96 MiB by default (DEZFIL_ASSISTANT_LOOK_RETENTION, DEZFIL_ASSISTANT_LOOK_RETENTION_MB), full images and thumbnails counted together, oldest evicted first, gone with the process. After eviction or a restart the answer is look_image_unavailable; this read renders nothing.

Parameters

renderIdPathrequired
The render's identity from the check's facts.
string
variantQuery
full (the default) is the image the model was given; thumbnail is the 132 px wide derivation kept beside it.
string
One of full, thumbnail

Responses

200
The PNG, as an attachment.
image/png
stringformat binary
401403503default
Error with a machine-readable code and human message.
application/json
Error
404
Evicted or gone with a restart (look_image_unavailable).
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways GET, HEAD, OPTIONS

HEADRead response headers
Sign-in Session cookie or Bearer tokenAnswers 200, 401, 403, 404, 405, 503, defaultAllow GET, HEAD, OPTIONS
Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

`/api/maps/{id}/export/image`

POSTRender a map to a PNG image

Sign-in Session cookie or Bearer tokenMCP tool export_map_image

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Requires a current cookie session or bearer token. Cookie mutations require the same trusted Origin. Responses, including refusals, are private, no-store. Private execution retains the initiating account through completion. Retained images and download receipts belong only to that account, including for administrators, even after the source or output is deleted. A copied result identifier has the same refusal as an unknown identifier and cannot consume or release the owner's result. Account activity is checked before returning bytes or retaining a new result; deactivation freezes access until reactivation. Reach is asked again where the work commits. A prepared layer download is refused on the claim when its layer, on a map the claimant does not own, or a dataset it drew that someone else owns has left the claimant's reach since the ticket, with the same answer as an expired ticket. A server render and a look check ask at every phase whether the caller still reaches the map and are refused as absent otherwise. A project export checks every selected member against the caller's reach as the archive completes and fails with export_failed naming the first one withdrawn rather than delivering a thinner archive. Results already issued (a query download, a retained look image, a project archive, an assistant answer) remain the initiator's for their retention lifetime after reach is withdrawn, as a copy they hold; they grant no new access to the source. A map is reached by its owner and, while it is filed in a project, by that project's owner and people. Results cover exactly the reached maps and name each map's owner and SQL home; the map's SQL is evaluated in its home within the caller's own reach. Content changes are open to the owner, the project's owner and its editors; SQL anyone but the owner saves, directly or by undo and redo, must name only datasets within their own reach in the map's home, else it is refused with sql_error naming the reference as written and nothing changes. Sketches drawn on the map are content, each sketch dataset its drawer's own; deletion and publication settings stay the owner's; the server makes pictures as the owner, and an Editor may request a refresh; a snapshot is served to everyone who reaches the map and every dataset it drew. Anyone who reaches a map may duplicate it into their own space: the copy keeps the map's SQL home and its layers' SQL as stored, is filed in the map's project only when the duplicator may file there (its owner or an editor), and carries the snapshot only when the duplicator may be served it. Administrators reach nothing more. Unreached and missing map or project identities both return not_found before source access or protected changes; a reached map whose change the caller may not make returns forbidden and changes nothing. Server-side image export: the map rendered by the app's own client inside the instance's headless browser and screenshotted at exactly the definition's pixels — the same composition the builder's export card downloads, pixel-faithful by construction. Takes the documented ExportImageDefinition; answers the PNG as an attachment (agents receive it as the base64 attachment envelope). Bounded by the documented render budget and concurrency cap; renders stored map state — visible layers, stored filters — never builder-transient selections. Without a browser on the instance the operation answers render_unavailable; health is unaffected. When an external request outlives its bound, the request burst has settled and no app-origin request remains in flight, the relay ends its current sockets and refuses re-dials only to the stalled hosts for this render. Requests without a terminal event stay armed for another cut after the same bound. The whole render budget still applies. An image response carries x-dezfil-export-abandoned with the abandonment count and hosts (never paths), counting repeated cuts again. The server log names each abandonment as it happens.

Parameters

idPathrequired
Map id.
string

Request body

At most 16,777,216 bytes (16 MiB); a larger body is refused with request_body_too_large.

application/json

object

definitionExportImageDefinitionrequired

Responses

200
The PNG, as an attachment.
image/png
stringformat binary
400
Invalid definition (schema-validated).
401403404413503default
Error with a machine-readable code and human message.
application/json
Error
405
method_not_allowed: the method is unsupported for this path.
application/json
Error
- AllowHeader
  Exactly the documented methods for this path.
  stringalways OPTIONS, POST

Also on this path: OPTIONS under System.