API reference

HTTP routes and request contracts

Production apps normally consume the generated style URL. Trusted servers and the CLI use the versioned API for project status, deploys, tilesets, and static map creation.

Base URL

https://api.tileflow.dev

Prefer the CLI for config-driven deploys.It validates the typed config, handles every named map, and writes the frontend manifest after publication.

Routes

Delivery, project, and write endpoints

Delivery assets are loaded by MapLibre. Project and write endpoints require a bearer key with the stated scope.

Delivery

GET/maps/:mapId/style.jsonOrigin checked for restricted maps

MapLibre style document for a deployed Tileflow map.

GET/tiles/:tilesetId/tiles.jsonPublic for world/terrain; tenant maps require map ID in production

TileJSON metadata used by the generated style.

GET/tiles/:tilesetId/:version/:z/:x/:y.pbfPublic for world/terrain; tenant maps require map ID in production

Immutable vector tile delivery from an exact retained PMTiles archive.

GET/v1/styles/:projectId/:environment.jsonOrigin checked for restricted maps

Compatibility project/environment style URL for deployed maps.

GET/fonts/:fontstack/:range.pbfPublic immutable asset

MapLibre glyph range used by text layers.

GET/sprites/:spriteId/:filePublic immutable asset

Sprite JSON or PNG used by MapLibre icon layers.

GET/maps/:mapId/static.pngDevelopment/self-hosting only

Convenience PNG shortcut; disabled on the hosted production API.

GET/static-maps/v1/:hash.pngPublic immutable asset

Immutable generated PNG served from the static map cache.

Project

GET/v1/meBearer key

Authenticated API key ID, project ID, and granted scopes.

GET/v1/statusBearer key with a read or write scope

Registered tilesets, PMTiles archives, orphan uploads, and deployed styles.

GET/v1/usage/summaryBearer key with usage:read

Daily project usage over a bounded date range.

GET/v1/billing/configBearer key with billing:read

Billing capability state; hosted subscription checkout is disabled prelaunch.

Write

POST/v1/stylesBearer key with styles:write

Validate and deploy one map environment to a stable style URL.

POST/v1/tilesetsBearer key with tilesets:write or styles:write

PUT/v1/tilesets/:tilesetId/archive.pmtilesBearer key with tilesets:write or styles:write

Validate and publish a PMTiles archive of at most 32 MiB.

POST/v1/static/mapsBearer key with static:write

Create or reuse a deterministic static map image from scene JSON.

POST/v1/static/maps/precacheBearer key with static:write

Idempotently warm the cache for the same static map scene.

POST/v1/usageBearer key with usage:write + Idempotency-Key

Record a bounded custom usage event exactly once per project and key.

POST/v1/billing/checkoutBearer key with billing:write + Idempotency-Key

Reserved subscription flow; returns 503 in hosted production until billing launch.

Authentication

Send bearer keys only from trusted environments

Use Authorization: Bearer $TILEFLOW_API_KEY. Missing or invalid keys return 401; valid keys without the required scope return 403. Never expose project keys in browser code. Mutation endpoints that declare Idempotency-Key require an 8–128 character key and scope it to the authenticated project.

Style deploy

Publish one environment directly

POST /v1/styles accepts an environment name, optional tileset ID, map config, themes, and icon metadata. The authenticated project is derived from the key and cannot be selected in the request body.

Terminal

curl https://api.tileflow.dev/v1/styles \
  -H "Authorization: Bearer $TILEFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "madrid",
    "tilesetId": "world",
    "config": {
      "basemap": { "type": "osm" },
      "theme": "light",
      "view": { "center": [-3.7038, 40.4168], "zoom": 12 }
    }
  }'

Static map

Create an image from a complete scene

The scene identifies a deployed map, camera, output size, and optional overlays. Use @tileflow/static when possible so validation happens before the request.

Terminal

curl https://api.tileflow.dev/v1/static/maps \
  -H "Authorization: Bearer $TILEFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "map": "madrid",
    "camera": {
      "type": "center",
      "center": [-3.7038, 40.4168],
      "zoom": 12
    },
    "size": {
      "width": 1200,
      "height": 800
    },
    "overlays": []
  }'

Responses

URLs are stable; generated assets are immutable

A style deploy returns the compatibility URL and the preferred public map URL. Static map creation returns imageUrl, hash, cached, and a ready status.

Style deploy response

{
  "mapId": "map_1234567890abcdef",
  "mapUrl": "https://api.tileflow.dev/maps/map_1234567890abcdef/style.json",
  "styleId": "sty_456",
  "url": "https://api.tileflow.dev/v1/styles/prj_123/madrid.json"
}

Static map response

{
  "cached": false,
  "hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "imageUrl": "https://api.tileflow.dev/static-maps/v1/AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA.png",
  "status": "ready"
}

Errors and cache

Handle status codes and the JSON error body

Invalid JSON or config returns 400, missing project resources return 404, conflicting registrations return 409, and oversized requests return 413. Temporary service or capacity failures return 503. Immutable generated PNGs include X-Tileflow-Cache on cache reads.

Error response

{
  "error": "Invalid config",
  "messages": [
    {
      "level": "error",
      "path": "view.center",
      "message": "Expected a longitude and latitude pair"
    }
  ]
}