Publish

17 operations on 9 paths.

/api/maps/{id}/publish

GETThe active publication's authored settings

Sign-in Session cookie or Bearer tokenMCP tool get_publication_state

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 theme default and the viewer-controls checklist for the active publication. 204 when the map is not published — a state, not an error. A map record carries no publication state, so this is how an author surface reads back what it is about to change. The token is the map owner's alone: anyone else who reaches the map reads the settings without it.

Parameters

• idPathrequired

  Map id.

  string

Responses

• 200

  The active publication's settings.

  application/json

  PublicationState

• 204

  The map is not published.

• 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, POST

POSTPublish a map

Sign-in Session cookie or Bearer tokenMCP tool publish_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. Minting a publication and changing its theme or reader controls are the map owner's alone. Returns a stable, unguessable token. Idempotent while published. The optional theme ("light" | "dark") sets the published view's authored default: omitted on a first publication it records dark (existing callers keep their behavior); stated while already published it updates the stored default in place — the token never changes for a theme; omitted while published it changes nothing. The optional viewerControls sets which optional reader controls the publication exposes, on the same in-place rule: omitted it changes nothing, and on a publication that never stated one every control is on. Within a stated set an omitted member reads as enabled. The two settings are independent — stating one never rewrites the other. Unpublishing clears both with the token.

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.

Request body (optional)

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

application/json

object

• themestring

  The authored default theme for readers.

  One of light, dark

• viewerControlsViewerControls

Responses

• 201

  Published.

  application/json

  PublishState

• 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, POST

Example

Publish the map

Needs the map World cities with the editRevision adding the layer answered. The answer's token is the published link's: the map opens at /v/<token> for anyone with the link.

curlJavaScript

curl

Terminal

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

Answers 201 application/json

Response

{
  "token": "<PUBLISH_TOKEN>",
  "publishedAt": "2026-10-20T09:00:01.521Z",
  "editRevision": "9b2d4f6a8c0e1b3d5f7a9c1e3b5d7f90",
  "lastChangedAt": "2026-10-20T09:00:01.521Z",
  "lastChangedBy": {
    "name": "Ana Diaz",
    "sqlName": "ana_diaz"
  }
}

DELETEUnpublish a map

Sign-in Session cookie or Bearer tokenMCP tool unpublish_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. The link stops resolving immediately. Revoking a publication is the map owner's alone.

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

  Unpublished. 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, POST

Example

Stop sharing the map

Needs the published map World cities with its newest editRevision, here the one the basemap change answered. The published link stops working at once.

curlJavaScript

curl

Terminal

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

Answers 200 application/json

Response

{
  "editRevision": "2d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c",
  "lastChangedAt": "2026-10-20T09:00:01.530Z",
  "lastChangedBy": {
    "name": "Ana Diaz",
    "sqlName": "ana_diaz"
  }
}

• HEADRead response headers

  Sign-in Session cookie or Bearer tokenAnswers 200, 204, 401, 403, 404, 405, 503, defaultAllow DELETE, GET, HEAD, OPTIONS, POST

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/maps/{id}/published-fields

GETWhat each layer shares when this map is published

Sign-in Session cookie or Bearer tokenMCP tool get_published_fields

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 shared-field statement: per layer, the effective published field set — fields marked required are what the published map cannot render without and publish regardless of any list — the mode (derived | list), and every field an explicit list could name. The publish surface renders exactly this; the wire carries exactly what it states. A layer whose SQL cannot resolve degrades to a per-layer error while the rest answer.

Parameters

• idPathrequired

  Map id.

  string

Responses

• 200

  Success.

  application/json

  PublishedFieldsStatement

• 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/publications/{token}

DELETERevoke a deactivated owner's publication

Sign-in Session cookie or Bearer tokenMCP tool revoke_inactive_publication

Requires a current admin through a cookie session or bearer token. Revokes only the supplied token when its owner is currently deactivated, checked in the same transaction as current admin authority. An active owner's token, an unknown token and a revoked token receive identical not_found responses with no change. This operation never reads or returns private map content or account identity, and grants no other access. Deactivation alone leaves existing links available; reactivation restores the owner's private access. Responses, including refusals, are private, no-store. Cookie mutations require the same trusted Origin.

Parameters

• tokenPathrequired

  The known publication token to revoke. This operation does not discover private maps.

  string

Responses

• 204

  Publication revoked. No content is returned.

• 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, OPTIONS

Example

Take a deactivated account's published map offline

Needs an admin's token and the publish token of a map whose owner is deactivated: the end of the map's link, /v/<token>. The answer has no body, and the link stops working at once. The account and the map stay.

curlJavaScript

curl

Terminal

curl -s -X DELETE "http://localhost:3000/api/publications/<PUBLISH_TOKEN>" \
  -H "Authorization: Bearer <YOUR_TOKEN>"

Answers 204 with no body

Also on this path: OPTIONS under System.

/api/published/{token}

GETRead a published view

Sign-in No sign-inMCP tool view_published_map

Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. The read-only view for a token: map, viewport, styled layers, and render data. The only data path a published page uses. Token ownership is checked before reuse and after assembly; responses are private and not stored so revocation cannot be bypassed by a browser or intermediary cache. Feature properties carry exactly each layer's effective published field set — the derived projection (style, label, tooltip/pop-up, live-filter, timeline and published-widget fields) or the author's explicit list plus the fields the map needs to render; hidden layers contribute no feature data.

Parameters

• tokenPathrequired

  Publish token (22 characters).

  string

Responses

• 200

  Success.

  application/json

  PublishedView

• 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

• 429

  rate_limited: Too many requests. Please slow down.

  application/json

  Error

• 503

  ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.

  application/json

  Error

• default

  Error with a machine-readable code and human message.

  application/json

  Error

• HEADRead response headers

  Sign-in No sign-inAnswers 200, 405, 429, 503, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/published/{token}/widget-values

POSTWidget values for a published view

Sign-in No sign-in

Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. At most 65,536 wire bytes. Excess answers 413 request_body_too_large before JSON parsing. Empty bodies keep their default selections. The live half of a published dashboard: the same batched computation as the builder path, under the published-view guarantees — the token must currently resolve, the map must ship widgets, selections pass stored-filter validation, and the anonymous viewer rate limit applies. Responses are private and never stored.

Parameters

• tokenPathrequired

  Publish token (22 characters).

  string

Request body (optional)

At most 65,536 bytes (64 KiB); a larger body is refused with request_body_too_large.

application/json

object

• selectionsWidgetSelections

Responses

• 200

  Success.

  application/json

  WidgetValues

• 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

• 413default

  Error with a machine-readable code and human message.

  application/json

  Error

• 429

  rate_limited: Too many requests. Please slow down.

  application/json

  Error

• 503

  ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.

  application/json

  Error

Also on this path: OPTIONS under System.

/api/published/{token}/render/{layerId}

POSTRe-render a published computed layer under selections

Sign-in No sign-in

Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. At most 65,536 wire bytes. Excess answers 413 request_body_too_large before JSON parsing. Empty bodies keep their default selections. The published settle lane: re-render one hexbin, grid, cluster, or heatmap layer under a reader's ephemeral selections — cells re-bin and clusters recount, read-only, with the same token checks and rate limit as other published reads. Selections may only reference fields the published surface declares — the layer's effective published field set, or a published widget's field; anything else answers 400 field_not_published before evaluation. Responses carry the effective set, and a hidden layer answers 404 like an absent one. Selection documents above 65,536 bytes are refused even when their filters meet the semantic count limits.

Parameters

• tokenPathrequired

  Publish token (22 characters).

  string

• layerIdPathrequired

  Layer id within the published map.

  string

Request body (optional)

At most 65,536 bytes (64 KiB); a larger body is refused with request_body_too_large.

application/json

object

• selectionsarray of LayerFilter

Responses

• 200

  Success.

  application/json

  LayerRender

• 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

• 413default

  Error with a machine-readable code and human message.

  application/json

  Error

• 429

  rate_limited: Too many requests. Please slow down.

  application/json

  Error

• 503

  ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.

  application/json

  Error

Also on this path: OPTIONS under System.

/api/published/{token}/tiles/{layerId}/{z}/{x}/{y}

GETOne vector tile of a published map's layer

Sign-in No sign-in

Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. Read-only under the publish token, in the tile-sized anonymous rate bucket. Only the layer's current ready server-shipped result is eligible; revocation, deletion, replacement, an inline transition, or a stale version returns the same clean not-found. Use the URL template the published view reports. Current tiles are private and must revalidate at the origin; a valid unchanged artifact may answer conditionally. A spot the current archive does not cover returns 204 with no body.

Parameters

• tokenPathrequired

  Publish token (22 characters).

  string

• layerIdPathrequired

  Layer id within the published map.

  string

• zPathrequired

  Tile zoom.

  string

• xPathrequired

  Tile column.

  string

• yPathrequired

  Tile row.

  string

• vQuery

  Artifact version from the published view's URL template. When supplied, it must still be current.

  string

Responses

• 200

  The tile.

  application/vnd.mapbox-vector-tile

  stringformat binary

• 204

  No tile at these coordinates.

• 304

  The authorized current artifact matches If-None-Match.

• 404

  The publication or requested tile artifact is not current.

  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

• 429

  rate_limited: Too many requests. Please slow down.

  application/json

  Error

• 503

  ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.

  application/json

  Error

• default

  Error with a machine-readable code and human message.

  application/json

  Error

• HEADRead response headers

  Sign-in No sign-inAnswers 200, 204, 304, 404, 405, 429, 503, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/published/{token}/basemaps/satellite

GETThe imagery style of a published map

Sign-in No sign-in

Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. The imagery style for a published page's reader, who is not signed in: the signed-in style's document, its raster source naming this publication's own tile address, /api/published/{token}/basemaps/satellite/tiles/{z}/{x}/{y}{ratio}, never the configured tile template. The published view's basemapUrl and the page's basemap switcher name this address. In the view budget. Served under the publish token only while the publication resolves, as its layer tiles are: a revoked or unknown token answers the same clean not_found, and so does a publication whose reader is not shown Satellite (the map is not on it, and its basemap switcher is off or no longer offers it). An instance with no imagery to draw now, none configured or a stored template its key no longer opens, answers 404 as the signed-in style does while none is configured. Private, no-store.

Parameters

• tokenPathrequired

  Publish token (22 characters).

  string

Responses

• 200

  The style document.

  application/json

  object

• 404

  The publication is not current or does not show Satellite (not_found), or no imagery is configured.

  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

• 429

  rate_limited: Too many requests. Please slow down.

  application/json

  Error

• 503

  ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.

  application/json

  Error

• default

  Error with a machine-readable code and human message.

  application/json

  Error

• HEADRead response headers

  Sign-in No sign-inAnswers 200, 404, 405, 429, 503, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.

/api/published/{token}/basemaps/satellite/tiles/{z}/{x}/{y}

GETOne imagery tile of a published map

Sign-in No sign-in

Verified ingress source is charged before token resolution, including unknown tokens. The five view operations, the satellite style among them, share one source budget across tokens (default 60 per ten seconds); tiles, the satellite tiles among them, have a separate budget (default 600). Missing or forged provenance answers 503 ingress_unavailable. The combined state holds at most 10,000 entries, expired on traffic then evicted least recently used; eviction grants a fresh window. Untrusted proxies share their socket budget. Every address of one IPv6 /64 is charged to one budget; an IPv4 source is charged alone, whether mapped, reaching the instance through the NAT64 prefix 64:ff9b::/96, or neither. The token evaluates the map's SQL in its SQL home with the map owner's current reach, independently of visitor credentials, including while the owner is deactivated, restricted to the datasets the map's own layers name: nothing else of the owner's space is mounted for the link. A layer or widget that reads the instance's catalogue fails with catalogue_not_published while the owner holds datasets the map does not name, and one naming a dataset the owner can no longer reach fails with sql_error. Before first-account setup, a legacy token has only its pending-adoption publication scope; setup retires that scope atomically. Revocation is checked after asynchronous work before returning results. The projection never exposes account identity, private SQL, dataset paths or connection credentials. Fetched now by the server from the tile template this instance configures and passed back, so the template and a key in it never leave the server. Use the tile address the imagery style names. Only the tile's z, x and y reach the template, each a whole number in plain decimal, z from 0 to 19 and x and y below 2 to the power of z, the row followed by @2x for a high-density tile or by nothing; anything else is refused with invalid_request before the imagery is asked. The template is filled from these alone as MapLibre fills a raster template: {z}, {x}, {y} (counted by the style source's scheme), {ratio} (@2x or nothing), {quadkey}, {prefix} and {bbox-epsg-3857}. No query, header or credential of the request goes with them. The fetch takes the egress policy at every hop, waits at most ten seconds and reads at most 4 MiB; only a whole PNG, JPEG, GIF, WebP or AVIF image passes back, with the type its bytes are, and no tile is stored. Every failure upstream answers imagery_unavailable, whose message says what went wrong and never the tile address or its key; a template carrying a user name or password is not drawn and answers the same. Private, no-store. In the tile budget. Served under the publish token only while the publication resolves, as its layer tiles are: a revoked or unknown token answers the same clean not_found, and so does a publication whose reader is not shown Satellite (the map is not on it, and its basemap switcher is off or no longer offers it). An instance with no imagery to draw now, none configured or a stored template its key no longer opens, answers 404 as the signed-in style does while none is configured. The token is checked again once the tile has come, so a publication revoked meanwhile passes nothing back.

Parameters

• tokenPathrequired

  Publish token (22 characters).

  string

• zPathrequired

  Tile zoom, 0 to 19.

  string

• xPathrequired

  Tile column, below 2 to the power of z.

  string

• yPathrequired

  Tile row, below 2 to the power of z, followed by @2x for a high-density tile.

  string

Responses

• 200

  The tile, as the imagery drew it.

  image/png

  stringformat binary

  image/jpeg

  stringformat binary

  image/gif

  stringformat binary

  image/webp

  stringformat binary

  image/avif

  stringformat binary

• 400504default

  Error with a machine-readable code and human message.

  application/json

  Error

• 404

  The publication is not current or does not show Satellite (not_found), or no imagery is configured.

  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

• 429

  rate_limited: Too many requests. Please slow down.

  application/json

  Error

• 502

  imagery_unavailable: the imagery failed, or this instance's egress policy refused its address.

  application/json

  Error

  • X-Dezfil-Egress-RefusedHeader

    imagery where the egress policy refused the imagery's address, at its host or at a redirect; absent for every other failure. An image export that meets it refuses its image rather than make it without the imagery.

    stringalways imagery

• 503

  ingress_unavailable: The instance cannot serve published maps yet. Private, no-store; refused before body work or publication resolution.

  application/json

  Error

• HEADRead response headers

  Sign-in No sign-inAnswers 200, 400, 404, 405, 429, 502, 503, 504, defaultAllow GET, HEAD, OPTIONS

  Automatic HEAD uses GET with no response body.

Also on this path: OPTIONS under System.