Layers

25 operations on 13 paths.

/api/icons/sanitize

POSTSanitize custom icon SVG

Sign-in Session cookie or Bearer tokenMCP tool sanitize_icon_svg

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Advisory pass of the custom-icon sanitizer: returns the accepted markup, whether anything changed, and a bounded report of dropped content (category and name). The layer write re-sanitizes — this exists so a picker or agent can preview the outcome. Not-SVG, oversize, and nothing-drawable inputs answer invalid_request.

Request body

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

application/json

object

• svgstringrequired

Responses

• 200

  Success.

  application/json

  SanitizedIcon

• 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}/layers

GETList a map's layers

Sign-in Session cookie or Bearer tokenMCP tool list_layers

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.

Parameters

• idPathrequired

  Map id.

  string

Responses

• 200

  Success.

  application/json

  LayerList

• 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

POSTCreate a layer from a SQL result

Sign-in Session cookie or Bearer tokenMCP tool create_layer

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. The SQL must return at least one geometry column. The first geometry column in select order is the primary geometry used for simple rendering; additional geometry columns are allowed. A default, publication-ready style is applied when none is provided: it takes the instance's defaults for new layers, the next color of the color cycle with the geometry's opacity, the line width and the point radius (defaults in the runtime configuration). A given style is kept as given.

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-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.

Request body

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

application/json

LayerCreate

Responses

• 201

  Created.

  application/json

  Layer

• 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 GET, HEAD, OPTIONS, POST

Example

Add the layer Big cities

Needs the map World cities with the editRevision creating it answered, and the dataset world_cities. The layer draws the 15 cities of more than 10 million people.

curlJavaScript

curl

Terminal

curl -s http://localhost:3000/api/maps/2f6e9c41-8d3b-4a7e-b1f5-6c0d2e8a9b34/layers \
  -H "Authorization: Bearer <YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -H "X-Edit-Revision: 4f1c9a7e2b0d4c6e8a1f3b5d7c9e0a2b" \
  -d '{"name": "Big cities", "sql": "SELECT name, population, geometry FROM world_cities WHERE population > 10000000"}'

Answers 201 application/json

Response

{
  "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": "c03e5b7d9f1a2c4e6b8d0f2a4c6e8b1d",
  "lastChangedAt": "2026-10-20T09:00:01.515Z",
  "lastChangedBy": {
    "name": "Ana Diaz",
    "sqlName": "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/layers/{id}

GETRead a layer

Sign-in Session cookie or Bearer tokenMCP tool get_layer

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.

Parameters

• idPathrequired

  Layer id.

  string

Responses

• 200

  Success.

  application/json

  Layer

• 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

PATCHUpdate a layer

Sign-in Session cookie or Bearer tokenMCP tool update_layer

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. Any of name, sql, style, visibility, tooltip or popup fields (null = automatic), the published-field list (null = derived projection), legend inclusion, viz (points | hexbin | grid | heatmap — hexbin/grid aggregate server-side and get a fill over their aggregate value automatically), filters (applied before aggregation; [] removes them), or legend text overrides. Text labels live in the style's label member. When sql is changed, it must return at least one geometry column. The first geometry column in select order is the primary geometry used for simple rendering; additional geometry columns are allowed.

Parameters

• idPathrequired

  Layer 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-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.

Request body (optional)

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

application/json

LayerUpdate

Responses

• 200

  Success.

  application/json

  Layer

• 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

DELETEDelete a layer

Sign-in Session cookie or Bearer tokenMCP tool delete_layer

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. Recorded on the undo timeline — an undo restores the layer whole. Removing one's own sketch layer also deletes its sketch dataset, wherever the map is; removing a layer that draws someone else's sketch leaves their dataset.

Parameters

• idPathrequired

  Layer 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-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

  Deleted. The surviving map revision.

  application/json

  EditRevisionResult

• 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/layers/{id}/duplicate

POSTDuplicate a layer

Sign-in Session cookie or Bearer tokenMCP tool duplicate_layer

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. Full copy — SQL, style, viz, filters, tooltip, legend settings — with a suffixed name, stacked on top of the map's layer order.

Parameters

• idPathrequired

  Layer 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-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

• 201

  Created.

  application/json

  Layer

• 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/layers/{id}/extent

POSTA layer's current data extent

Sign-in Session cookie or Bearer tokenMCP tool layer_extent

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. The bounding box of what the layer currently draws: its SQL, its stored filters, and any constraints stated in dims — the ranges, time windows and category selections a canvas enforces after the data is fetched. Answers kind: "extent" with box as [west, south, east, north], or kind: "empty" when the constraints leave nothing drawn. Empty is a normal outcome of filtering, not a failure. A client holding the layer's features whole can compute this itself; it exists for the case it cannot — a tiled layer, whose features never reach the client entire.

Parameters

• idPathrequired

  Layer 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

• dimsarray of object

  Constraints in force beyond the layer's stored filters, in the canvas's dimension form.

Responses

• 200

  The extent.

  application/json

  LayerExtent

• 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/layers/{id}/export/{format}

GETDownload a layer's effective result

Sign-in Session cookie or Bearer tokenMCP tool export_layer_data

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. 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. The layer's effective result as a file download: its SQL, then its stored filters, then OD/aggregation — exactly what the builder renders, so a stored filter is never dropped on the way out. Live widget selections and other transient view state never enter. The result's first geometry column is the feature geometry; every other geometry column travels as a WKT value beside it. Runs on the hardened read-only instance under the universal query bound — timeout, memory budget, and cancellation when the caller departs. The response is an attachment named <layer>.<ext>; through the agent tool it arrives as a base64 attachment envelope.

Parameters

• idPathrequired

  Layer id.

  string

• formatPathrequired

  Download format: geoparquet, geojson, or csv (geometry as WKT).

  string

  One of geoparquet, geojson, csv

Responses

• 200

  The file, as an attachment.

  application/octet-stream

  stringformat binary

• 400

  Unknown format, invalid SQL, or the bounded lane's coded errors.

• 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, 400, 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/layers/{id}/render

GETRender data for a layer

Sign-in Session cookie or Bearer tokenMCP tool render_layer

Render results follow the layer's map: everyone who reaches it reads them, evaluated in the map's SQL home within their own reach. Tile archives record the datasets they drew and are served to a caller only while that caller can reach every one of them; administrators reach nothing more. Everyone who reaches the map is served an archive within their reach, and otherwise their render prepares tiles in their own reach; a tile request for an archive beyond the caller's reach, or for one whose evidence names another build, answers not_found. An archive made before archives recorded their inputs is served to the map's owner alone. Builds are kept apart by the reach that asked for them: a refused or failed build is that reach's alone, reported as failed to it for the same query, and never replaces the archive or the status anyone else is served. Unreached and missing layers return the same not_found before archive reads or build admission. Private tile workers recheck account activity before export and on both sides of archive publication; deactivation leaves no new authoritative archive. Private reads recheck authority before answering. Deleting an owned layer fences its outstanding build. Reactivation permits a fresh build. A visible published layer uses its current token independently of the publisher's activity; a revoked token cannot authorize a new archive. 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. The layer's effective result — its SQL refined by its filters, then aggregated by its viz (hexbin/grid cells expose value and count). Under the render cap the response is inline GeoJSON (mode: inline). A points-viz result over the cap is served as vector tiles instead (mode: tiled): tiles are prepared in the background — poll while tiles.state is building; when ready, tiles.url is a {z}/{x}/{y} template and bounds/zoom range describe the archive. Inline feature properties are the columns the layer and its map read: its style, label and label-priority fields, the filters the canvas applies, the docked timeline's field, the fields of the map's widgets on it, its explicit tooltip and pop-up fields or, while either list is automatic, the first eight columns, and a drawn sketch's feature_id and kind; other columns stay out, and the published field list plays no part. The inline answer, envelope included, is bounded by Bytes drawn per layer (renderCapBytes), counted as it is built. Above it the layer takes the road it takes over the cap: a points-viz result is served as tiles, a result shipped without its live filters has them applied in the query and is answered inline if that fits, and anything else answers the errored state render_bytes_exceeded. A template's layer has no tile road. Errored states (deleted table, failed build, missing tiler, an aggregation over the cap, an answer over the byte limit) are returned as data, not an HTTP error.

Parameters

• idPathrequired

  Layer id.

  string

Responses

• 200

  Success.

  application/json

  LayerRender

• 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

POSTRender a computed layer under ephemeral selections

Sign-in Session cookie or Bearer token

At most 16,777,216 wire bytes; a larger body is refused with request_body_too_large before JSON parsing. Render results follow the layer's map: everyone who reaches it reads them, evaluated in the map's SQL home within their own reach. Tile archives record the datasets they drew and are served to a caller only while that caller can reach every one of them; administrators reach nothing more. Everyone who reaches the map is served an archive within their reach, and otherwise their render prepares tiles in their own reach; a tile request for an archive beyond the caller's reach, or for one whose evidence names another build, answers not_found. An archive made before archives recorded their inputs is served to the map's owner alone. Builds are kept apart by the reach that asked for them: a refused or failed build is that reach's alone, reported as failed to it for the same query, and never replaces the archive or the status anyone else is served. Unreached and missing layers return the same not_found before archive reads or build admission. Private tile workers recheck account activity before export and on both sides of archive publication; deactivation leaves no new authoritative archive. Private reads recheck authority before answering. Deleting an owned layer fences its outstanding build. Reactivation permits a fresh build. A visible published layer uses its current token independently of the publisher's activity; a revoked token cannot authorize a new archive. 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. The settle lane for widget cross-filtering: re-render a hexbin, grid, cluster, or heatmap layer with a selection set folded into its query — cells re-bin and clusters recount, with zero writes. Selections are pre-resolved filters and pass the stored-filter validation; other viz types enforce selections client-side and reject this call.

Parameters

• idPathrequired

  Layer 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

• selectionsarray of LayerFilter

Responses

• 200

  Success.

  application/json

  LayerRender

• 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

• 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/layers/{id}/slider-preview

GETRead bounded slider-preview input

Sign-in Session cookie or Bearer token

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. Read-only point input for an editing interaction. Discrete filters are applied; range/time filters are left for the client so a slider can narrow and widen. The response says whether it is exact or a stable bounded subset. It never changes the layer or its history and is not published. The answer, envelope included, is bounded by Bytes drawn per layer (renderCapBytes), counted as it is built; above it the read answers 422 render_bytes_exceeded with no partial preview, and the layer's own render is unaffected.

Parameters

• idPathrequired

  Layer id.

  string

Responses

• 200

  Success.

  application/json

  SliderPreviewData

• 401403404422503default

  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, 422, 503, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/layers/{id}/tiles/{z}/{x}/{y}

GETOne vector tile of a tiled layer

Sign-in Session cookie or Bearer token

Render results follow the layer's map: everyone who reaches it reads them, evaluated in the map's SQL home within their own reach. Tile archives record the datasets they drew and are served to a caller only while that caller can reach every one of them; administrators reach nothing more. Everyone who reaches the map is served an archive within their reach, and otherwise their render prepares tiles in their own reach; a tile request for an archive beyond the caller's reach, or for one whose evidence names another build, answers not_found. An archive made before archives recorded their inputs is served to the map's owner alone. Builds are kept apart by the reach that asked for them: a refused or failed build is that reach's alone, reported as failed to it for the same query, and never replaces the archive or the status anyone else is served. Unreached and missing layers return the same not_found before archive reads or build admission. Private tile workers recheck account activity before export and on both sides of archive publication; deactivation leaves no new authoritative archive. Private reads recheck authority before answering. Deleting an owned layer fences its outstanding build. Reactivation permits a fresh build. A visible published layer uses its current token independently of the publisher's activity; a revoked token cannot authorize a new archive. 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. Mapbox Vector Tile bytes for the archive built from the layer's effective result. Use the URL template from the render response (it carries a cache-busting version). A spot the archive does not cover returns 204 with no body.

Parameters

• idPathrequired

  Layer id.

  string

• zPathrequired

  Tile zoom.

  string

• xPathrequired

  Tile column.

  string

• yPathrequired

  Tile row.

  string

Responses

• 200

  The tile.

  application/vnd.mapbox-vector-tile

  stringformat binary

• 204

  No tile at these coordinates.

• 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, 204, 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/layers/{id}/fields

GETA layer's non-geometry columns

Sign-in Session cookie or Bearer tokenMCP tool list_layer_fields

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. styling: columns of the effective result, for fill and tooltip fields (an aggregated layer exposes exactly value and count). filterable: columns of the layer's own SQL result — what filters apply to.

Parameters

• idPathrequired

  Layer id.

  string

Responses

• 200

  Success.

  application/json

  LayerFields

• 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/layers/{id}/fields/{field}

GETA field's extent or distinct values

Sign-in Session cookie or Bearer tokenMCP tool get_field_stats

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. Seed data for a filter control: min/max and a binned distribution for numeric and time fields (time extents as ISO-8601 strings), distinct values (bounded, by frequency) for text. Computed on the layer's own result — the unfiltered extent, so a brush keeps a stable background. A distinct value longer than 2,097,152 bytes (2 MiB) as a JSON string refuses the answer with 422 query_result_too_large.

Parameters

• idPathrequired

  Layer id.

  string

• fieldPathrequired

  Field name from the layer's result.

  string

Responses

• 200

  Success.

  application/json

  FieldStats

• 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/layers/{id}/fill

POSTCompute a data-driven paint

Sign-in Session cookie or Bearer tokenMCP tool compute_fill

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. Quantile, equal-interval, or natural (Fisher–Jenks, computed on a bounded sample) breaks for numeric attributes, distinct colors for categorical ones, or a continuous unclassed ramp: the attribute's domain resolved over the effective result with the palette's stops baked in (diverging palettes come back centered on the mean; clamp, log, and center are then style-level edits on the returned paint). Optional palette (curated or saved custom — see /api/palettes), class count, and reverse. Classification runs on the layer's effective result, so filters are respected and an aggregated layer classifies its value or count. Returns a paint to merge into the style — fill, or strokeBy for a data-driven outline — or into the viz fill of an aggregated layer. A category longer than 2,097,152 bytes (2 MiB) as a JSON string refuses the paint with 422 query_result_too_large.

Parameters

• idPathrequired

  Layer 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

• attributestringrequired

• methodstringrequired

  One of quantile, equal, natural, categorical, continuous

• palettestring

  Palette name from the catalogue or a saved custom palette; kind must match the method (numeric methods take sequential, diverging, and custom palettes, categorical takes qualitative).

• classesinteger

  Class count for numeric ramps (2-12).

• reversedboolean

Responses

• 200

  Success.

  application/json

  FillPaint

• 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/layers/{id}/scale

POSTCompute a size scale

Sign-in Session cookie or Bearer tokenMCP tool compute_scale

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. Resolve a numeric attribute's value range over the layer's effective result (filters respected) and map it onto an output range. Returns a scale to merge into the style — pointRadiusBy for point radius, strokeWidthBy for line width, or (with unit 'm') heightBy for polygon extrusion in meters. The sibling of the paint operation, for the size channels.

Parameters

• idPathrequired

  Layer 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

• attributestringrequired

• rangearray of numberrequiredmin items 2max items 2

  Output values, smallest first — pixels (0-200) by default, meters (0-100000) with unit 'm'.

• unitstring

  Output unit: px for sizes (default), m for the extrusion height channel.

  One of px, m

Responses

• 200

  Success.

  application/json

  SizeScale

• 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.