Get started
Map Studio API

Event streams and sync

Event streams and sync

Keep your own copy of your organization's content up to date in two moves. List what changed since your last sync, then hold the organization's event stream open to hear about each change. A server that holds no connection open receives webhook events instead.

Before you start

The event stream acts as a member, so mint a session token that names one, as in the quickstart:

export MOUNTAYA_SESSION_TOKEN=$(curl -s -X POST https://api.mountaya.com/v1/sessions \
  -H "X-API-Key: $MOUNTAYA_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"publishable_key\": \"$MOUNTAYA_PUBLISHABLE_KEY\", \"user_id\": \"7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1\", \"surface\": \"studio-embedded\"}" \
  | jq -r .data.token)

List what changed

updated_since lists only what changed at or after an instant. Sort by updated_at, and keep the latest updated_at you read for your next sync.

curl -s "https://api.mountaya.com/v1/itineraries?updated_since=2026-11-09T00:00:00Z&sort=updated_at&limit=50" \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  | jq '{changed: [.data[] | {id, name, updated_at}], pagination: .extensions.metadata.pagination}'
Response
{
  "changed": [
    {
      "id": "0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21",
      "name": "Tour du Mont-Blanc",
      "updated_at": "2026-11-09T10:53:23.316072Z"
    },
    {
      "id": "3e8a5f21-9c47-4d6b-b0e3-6a1f7d2c9b54",
      "name": "Chamonix to Argentière",
      "updated_at": "2026-11-09T11:20:42.525768Z"
    }
  ],
  "pagination": {
    "limit": 50,
    "next_cursor": null
  }
}

Zones and collections take updated_since the same way, at /v1/zones and /v1/collections. A listing does not show what was deleted: the event stream does.

Follow the event stream

GET /v1/organizations/{organization_id}/events is a server-sent event stream. Each frame names an itinerary, a zone or a collection that was created, updated or deleted. Refetch what it names.

ORGANIZATION_ID=$(curl -s -X POST https://api.mountaya.com/v1/organizations/lookup \
  -H "Content-Type: application/json" \
  -d "{\"publishable_key\": \"$MOUNTAYA_PUBLISHABLE_KEY\"}" | jq -r .data.id)

# Reads for ten seconds: curl exits 28 when --max-time ends it. Drop it to stay connected.
curl -sN --max-time 10 "https://api.mountaya.com/v1/organizations/$ORGANIZATION_ID/events" \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" || [ $? -eq 28 ]
Stream
id: 1794222259487-0
event: collection.changed
data: {"type":"collection.changed","kind":"collection","action":"updated","id":"59cfff6f-29bb-49e9-9090-91e211151802","itinerary_id":"00000000-0000-0000-0000-000000000000","organization_id":"a5eec5f3-3463-4b20-9469-de3eeb870a7a","revision":0,"actor_id":"7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1","occurred_at":"2026-11-09T11:04:19.456109Z"}

id: 1794222300297-0
event: itinerary.changed
data: {"type":"itinerary.changed","kind":"itinerary","action":"created","id":"0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21","itinerary_id":"0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21","organization_id":"a5eec5f3-3463-4b20-9469-de3eeb870a7a","revision":1,"actor_id":"7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1","occurred_at":"2026-11-09T11:05:00.29693Z"}

One itinerary or zone at a time

GET /v1/itineraries/{itinerary_id}/events and GET /v1/zones/{zone_id}/events stream one resource's edits as they happen: its segments and waypoints, and who is editing. They are what Map Studio's collaboration runs on.

Next steps

Last updated