Get started
Map Studio API

Collections and share links

Collections and share links

A collection groups itineraries and zones, like a folder. A share link opens one collection, or one itinerary, to whoever holds the link, as a read-only map in Mountaya. Share links need Map Publishing in your agreement.

Before you start

Writes act 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)

The examples file $ITINERARY_ID, a published itinerary of yours.

Create a collection

A collection takes a name and whether it is private.

COLLECTION_ID=$(curl -s -X POST https://api.mountaya.com/v1/collections \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Chamonix day hikes", "description": "Day hikes around Chamonix.", "is_private": false}' \
  | jq -r .data.id)
Response (abridged)
{
  "data": {
    "id": "59cfff6f-29bb-49e9-9090-91e211151802",
    "name": "Chamonix day hikes",
    "description": "Day hikes around Chamonix.",
    "is_private": false,
    "count": { "itineraries": 0, "zones": 0 },
    "etag": "\"d1\"",
    "role": "owner"
  }
}

File itineraries and zones

Add itineraries by id. Zones are filed the same way, at /zones with zone_ids.

curl -s -X POST https://api.mountaya.com/v1/collections/$COLLECTION_ID/itineraries \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"itinerary_ids\": [\"$ITINERARY_ID\"]}" \
  | jq '.data.count'
Response (abridged)
{
  "itineraries": 1,
  "zones": 0
}

POST on the collection's share link mints one, or returns the one it already has.

SHARE_TOKEN=$(curl -s -X POST https://api.mountaya.com/v1/collections/$COLLECTION_ID/share-link \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  | jq -r .data.share_token)

echo "https://app.mountaya.com/studio/share?collection_id=$COLLECTION_ID&share_token=$SHARE_TOKEN"
Response
{
  "data": {
    "created_at": "2026-11-09T11:04:27.449694Z",
    "share_token": "share_your_share_token"
  }
}

The link opens a read-only map of the collection's published itineraries, and of its published public zones. Anyone who holds it can open it, with no account.

Your own code reads the shared content with the token in X-Share-Token, and no key.

curl -s https://api.mountaya.com/v1/collections/$COLLECTION_ID/itineraries \
  -H "X-Share-Token: $SHARE_TOKEN" \
  | jq '[.data[] | {name, status}]'
Response (abridged)
[
  {
    "name": "Chamonix to Argentière",
    "status": "published"
  }
]
  • POST /v1/collections/{collection_id}/share-link/rotate replaces the token. The old URL stops working.
  • DELETE /v1/collections/{collection_id}/share-link removes the link.

An itinerary has its own link at /v1/itineraries/{itinerary_id}/share-link, with the same calls. A zone has none: share it through a collection.

Next steps

Last updated