REST API

{ "error": { "code": "unauthorized", "message": "Provide a session or Bearer spk_ token" } }

TOKEN=spk_…
BASE=https://spatly.io/api/v1
curl -H "Authorization: Bearer $TOKEN" $BASE/me

{ "error": { "code": "not_found", "message": "Project not found" } }

{ "items": [ … ], "nextCursor": "bzoz" }

curl -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -X POST $BASE/features/query -d '{
    "datasetId": "DATASET_ID",
    "where": { "mag": { "gte": 7 } },
    "orderBy": "mag", "order": "desc",
    "select": ["place", "mag", "time_iso"],
    "geometry": false,
    "limit": 5
  }'

{ "type": "FeatureCollection",
  "features": [ { "type": "Feature", "id": "us6000m0xl", "geometry": null,
                  "properties": { "mag": 7.5, "place": "2024 Noto Peninsula, Japan Earthquake", "__fid": "us6000m0xl" } } ],
  "total": 4, "limit": 5, "offset": 0, "nextCursor": null,
  "budget": { "maxLimit": 500, "requireBbox": false } }

{ "metricId": "…", "value": 344, "previous": 301,
  "series": [{ "t": "2024-01", "v": 28 }], "breakdown": [{ "key": "mww", "v": 55 }],
  "asOf": "2026-09-02T15:56:14.228Z", "status": "ok" }

TOKEN=spk_…
BASE=https://spatly.io/api/v1
H=(-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json')

# 1. a project, with the slug you will look it up by on the next run
PID=$(curl -s "${H[@]}" -X POST $BASE/projects -d '{"name":"Wildfire watch","basemapId":"noir"}' | jq -r .id)
curl -s "${H[@]}" -X PATCH $BASE/projects/$PID -d '{"slug":"wildfire-watch"}'

# 2. a live dataset, then its time column
DS=$(curl -s "${H[@]}" -X POST $BASE/datasets/from-url \
      -d '{"url":"https://example.com/feed.geojson","name":"Events","refreshSec":60}' | jq -r .dataset.id)
curl -s "${H[@]}" -X PATCH $BASE/datasets/$DS -d '{"timeField":"ignition_time_est"}'

# 3. a styled layer (this also attaches the dataset to the project)
LID=$(curl -s "${H[@]}" -X POST $BASE/projects/$PID/layers -d '{
  "datasetId":"'$DS'", "name":"Events", "renderType":"symbol",
  "style":{"markId":"incident","classification":{"field":"tier","method":"categorical","stops":["aday","onayli","teyitli"],"ramp":["#8A93A0","#F5A524","#EB3434"]}},
  "interactive":{"click":true,"titleField":"#{{event_id}} · {{tier}}","tooltipFields":["tier","status","frp_max"],
                 "media":{"videoField":"video_url","posterField":"poster_url","expiresField":"expires_at"}},
  "legend":{"show":true,"title":"Tier"} }' | jq -r .id)

# 4. a KPI
MID=$(curl -s "${H[@]}" -X POST $BASE/projects/$PID/metrics \
      -d '{"name":"Open events","datasetId":"'$DS'","aggregation":"count","filter":["==",["get","status"],"open"],"spatialScope":"viewport"}' | jq -r .id)

# 5. a dashboard surface, then its body
SID=$(curl -s "${H[@]}" -X POST $BASE/projects/$PID/surfaces -d '{"kind":"dashboard","name":"Wildfire watch"}' | jq -r .id)
curl -s "${H[@]}" -X PATCH $BASE/surfaces/$SID -d '{
  "settings":{"variant":"ops"},
  "body":{"id":"root","type":"dashboard","props":{"variant":"ops","refreshSec":60,"cols":24,"showAsOf":true},
    "children":[
      {"id":"w1","type":"mapWidget","props":{"title":"Map"},"layout":{"grid":{"desktop":{"x":0,"y":0,"w":18,"h":14}}}},
      {"id":"w2","type":"kpiWidget","props":{"title":"Open events","metricId":"'$MID'"},"layout":{"grid":{"desktop":{"x":18,"y":0,"w":6,"h":4}}}}
    ]}}'

# 6. publish
curl -s "${H[@]}" -X POST $BASE/surfaces/$SID/publish -d '{"visibility":"public","allowEmbed":true}'

TOKEN=spk_…
BASE=https://spatly.io/api/v1

curl -H "Authorization: Bearer $TOKEN" $BASE/me
curl -H "Authorization: Bearer $TOKEN" "$BASE/projects?limit=10"
curl -H "Authorization: Bearer $TOKEN" $BASE/projects/PROJECT_ID

# geocode → save a beat → add a chapter → publish
curl -H "Authorization: Bearer $TOKEN" "$BASE/geocode?q=Antakya&limit=1"

curl -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -X POST $BASE/projects/PROJECT_ID/beats -d '{
    "name": "Antakya",
    "bbox": [36.05, 36.1, 36.3, 36.3],
    "layerStates": { "LAYER_ID": { "visible": true, "filter": [">=", ["get", "mag"], 4] } }
  }'

curl -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -X POST $BASE/surfaces/STORY_ID/chapters -d '{
    "title": "Antakya, 6 February",
    "text": "At 04:17 local time…\n\n> A quote from the field.",
    "bbox": [36.05, 36.1, 36.3, 36.3],
    "highlight": { "layerId": "LAYER_ID", "filter": [">=", ["get", "mag"], 7], "pulse": true }
  }'

curl -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -X POST $BASE/surfaces/STORY_ID/publish -d '{"visibility":"unlisted"}'

# poll a KPI with an ETag
curl -i -H "Authorization: Bearer $TOKEN" -H 'If-None-Match: W/"ba2f293c2bcc"' \
  https://spatly.io/api/live/metrics/METRIC_ID