Get started
Map Studio API

Publishing

Publishing

An itinerary is a draft that only your organization's members see. Publishing copies the draft into a publication, which is what embeds, share links, route files and tiles show. Publishing needs 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 below publish $ITINERARY_ID, an itinerary of yours with at least one segment.

Publish

POST on the itinerary's publication publishes its current draft. It takes no body and is safe to repeat.

curl -s -X POST https://api.mountaya.com/v1/itineraries/$ITINERARY_ID/publication \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  | jq '.data | {status, published_at, has_unpublished_changes}'
Response (abridged)
{
  "status": "published",
  "published_at": "2026-11-09T11:04:04.139845Z",
  "has_unpublished_changes": false
}

Edit after a publish

Edits change the draft only. The itinerary reports has_unpublished_changes until you publish again.

curl -s -X PATCH https://api.mountaya.com/v1/itineraries/$ITINERARY_ID \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"description": "Day one, through Chamonix."}' \
  | jq '.data | {description, status, has_unpublished_changes}'
Response (abridged)
{
  "description": "Day one, through Chamonix.",
  "status": "published",
  "has_unpublished_changes": true
}

Visitors still see the published version. Publish again to show the edit.

Take it down

DELETE on the publication stops serving the itinerary. The draft stays, and you can publish it again later.

curl -s -X DELETE https://api.mountaya.com/v1/itineraries/$ITINERARY_ID/publication \
  -H "X-API-Key: $MOUNTAYA_PUBLISHABLE_KEY" \
  -H "X-Session-Token: $MOUNTAYA_SESSION_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  | jq '.data | {status, published_at}'
Response (abridged)
{
  "status": "draft",
  "published_at": null
}

When a publish is refused

StatusCodeWhyDo
409CONFLICTThe itinerary has no segmentsAdd a segment
409CONFLICTA collaborator is editing it in Map StudioRetry once they finish
402PAYMENT_REQUIREDYour agreement does not include Map PublishingTalk to us
429LIMIT_REACHEDYou publish as many itineraries as your agreement allowsTake one down, or raise the limit
412PRECONDITION_FAILEDThe itinerary changed since you read itRead it again

A collaborator's edit names them in the answer:

Response
{
  "errors": [
    {
      "message": "An edit is in progress. Finish it before publishing.",
      "extensions": { "code": "CONFLICT" }
    }
  ],
  "extensions": {
    "metadata": {
      "holder": { "id": "7a4e1c98-3b52-4f60-9d81-c05e2f7a83b1" }
    }
  }
}

Zones

A zone publishes the same way, at /v1/zones/{zone_id}/publication. Collection embeds and collection share links show a zone once it is published and public.

Next steps

Last updated