Quickstart

An itinerary picks its activity at creation and keeps it for life — every segment inherits it. Activities are identified by uuid, so read the catalog once and cache it.

curl https://internal.mountaya.com/v1/activities \
  -H "X-API-Key: pk_your_publishable_key"

Reads take the key alone. The next three calls write, so they each add X-User-Id.

POST /v1/itineraries takes a name, the activity id, and whether the itinerary is private. It answers 201 Created with the itinerary and its empty segments and waypoints arrays.

curl -X POST https://internal.mountaya.com/v1/itineraries \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-User-Id: 7f3c1d92-4a08-4b6e-9c15-2d84e0b7a361" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "is_private": true
  }'

A name already taken inside the organization answers 409 Conflict, naming the itinerary that holds it at extensions.metadata.itinerary.

Segments carry the geometry. A segment in directions mode takes between 2 and 45 waypoints as a GeoJSON LineString, and the router snaps them to the trail network for the itinerary's activity.

curl -X POST https://internal.mountaya.com/v1/itineraries/$ITINERARY_ID/segments \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-User-Id: 7f3c1d92-4a08-4b6e-9c15-2d84e0b7a361" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Day 1: Col de Voza",
    "mode": "directions",
    "speed": 4.5,
    "geojson": {
      "type": "LineString",
      "coordinates": [[6.7986, 45.8918], [6.7621, 45.8842], [6.7280, 45.8215]]
    }
  }'

Coordinates are [longitude, latitude] in WGS 84. Distance, duration, ascent, surface, and way type come back computed from the routed line — you never send them, and sending them changes nothing.

To draw a line the router should leave alone, send "mode": "linestring" and the geometry is stored as given.

Editing changes only the draft. Share links, embeds, and the tiles they render serve the last published snapshot, and an itinerary that has never been published resolves to nothing on any of them. Publishing freezes the current draft into the next publication.

curl -X POST https://internal.mountaya.com/v1/itineraries/$ITINERARY_ID/publish \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-User-Id: 7f3c1d92-4a08-4b6e-9c15-2d84e0b7a361"

The call takes no body and returns the itinerary with its status, published_at, and has_unpublished_changes reflecting the new publication. An itinerary with no segments is refused with a 400; one whose segments a collaborator still holds open is refused with a 409 naming that collaborator at extensions.metadata.holder.id, so you can say who to wait for rather than just that the publish failed. See conflicts.