Get started

Itineraries

Itineraries

Routes, end to end: create one, publish it, duplicate it, export it to GPX or KML, and hand it out behind a share link. An itinerary owns its segments and waypoints and carries the totals computed from them.

The Itinerary object

An itinerary organizing one or more segments into a multi-day or multi-stage plan for an outdoor activity.

activity_id

string (uuid)

required

Identifier of the activity type for the whole itinerary. Set at creation and immutable; every segment shares this activity.

ascent

integer (int32) | null

required

Total elevation gain across all of the itinerary's segments, in meters (the sum of each segment's ascent). Matches the unit of ItinerarySegment.ascent. Null when no segment contributes an ascent value (e.g. the itinerary has no segments, or none carry elevation data).

count

object

required

How many segments and waypoints the itinerary holds. A summary count, so a client can size a list without fetching the details.

created_at

string (date-time)

required

Timestamp of the itinerary's creation.

created_by

object

required

The user who created the itinerary. It is the author rather than the last editor, and it does not move when another member edits the itinerary.

description

string | null

required

Free-text description of the itinerary. Null when it has none.

distance

number (double) | null

required

Total distance across all of the itinerary's segments, in meters (the sum of each segment's distance). Matches the unit and measurement basis of ItinerarySegment.distance, so segments routed through waypoints and drawn freehand sum to a single comparable quantity. Null when no segment contributes a distance value (e.g. the itinerary has no segments, or none have been computed).

id

string (uuid)

required

Unique identifier of the itinerary.

is_private

boolean

required

Whether the itinerary is private. A private itinerary is reached only with the key of the organization that owns it, so a private personal itinerary, owned by no organization, is reached by no key. A public itinerary is readable by id, read-only, by any publishable key, as last published, and it is listed only in its own organization's listings. A share token reaches only what its link names, the itinerary or a collection holding it, and reaches it whatever this says. Public never grants editing, which takes a write role in the owning organization. Privacy is read from the draft, so a change takes effect at once rather than at the next publish.

is_verified

boolean

required

Whether the itinerary has been verified by the organization.

name

string

required

Display name of the itinerary.

organization_id

string (uuid) | null

required

Identifier of the organization that owns this itinerary. Null for a personal itinerary, made from an individual account and owned by no organization.

etag

string

required

The version of everything a read of this itinerary returns, the one the ETag of that read carries, opaque and compared whole. Unlike revision, it moves on every write that changes the read: the itinerary's own fields, a segment, segment group or waypoint, a merge, split or convert, and a publish or unpublish, so a client holding it knows whether anything it shows is stale. A share link minted or revoked leaves it where it is. A draft read and a read served the published snapshot carry different tags. Send it as If-Match to make a write to the itinerary conditional.

revision

integer (int32)

required

Revision number of the itinerary's own fields: 1 at creation, and raised by every accepted patchItinerary, even one that changes nothing. Edits to its segments, waypoints and groups leave it where it is, since each of those carries a revision of its own. On a read served the published snapshot it is the publication number instead. A consumer holding an older copy compares it with the revision a change frame carries; no request takes it.

status

string

required

One of: draft, published

Whether the itinerary is published right now, that is whether it has a live publication. Derived server-side; read-only and never accepted as an input. Taking an itinerary down returns it to draft, although its publication number is kept, so a later publish takes the next one. Note this is independent of is_private: a draft is invisible on the public surfaces however public its privacy setting says it is.

updated_at

string (date-time)

required

Timestamp of the itinerary's last change, counting changes to its segments, segment groups and waypoints, a deletion among them. Always present: it equals created_at until the itinerary is first changed.

The ItineraryWithDetails object

An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.

activity_id

string (uuid)

required

Identifier of the activity type for the whole itinerary. Set at creation and immutable; every segment shares this activity.

ascent

integer (int32) | null

required

Total elevation gain across all of the itinerary's segments, in meters (the sum of each segment's ascent). Matches the unit of ItinerarySegment.ascent. Null when no segment contributes an ascent value (e.g. the itinerary has no segments, or none carry elevation data).

count

object

required

How many segments and waypoints the itinerary holds. A summary count, so a client can size a list without fetching the details.

created_at

string (date-time)

required

Timestamp of the itinerary's creation.

created_by

object

required

The user who created the itinerary. It is the author rather than the last editor, and it does not move when another member edits the itinerary.

description

string | null

required

Free-text description of the itinerary. Null when it has none.

distance

number (double) | null

required

Total distance across all of the itinerary's segments, in meters (the sum of each segment's distance). Matches the unit and measurement basis of ItinerarySegment.distance, so segments routed through waypoints and drawn freehand sum to a single comparable quantity. Null when no segment contributes a distance value (e.g. the itinerary has no segments, or none have been computed).

id

string (uuid)

required

Unique identifier of the itinerary.

is_private

boolean

required

Whether the itinerary is private. A private itinerary is reached only with the key of the organization that owns it, so a private personal itinerary, owned by no organization, is reached by no key. A public itinerary is readable by id, read-only, by any publishable key, as last published, and it is listed only in its own organization's listings. A share token reaches only what its link names, the itinerary or a collection holding it, and reaches it whatever this says. Public never grants editing, which takes a write role in the owning organization. Privacy is read from the draft, so a change takes effect at once rather than at the next publish.

is_verified

boolean

required

Whether the itinerary has been verified by the organization.

name

string

required

Display name of the itinerary.

organization_id

string (uuid) | null

required

Identifier of the organization that owns this itinerary. Null for a personal itinerary, made from an individual account and owned by no organization.

etag

string

required

The version of everything a read of this itinerary returns, the one the ETag of that read carries, opaque and compared whole. Unlike revision, it moves on every write that changes the read: the itinerary's own fields, a segment, segment group or waypoint, a merge, split or convert, and a publish or unpublish, so a client holding it knows whether anything it shows is stale. A share link minted or revoked leaves it where it is. A draft read and a read served the published snapshot carry different tags. Send it as If-Match to make a write to the itinerary conditional.

revision

integer (int32)

required

Revision number of the itinerary's own fields: 1 at creation, and raised by every accepted patchItinerary, even one that changes nothing. Edits to its segments, waypoints and groups leave it where it is, since each of those carries a revision of its own. On a read served the published snapshot it is the publication number instead. A consumer holding an older copy compares it with the revision a change frame carries; no request takes it.

status

string

required

One of: draft, published

Whether the itinerary is published right now, that is whether it has a live publication. Derived server-side; read-only and never accepted as an input. Taking an itinerary down returns it to draft, although its publication number is kept, so a later publish takes the next one. Note this is independent of is_private: a draft is invisible on the public surfaces however public its privacy setting says it is.

updated_at

string (date-time)

required

Timestamp of the itinerary's last change, counting changes to its segments, segment groups and waypoints, a deletion among them. Always present: it equals created_at until the itinerary is first changed.

groups

array of ItinerarySegmentGroup

required

Segment groups defined on this itinerary. Flat, not nested inside the segments: the ordered segment chain stays the primary structure, and each segment points back at its group through its group_id. Empty when the itinerary has no groups.

has_unpublished_changes

boolean

required

Whether the draft has been edited since the last publish, so the public surfaces are serving something older than what the studio shows. Derived server-side by comparing the itinerary's updated_at against its latest publication; read-only and never accepted as an input. Every write to the itinerary, its segments, its segment groups and its waypoints moves updated_at, a deletion among them, so each of those edits sets it. Always false while status is draft. status itself is on Itinerary, so a listing answers "is this live" without this read.

published_at

string (date-time) | null

required

Timestamp of the itinerary's live publication, or null when it has none: when it has never been published, or has been taken down. Derived server-side: publishing is the only thing that sets it, taking the itinerary down clears it, and it is never accepted as an input.

segments

array of ItinerarySegment

required

Ordered list of segments belonging to this itinerary.

waypoints

array of ItineraryWaypoint

required

Ordered list of waypoints belonging to this itinerary.

The share link of one itinerary or one collection: the token that opens it and when it was minted. A resource has at most one link at a time.

share_token

string

required

The share credential: the literal prefix share_ followed by 32 lowercase hexadecimal characters.

created_at

string (date-time)

required

When this token was minted: when the link was first made, or last rotated.

List the itineraries the credential reaches

Returns the itineraries of the key's organization that the request's credential reaches, one page at a time. Each itinerary carries its summary fields and counts but not its segments and waypoints, which getItinerary returns.

Query parameters

organization_id

string (uuid)

in query

The organization to list for. It can only be the key's organization, which is also what the listing covers when this is omitted; any other identifier is a 403, whether or not it exists. A personal resource, owned by no organization, is never listed under a key.

status

string

in query

One of: draft, published

Lists only the itineraries in this publication state: published those with a live publication, draft those with none. Omitted, both are listed. A key alone is served published itineraries only, and so is a key with a session token naming nobody, so draft lists nothing under either.

is_private

boolean

in query

true lists only private items and false only public ones; omitted, both are listed. It narrows and never widens: what a credential lists is still decided by the read tiers in this document's introduction, so a key without a session token naming a member lists no private item whatever this says.

activity_id

string (uuid)

in query

Lists only the itineraries of this activity, one getActivities lists.

in_collection

boolean

in query

true lists only the itineraries filed in at least one collection this credential lists, and false only those filed in none of them. Omitted, both are listed. A key alone lists the organization's public collections only, and so does a key with a session token naming nobody, so under either an itinerary filed only in a private collection counts as filed in none.

updated_since

string (date-time)

in query

Lists only what changed at or after this instant, compared with each item's updated_at. With sort=updated_at, it is how a client picks up what changed since its last read without walking the whole listing.

q

string

in query

Lists only the items whose name contains this text, compared without regard to case. 1 to 100 characters; leading and trailing whitespace is ignored.

sort

string

in query

default: -updated_at

One of: -updated_at, updated_at, -created_at, created_at, name, -name

The order the listing is served in, one key: updated_at and created_at order by those timestamps and name by the itinerary's name, ascending, and a leading - reverses the order. Omitted, the most recently changed comes first (-updated_at). Ties on the key break on id, so the order is total and the same from one page to the next.

cursor

string

in query

Where the page starts: the next_cursor the previous page reported at extensions.metadata.pagination, sent back unchanged. Omitted, the listing starts at its first item.

limit

integer (int32)

in query

default: 50

How many items one page holds, between 1 and 100; 50 when omitted, on every listing that pages. extensions.metadata.pagination.limit reports the size the page was served at. A page shorter than limit is not how the end is told: the end is a next_cursor of null. The page is cut after authorization, so it never widens what a caller can read.

Response 200

One page of the key's organization's itineraries this credential reaches, matching every filter sent, in the order sort names. data is empty when nothing matches. extensions.metadata.pagination reports the page size and the cursor of the next page, null on the last.

extensions

object

required

The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.pagination, the page this listing served and the cursor of the next one.

data

array of Itinerary

required

Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.

# The first page, most recently changed first. Send the page's
# extensions.metadata.pagination.next_cursor as `cursor` for the next one.
curl -s "https://api.mountaya.com/v1/itineraries?sort=-updated_at&limit=20" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": [
    {
      "id": "8f14e45f-ceea-467a-9ba5-2b6d3a71c9e0",
      "name": "Tour du Mont-Blanc",
      "description": "Ten stages from Les Houches, anticlockwise.",
      "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
      "organization_id": "2b7d6e5f-4c3a-4918-8f07-6e5d4c3b2a19",
      "status": "draft",
      "is_private": true,
      "is_verified": false,
      "distance": 169842.5,
      "ascent": 9827,
      "count": {
        "segments": 10,
        "waypoints": 24,
        "groups": 10
      },
      "revision": 7,
      "etag": "\"d31\"",
      "created_at": "2026-07-04T09:12:41Z",
      "updated_at": "2026-07-11T16:03:08Z",
      "created_by": {
        "id": "4d9a2f13-7c60-4b85-9e12-3a8f6b0c5d74"
      }
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

Create a new itinerary

Creates a new itinerary in the key's organization. Returns 409 Conflict when another itinerary in that organization already carries the name. The response is the created itinerary's full draft: its segments and waypoints arrays are empty, and description, distance and ascent are null when it has none.

Webhook events itinerary.created, recorded by the task itinerary.create.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

The new itinerary's name, activity and ownership. Segments and waypoints are added afterwards, through their own operations.

activity_id

string (uuid)

in body

required

Identifier of the activity type for the whole itinerary, one getActivities lists; any other identifier is a 400. Set at creation and immutable; every segment shares this activity.

description

string

in body

Free-text description of the itinerary, at most 100 characters as sent, leading and trailing whitespace included; that whitespace is then trimmed. Omit it, or send one that trims to nothing, to create the itinerary without one.

is_private

boolean

in body

required

Whether the itinerary is private. A private itinerary is reached only with the key of the organization that owns it, so a private personal itinerary, owned by no organization, is reached by no key. A public itinerary is readable by id, read-only, by any publishable key, as last published, and it is listed only in its own organization's listings. A share token reaches only what its link names, the itinerary or a collection holding it, and reaches it whatever this says. Public never grants editing, which takes a write role in the owning organization. Privacy is read from the draft, so a change takes effect at once rather than at the next publish.

name

string

in body

required

Display name of the itinerary, 2 to 30 characters as sent. Leading and trailing whitespace is then trimmed, and what remains must still be at least 2 characters. Refused with a 409 when another itinerary in the organization already carries it; names are compared exactly after trimming, case included. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.

organization_id

string (uuid)

in body

Identifier of the organization that will own the itinerary. It must be the key's organization; omitted, it is that organization.

Response 201

The itinerary as created, with its (empty) segments and waypoints and its starting revision. Location names it, /v1/itineraries/{itinerary_id}, and ETag carries its version.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryWithDetails

required

An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.

See the ItineraryWithDetails object.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

# Keep the Idempotency-Key and send it again on a retry: a create whose answer
# was lost is then answered with the first one's 201 rather than run twice.
curl -s https://api.mountaya.com/v1/itineraries \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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
  }'
201
Response
{
  "data": {
    "id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "is_private": false,
    "is_verified": true,
    "distance": 169800,
    "ascent": 9800,
    "count": {
      "groups": 3,
      "segments": 10,
      "waypoints": 24
    },
    "revision": 42,
    "etag": "\"d118\"",
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "status": "published",
    "published_at": "2026-06-28T16:05:00Z",
    "has_unpublished_changes": false,
    "groups": [
      {
        "id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "name": "Days 1-2",
        "color": "#2f80ed",
        "speed": 4.5,
        "revision": 2,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "segments": [
      {
        "id": "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "group_id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "name": "Day 1: Col de Voza",
        "description": "From Les Houches over the Col de Voza, down the Bon Nant valley.",
        "mode": "directions",
        "position": 0,
        "color": "#2f80ed",
        "speed": 4.5,
        "start_at": "2026-07-04T07:30:00Z",
        "distance": 17400,
        "duration": 14760,
        "ascent": 1080,
        "descent": 720,
        "altitude_min": 942,
        "altitude_max": 1653,
        "gradient_min": -18.4,
        "gradient_max": 21.7,
        "geojson": {
          "type": "GeometryCollection",
          "geometries": [
            {
              "type": "LineString",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.7621,
                  45.8842
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            },
            {
              "type": "MultiPoint",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            }
          ]
        },
        "slope_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 12.4
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": -8.1
          }
        ],
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 2.9
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": 5.6
          }
        ],
        "surface_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": "compacted-gravel"
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": "dirt"
          }
        ],
        "way_type_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "path"
          }
        ],
        "trail_difficulty_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "mountain-hiking"
          }
        ],
        "steps": [
          {
            "from_index": 0,
            "to_index": 1,
            "type": "depart",
            "name": "Route des Chavants",
            "distance": 8400,
            "duration": 7200,
            "exit_number": null
          },
          {
            "from_index": 1,
            "to_index": 2,
            "type": "goal",
            "name": "-",
            "distance": 9000,
            "duration": 7560,
            "exit_number": null
          }
        ],
        "road_access_info": [
          {
            "from_index": 1,
            "to_index": 2,
            "values": [
              "private"
            ]
          }
        ],
        "revision": 7,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "waypoints": [
      {
        "id": "e8b1d740-2a96-4c53-b7f8-15d0a3c69e42",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "mode": "poi",
        "position": 0,
        "name": "Refuge du Fioux",
        "description": "Half-board, book ahead in July.",
        "icon": "hut",
        "color": "#f2994a",
        "geojson": {
          "type": "Point",
          "coordinates": [
            6.7612,
            45.8479
          ]
        },
        "amenities": [
          "water",
          "hot-meal",
          "accommodation",
          "toilets",
          "timing-checkpoint"
        ],
        "timing": {
          "cutoff_at": "2026-08-28T21:30:00Z",
          "stop_duration": 900
        },
        "contact": {
          "website": "https://www.example.com/refuge",
          "phone": "+33 4 50 12 34 56",
          "email": "contact@example.com",
          "address": "74170 Les Contamines-Montjoie, France",
          "opening_hours": "Mid-June to mid-September, 07:00-21:00 daily.",
          "booking_url": "https://www.example.com/refuge/reserver"
        },
        "media": {
          "photos": [
            {
              "url": "https://cdn.example.com/refuge-du-fioux/terrace.jpg",
              "caption": "The terrace at sunrise."
            }
          ],
          "links": [
            {
              "label": "Access from Les Contamines",
              "url": "https://www.example.com/access/les-contamines"
            }
          ]
        },
        "properties": [
          {
            "key": "bib-check",
            "label": "Bib check",
            "value": "Mandatory, both sides",
            "format": "text"
          }
        ],
        "revision": 3,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ]
  }
}

Preview an itinerary import without persisting it

Parses an uploaded itinerary file, segments each track, and computes per-segment mode candidates (directions and/or linestring) with a server recommendation. Nothing is persisted: the response is a reviewable draft the client edits before confirming it with postItineraryImport. Since a preview creates nothing, the request is safe to repeat.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body multipart/form-data

The file to import and the format it is in. The response is a preview to review; nothing is created until it is confirmed.

provider

string

in body

required

One of: gpx, geojson, kml, kmz, fit, tcx

Format the upload is parsed in.

file

string (binary)

in body

required

The uploaded itinerary file, at most 25 MiB. A larger upload is refused with 413, and a file that cannot be read in the named provider's format, or holds no track, is a 400 naming file.

activity_id

string (uuid)

in body

required

Identifier of the activity to use for the import, one getActivities lists. Required: no file format carries an activity the server reads, so there is no choice of the source's to fall back on, and a missing part is a 400 naming activity_id.

organization_id

string (uuid)

in body

Identifier of the organization the preview is scoped to: the organization a confirm will create the itinerary in, so the routing is recorded under it. It must be the key's organization; omitted, it is that organization.

granularity

string

in body

One of: auto, single

Segmentation granularity. Optional: omit the part for auto, semantic splits on.

Response 200

What the source contains: the proposed segments, each with its candidate geometries and a recommendation, and the waypoints found in it, to review and send to postItineraryImport. Nothing is created.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryImportPreview

required

Non-persisted result of an itinerary import preview: the proposed itinerary draft a user reviews before confirming. Carries the proposed segments (each with its candidate modes and recommendation), the parsed waypoints, the best-effort name and activity, and any non-fatal warnings. No itinerary, segment, or waypoint is written.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

# An upload is multipart/form-data. Nothing is persisted: the
# response is a draft to review, and the segments and waypoints kept from it
# are what POST /v1/itineraries/import takes.
curl -s https://api.mountaya.com/v1/itineraries/preview \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -F "provider=gpx" \
  -F "file=@tour-du-mont-blanc.gpx" \
  -F "activity_id=a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134" \
  -F "granularity=auto"
200
Response
{
  "data": {
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "segments": [
      {
        "name": "Segment #1",
        "color": "",
        "recommendation": "directions",
        "recommendation_reason": null,
        "linestring": {
          "mode": "linestring",
          "geojson": {
            "type": "LineString",
            "coordinates": [
              [
                6.7986,
                45.8918
              ],
              [
                6.7621,
                45.8842
              ],
              [
                6.728,
                45.8215
              ]
            ]
          },
          "distance": 17600,
          "duration": 15100,
          "ascent": 1080,
          "descent": 720,
          "altitude_min": 942,
          "altitude_max": 1653
        },
        "directions": {
          "mode": "directions",
          "geojson": {
            "type": "GeometryCollection",
            "geometries": [
              {
                "type": "LineString",
                "coordinates": [
                  [
                    6.7986,
                    45.8918
                  ],
                  [
                    6.7621,
                    45.8842
                  ],
                  [
                    6.728,
                    45.8215
                  ]
                ]
              },
              {
                "type": "MultiPoint",
                "coordinates": [
                  [
                    6.7986,
                    45.8918
                  ],
                  [
                    6.728,
                    45.8215
                  ]
                ]
              }
            ]
          },
          "distance": 17400,
          "duration": 14760,
          "ascent": 1080,
          "descent": 720,
          "altitude_min": 942,
          "altitude_max": 1653
        }
      }
    ],
    "waypoints": [
      {
        "mode": "poi",
        "name": "Refuge du Fioux",
        "icon": "hut",
        "geojson": {
          "type": "Point",
          "coordinates": [
            6.7612,
            45.8479
          ]
        }
      }
    ],
    "warnings": []
  }
}

Confirm an itinerary import, persisting the reviewed draft

Persists a reviewed import draft atomically: the itinerary, its ordered segments and its waypoints are created together or not at all. Every segment's metrics are recomputed server-side from its defining geometry, never trusted from the client, and a segment the routing engine cannot route is a 400 naming that segment's geojson, with nothing created. Returns 409 Conflict when another itinerary in the key's organization already carries the name. The response is the created itinerary with its full segments and waypoints.

Webhook events itinerary.created, recorded by the task itinerary.import.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

The reviewed draft to persist: the itinerary's name, privacy and activity, its ordered segments and the waypoints to keep. A segment or waypoint left out is not imported.

name

string

in body

required

Display name of the new itinerary, 2 to 30 characters as sent. Leading and trailing whitespace is then trimmed, and what remains must still be at least 2 characters. Refused with a 409 when another itinerary in the organization already carries it. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.

description

string

in body

Free-text description of the itinerary, at most 100 characters as sent, leading and trailing whitespace included; that whitespace is then trimmed. Omit it, or send one that trims to nothing, to create the itinerary without one.

is_private

boolean

in body

required

Whether the itinerary is private. A private itinerary is reached only with the key of the organization that owns it, so a private personal itinerary, owned by no organization, is reached by no key. A public itinerary is readable by id, read-only, by any publishable key, as last published, and it is listed only in its own organization's listings. A share token reaches only what its link names, the itinerary or a collection holding it, and reaches it whatever this says. Public never grants editing, which takes a write role in the owning organization. Privacy is read from the draft, so a change takes effect at once rather than at the next publish.

activity_id

string (uuid)

in body

required

Identifier of the activity type for the itinerary, one getActivities lists; any other identifier is a 400.

organization_id

string (uuid)

in body

Identifier of the organization that will own the imported itinerary. It must be the key's organization; omitted, it is that organization.

segments

array of ItineraryImportConfirmSegment

in body

required

Ordered finalized segments to persist.

waypoints

array of ItineraryImportConfirmWaypoint

in body

required

The waypoints to persist, as reviewed. Sending an empty array persists no waypoints, which is not the same as omitting the field.

Response 201

The itinerary created from the confirmed draft, with its segments and waypoints. Location names it, /v1/itineraries/{itinerary_id}, and ETag carries its version.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryWithDetails

required

An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.

See the ItineraryWithDetails object.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

# The second half of the import. Send back the draft from POST
# /v1/itineraries/preview with the edits you made to it; this is the call
# that creates the itinerary.
curl -s https://api.mountaya.com/v1/itineraries/import \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tour du Mont-Blanc",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "is_private": true,
    "segments": [
      {
        "mode": "directions",
        "name": "Les Houches to Col de Voza",
        "geojson": {
          "type": "MultiPoint",
          "coordinates": [[6.7986, 45.8918], [6.7621, 45.8842]]
        }
      }
    ],
    "waypoints": []
  }'
201
Response
{
  "data": {
    "id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "is_private": false,
    "is_verified": true,
    "distance": 169800,
    "ascent": 9800,
    "count": {
      "groups": 3,
      "segments": 10,
      "waypoints": 24
    },
    "revision": 42,
    "etag": "\"d118\"",
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "status": "published",
    "published_at": "2026-06-28T16:05:00Z",
    "has_unpublished_changes": false,
    "groups": [
      {
        "id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "name": "Days 1-2",
        "color": "#2f80ed",
        "speed": 4.5,
        "revision": 2,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "segments": [
      {
        "id": "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "group_id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "name": "Day 1: Col de Voza",
        "description": "From Les Houches over the Col de Voza, down the Bon Nant valley.",
        "mode": "directions",
        "position": 0,
        "color": "#2f80ed",
        "speed": 4.5,
        "start_at": "2026-07-04T07:30:00Z",
        "distance": 17400,
        "duration": 14760,
        "ascent": 1080,
        "descent": 720,
        "altitude_min": 942,
        "altitude_max": 1653,
        "gradient_min": -18.4,
        "gradient_max": 21.7,
        "geojson": {
          "type": "GeometryCollection",
          "geometries": [
            {
              "type": "LineString",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.7621,
                  45.8842
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            },
            {
              "type": "MultiPoint",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            }
          ]
        },
        "slope_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 12.4
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": -8.1
          }
        ],
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 2.9
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": 5.6
          }
        ],
        "surface_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": "compacted-gravel"
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": "dirt"
          }
        ],
        "way_type_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "path"
          }
        ],
        "trail_difficulty_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "mountain-hiking"
          }
        ],
        "steps": [
          {
            "from_index": 0,
            "to_index": 1,
            "type": "depart",
            "name": "Route des Chavants",
            "distance": 8400,
            "duration": 7200,
            "exit_number": null
          },
          {
            "from_index": 1,
            "to_index": 2,
            "type": "goal",
            "name": "-",
            "distance": 9000,
            "duration": 7560,
            "exit_number": null
          }
        ],
        "road_access_info": [
          {
            "from_index": 1,
            "to_index": 2,
            "values": [
              "private"
            ]
          }
        ],
        "revision": 7,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "waypoints": [
      {
        "id": "e8b1d740-2a96-4c53-b7f8-15d0a3c69e42",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "mode": "poi",
        "position": 0,
        "name": "Refuge du Fioux",
        "description": "Half-board, book ahead in July.",
        "icon": "hut",
        "color": "#f2994a",
        "geojson": {
          "type": "Point",
          "coordinates": [
            6.7612,
            45.8479
          ]
        },
        "amenities": [
          "water",
          "hot-meal",
          "accommodation",
          "toilets",
          "timing-checkpoint"
        ],
        "timing": {
          "cutoff_at": "2026-08-28T21:30:00Z",
          "stop_duration": 900
        },
        "contact": {
          "website": "https://www.example.com/refuge",
          "phone": "+33 4 50 12 34 56",
          "email": "contact@example.com",
          "address": "74170 Les Contamines-Montjoie, France",
          "opening_hours": "Mid-June to mid-September, 07:00-21:00 daily.",
          "booking_url": "https://www.example.com/refuge/reserver"
        },
        "media": {
          "photos": [
            {
              "url": "https://cdn.example.com/refuge-du-fioux/terrace.jpg",
              "caption": "The terrace at sunrise."
            }
          ],
          "links": [
            {
              "label": "Access from Les Contamines",
              "url": "https://www.example.com/access/les-contamines"
            }
          ]
        },
        "properties": [
          {
            "key": "bib-check",
            "label": "Bib check",
            "value": "Mandatory, both sides",
            "format": "text"
          }
        ],
        "revision": 3,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ]
  }
}

Retrieve a single itinerary with its segments and waypoints

GET
/v1/itineraries/{itinerary_id}

Returns the full itinerary including all of its segments and waypoints. Each segment carries its geometry and computed metrics; each waypoint carries its location.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Query parameters

surface

string

in query

One of: published

Reads the published snapshot rather than the draft. published is the only accepted value: there is deliberately no draft spelling, because the param only ever narrows what the caller is served. An unrecognized value is rejected with a validation error rather than silently ignored. A read of one itinerary, or of one zone, refuses it with 403 when it is personal, owned by no organization, to the person whose it is: the published surface is what a video and an embed are made of, and a personal itinerary or zone makes neither. Every other caller reads a personal itinerary or zone as published, and since one is never published it is answered as one that does not exist.

Response 200

The itinerary with its segments, waypoints and computed totals.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryWithDetails

required

An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.

See the ItineraryWithDetails object.

Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.

# A session token naming a member is what serves your own organization's
# draft; the key alone is served the published snapshot, and so is a token
# naming nobody.
curl -s https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "is_private": false,
    "is_verified": true,
    "distance": 169800,
    "ascent": 9800,
    "count": {
      "groups": 3,
      "segments": 10,
      "waypoints": 24
    },
    "revision": 42,
    "etag": "\"d118\"",
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "status": "published",
    "published_at": "2026-06-28T16:05:00Z",
    "has_unpublished_changes": false,
    "groups": [
      {
        "id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "name": "Days 1-2",
        "color": "#2f80ed",
        "speed": 4.5,
        "revision": 2,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "segments": [
      {
        "id": "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "group_id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "name": "Day 1: Col de Voza",
        "description": "From Les Houches over the Col de Voza, down the Bon Nant valley.",
        "mode": "directions",
        "position": 0,
        "color": "#2f80ed",
        "speed": 4.5,
        "start_at": "2026-07-04T07:30:00Z",
        "distance": 17400,
        "duration": 14760,
        "ascent": 1080,
        "descent": 720,
        "altitude_min": 942,
        "altitude_max": 1653,
        "gradient_min": -18.4,
        "gradient_max": 21.7,
        "geojson": {
          "type": "GeometryCollection",
          "geometries": [
            {
              "type": "LineString",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.7621,
                  45.8842
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            },
            {
              "type": "MultiPoint",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            }
          ]
        },
        "slope_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 12.4
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": -8.1
          }
        ],
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 2.9
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": 5.6
          }
        ],
        "surface_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": "compacted-gravel"
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": "dirt"
          }
        ],
        "way_type_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "path"
          }
        ],
        "trail_difficulty_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "mountain-hiking"
          }
        ],
        "steps": [
          {
            "from_index": 0,
            "to_index": 1,
            "type": "depart",
            "name": "Route des Chavants",
            "distance": 8400,
            "duration": 7200,
            "exit_number": null
          },
          {
            "from_index": 1,
            "to_index": 2,
            "type": "goal",
            "name": "-",
            "distance": 9000,
            "duration": 7560,
            "exit_number": null
          }
        ],
        "road_access_info": [
          {
            "from_index": 1,
            "to_index": 2,
            "values": [
              "private"
            ]
          }
        ],
        "revision": 7,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "waypoints": [
      {
        "id": "e8b1d740-2a96-4c53-b7f8-15d0a3c69e42",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "mode": "poi",
        "position": 0,
        "name": "Refuge du Fioux",
        "description": "Half-board, book ahead in July.",
        "icon": "hut",
        "color": "#f2994a",
        "geojson": {
          "type": "Point",
          "coordinates": [
            6.7612,
            45.8479
          ]
        },
        "amenities": [
          "water",
          "hot-meal",
          "accommodation",
          "toilets",
          "timing-checkpoint"
        ],
        "timing": {
          "cutoff_at": "2026-08-28T21:30:00Z",
          "stop_duration": 900
        },
        "contact": {
          "website": "https://www.example.com/refuge",
          "phone": "+33 4 50 12 34 56",
          "email": "contact@example.com",
          "address": "74170 Les Contamines-Montjoie, France",
          "opening_hours": "Mid-June to mid-September, 07:00-21:00 daily.",
          "booking_url": "https://www.example.com/refuge/reserver"
        },
        "media": {
          "photos": [
            {
              "url": "https://cdn.example.com/refuge-du-fioux/terrace.jpg",
              "caption": "The terrace at sunrise."
            }
          ],
          "links": [
            {
              "label": "Access from Les Contamines",
              "url": "https://www.example.com/access/les-contamines"
            }
          ]
        },
        "properties": [
          {
            "key": "bib-check",
            "label": "Bib check",
            "value": "Mandatory, both sides",
            "format": "text"
          }
        ],
        "revision": 3,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ]
  }
}

Update an existing itinerary

Updates the itinerary's name, description and privacy. Every field is optional and an omitted field keeps its current value; send null to clear the description. Returns 409 Conflict when another itinerary in the organization already carries the requested name. The response is the itinerary's full draft: description, distance and ascent are null when it has none.

Webhook events itinerary.updated, recorded by the task itinerary.update.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Body

The itinerary fields to change. Every field is optional; omitted fields are left as they are.

description

string | null

in body

Free-text description of the itinerary, at most 100 characters as sent, leading and trailing whitespace included; that whitespace is then trimmed. Omit to keep the current value; null, or a value that trims to nothing, clears it.

is_private

boolean

in body

Whether the itinerary is private. A private itinerary is reached only with the key of the organization that owns it, so a private personal itinerary, owned by no organization, is reached by no key. A public itinerary is readable by id, read-only, by any publishable key, as last published, and it is listed only in its own organization's listings. A share token reaches only what its link names, the itinerary or a collection holding it, and reaches it whatever this says. Public never grants editing, which takes a write role in the owning organization. Privacy is read from the draft, so a change takes effect at once rather than at the next publish. Omit to keep the current value.

name

string

in body

Display name of the itinerary, 2 to 30 characters as sent. Leading and trailing whitespace is then trimmed, and what remains must still be at least 2 characters. Omit to keep the current value. Refused with a 409 when another itinerary in the organization already carries it, names compared exactly after trimming, case included; sending its current name again is not a conflict. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.

Response 200

The itinerary after the change, with a new revision.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryWithDetails

required

An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.

See the ItineraryWithDetails object.

Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.

# Every field is optional; an omitted field keeps its current value.
curl -s -X PATCH https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{"name": "Tour du Mont-Blanc", "is_private": false}'
200
Response
{
  "data": {
    "id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "is_private": false,
    "is_verified": true,
    "distance": 169800,
    "ascent": 9800,
    "count": {
      "groups": 3,
      "segments": 10,
      "waypoints": 24
    },
    "revision": 42,
    "etag": "\"d118\"",
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "status": "published",
    "published_at": "2026-06-28T16:05:00Z",
    "has_unpublished_changes": false,
    "groups": [
      {
        "id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "name": "Days 1-2",
        "color": "#2f80ed",
        "speed": 4.5,
        "revision": 2,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "segments": [
      {
        "id": "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "group_id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "name": "Day 1: Col de Voza",
        "description": "From Les Houches over the Col de Voza, down the Bon Nant valley.",
        "mode": "directions",
        "position": 0,
        "color": "#2f80ed",
        "speed": 4.5,
        "start_at": "2026-07-04T07:30:00Z",
        "distance": 17400,
        "duration": 14760,
        "ascent": 1080,
        "descent": 720,
        "altitude_min": 942,
        "altitude_max": 1653,
        "gradient_min": -18.4,
        "gradient_max": 21.7,
        "geojson": {
          "type": "GeometryCollection",
          "geometries": [
            {
              "type": "LineString",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.7621,
                  45.8842
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            },
            {
              "type": "MultiPoint",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            }
          ]
        },
        "slope_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 12.4
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": -8.1
          }
        ],
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 2.9
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": 5.6
          }
        ],
        "surface_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": "compacted-gravel"
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": "dirt"
          }
        ],
        "way_type_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "path"
          }
        ],
        "trail_difficulty_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "mountain-hiking"
          }
        ],
        "steps": [
          {
            "from_index": 0,
            "to_index": 1,
            "type": "depart",
            "name": "Route des Chavants",
            "distance": 8400,
            "duration": 7200,
            "exit_number": null
          },
          {
            "from_index": 1,
            "to_index": 2,
            "type": "goal",
            "name": "-",
            "distance": 9000,
            "duration": 7560,
            "exit_number": null
          }
        ],
        "road_access_info": [
          {
            "from_index": 1,
            "to_index": 2,
            "values": [
              "private"
            ]
          }
        ],
        "revision": 7,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "waypoints": [
      {
        "id": "e8b1d740-2a96-4c53-b7f8-15d0a3c69e42",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "mode": "poi",
        "position": 0,
        "name": "Refuge du Fioux",
        "description": "Half-board, book ahead in July.",
        "icon": "hut",
        "color": "#f2994a",
        "geojson": {
          "type": "Point",
          "coordinates": [
            6.7612,
            45.8479
          ]
        },
        "amenities": [
          "water",
          "hot-meal",
          "accommodation",
          "toilets",
          "timing-checkpoint"
        ],
        "timing": {
          "cutoff_at": "2026-08-28T21:30:00Z",
          "stop_duration": 900
        },
        "contact": {
          "website": "https://www.example.com/refuge",
          "phone": "+33 4 50 12 34 56",
          "email": "contact@example.com",
          "address": "74170 Les Contamines-Montjoie, France",
          "opening_hours": "Mid-June to mid-September, 07:00-21:00 daily.",
          "booking_url": "https://www.example.com/refuge/reserver"
        },
        "media": {
          "photos": [
            {
              "url": "https://cdn.example.com/refuge-du-fioux/terrace.jpg",
              "caption": "The terrace at sunrise."
            }
          ],
          "links": [
            {
              "label": "Access from Les Contamines",
              "url": "https://www.example.com/access/les-contamines"
            }
          ]
        },
        "properties": [
          {
            "key": "bib-check",
            "label": "Bib check",
            "value": "Mandatory, both sides",
            "format": "text"
          }
        ],
        "revision": 3,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ]
  }
}

Delete an itinerary

Permanently deletes the itinerary and all of its segments and waypoints. This action cannot be undone.

Webhook events itinerary.deleted, collection.itinerary.removed, recorded by the task itinerary.delete.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Response 200

The itinerary is deleted, along with its segments and waypoints. data is null.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.

# Deletes the itinerary and everything under it. Publishing does not protect it: take
# the publication down first if a live link must stop working in a known order.
curl -s -X DELETE https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": null
}

Duplicate an itinerary into the key's organization

POST
/v1/itineraries/{itinerary_id}/duplicate

Copies the selected segments and waypoints of an existing itinerary into a new one in the key's organization, which is also what an omitted organization_id means. Reading the source needs only view access (matching the "anyone with the link" model), so another organization's public itinerary can be copied, as it was last published; writing the copy needs a write role in the key's organization. Returns 409 Conflict when another itinerary in that organization already carries the requested name.

Webhook events itinerary.created, recorded by the task itinerary.duplicate.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Query parameters

surface

string

in query

One of: published

Copies from the published snapshot where the credential would otherwise copy the draft. Without it the source is read as getItinerary serves it: a key with a session token reads its own organization's draft, while a key alone, and any key reading another organization's itinerary, reads the last publication. published is the only accepted value: there is deliberately no draft spelling, because the param only ever narrows what the caller is served. An unrecognized value is rejected with a validation error rather than silently ignored.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

What to copy into the new itinerary. To copy the itinerary whole, send only name: an omitted segment_ids copies every segment and an omitted waypoint_ids every waypoint, however many the source holds. For a partial copy, segment_ids names a contiguous run of at least one segment, at most 1,000, and waypoint_ids names at most 5,000 waypoints, an empty list copying none.

name

string

in body

required

Display name of the new itinerary, 2 to 30 characters as sent. Leading and trailing whitespace is then trimmed, and what remains must still be at least 2 characters. Refused with a 409 when another itinerary in the organization already carries it. A name is one line: a tab, a line break or a line separator between two of its characters is a 400, and one at either end is trimmed with the whitespace there.

organization_id

string (uuid)

in body

Identifier of the organization that will own the copy. It must be the key's organization; omitted, it is that organization, whichever organization the source itinerary belongs to.

segment_ids

array of string (uuid)

in body

Identifiers of the source segments to copy, for a partial copy. Optional and not nullable: omit it to copy every segment of the source's chain, however many it holds, read from the source as the surface parameter describes, so a whole copy of a published snapshot never names ids that change at every publish.

waypoint_ids

array of string (uuid)

in body

Identifiers of the source waypoints to copy, for a partial copy. Waypoints are standalone markers, so any subset is valid, and an empty list copies none. Optional and not nullable: omit it to copy every waypoint of the source as read, however many it holds. At most 5,000, the ceiling the import confirm puts on the waypoints of one request. As with segment_ids, an id that is not a waypoint of the source as read is a 400 naming its position in the array, and a repeated identifier is a 400 naming the repeat, as it is for segment_ids.

Response 201

The new itinerary, with fresh ids throughout and its own revision. The original is untouched. Location names the copy, /v1/itineraries/{itinerary_id}, and ETag carries its version.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryWithDetails

required

An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.

See the ItineraryWithDetails object.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

# The chosen segments must be a contiguous run. Add ?surface=published to copy what
# the public sees rather than the draft.
curl -s -X POST https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/duplicate \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TMB: first three stages",
    "segment_ids": [
      "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
      "7e1c5a92-4b60-4d38-a7f2-0c9e6b3d854a",
      "15a9d3c7-8e02-4b6f-9d41-6f7a2c8e0b53"
    ],
    "waypoint_ids": [
      "6c0a9e37-2d58-4b16-9f4e-8a1d3c705b92"
    ]
  }'
201
Response
{
  "data": {
    "id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "is_private": false,
    "is_verified": true,
    "distance": 169800,
    "ascent": 9800,
    "count": {
      "groups": 3,
      "segments": 10,
      "waypoints": 24
    },
    "revision": 42,
    "etag": "\"d118\"",
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "status": "published",
    "published_at": "2026-06-28T16:05:00Z",
    "has_unpublished_changes": false,
    "groups": [
      {
        "id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "name": "Days 1-2",
        "color": "#2f80ed",
        "speed": 4.5,
        "revision": 2,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "segments": [
      {
        "id": "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "group_id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "name": "Day 1: Col de Voza",
        "description": "From Les Houches over the Col de Voza, down the Bon Nant valley.",
        "mode": "directions",
        "position": 0,
        "color": "#2f80ed",
        "speed": 4.5,
        "start_at": "2026-07-04T07:30:00Z",
        "distance": 17400,
        "duration": 14760,
        "ascent": 1080,
        "descent": 720,
        "altitude_min": 942,
        "altitude_max": 1653,
        "gradient_min": -18.4,
        "gradient_max": 21.7,
        "geojson": {
          "type": "GeometryCollection",
          "geometries": [
            {
              "type": "LineString",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.7621,
                  45.8842
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            },
            {
              "type": "MultiPoint",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            }
          ]
        },
        "slope_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 12.4
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": -8.1
          }
        ],
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 2.9
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": 5.6
          }
        ],
        "surface_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": "compacted-gravel"
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": "dirt"
          }
        ],
        "way_type_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "path"
          }
        ],
        "trail_difficulty_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "mountain-hiking"
          }
        ],
        "steps": [
          {
            "from_index": 0,
            "to_index": 1,
            "type": "depart",
            "name": "Route des Chavants",
            "distance": 8400,
            "duration": 7200,
            "exit_number": null
          },
          {
            "from_index": 1,
            "to_index": 2,
            "type": "goal",
            "name": "-",
            "distance": 9000,
            "duration": 7560,
            "exit_number": null
          }
        ],
        "road_access_info": [
          {
            "from_index": 1,
            "to_index": 2,
            "values": [
              "private"
            ]
          }
        ],
        "revision": 7,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "waypoints": [
      {
        "id": "e8b1d740-2a96-4c53-b7f8-15d0a3c69e42",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "mode": "poi",
        "position": 0,
        "name": "Refuge du Fioux",
        "description": "Half-board, book ahead in July.",
        "icon": "hut",
        "color": "#f2994a",
        "geojson": {
          "type": "Point",
          "coordinates": [
            6.7612,
            45.8479
          ]
        },
        "amenities": [
          "water",
          "hot-meal",
          "accommodation",
          "toilets",
          "timing-checkpoint"
        ],
        "timing": {
          "cutoff_at": "2026-08-28T21:30:00Z",
          "stop_duration": 900
        },
        "contact": {
          "website": "https://www.example.com/refuge",
          "phone": "+33 4 50 12 34 56",
          "email": "contact@example.com",
          "address": "74170 Les Contamines-Montjoie, France",
          "opening_hours": "Mid-June to mid-September, 07:00-21:00 daily.",
          "booking_url": "https://www.example.com/refuge/reserver"
        },
        "media": {
          "photos": [
            {
              "url": "https://cdn.example.com/refuge-du-fioux/terrace.jpg",
              "caption": "The terrace at sunrise."
            }
          ],
          "links": [
            {
              "label": "Access from Les Contamines",
              "url": "https://www.example.com/access/les-contamines"
            }
          ]
        },
        "properties": [
          {
            "key": "bib-check",
            "label": "Bib check",
            "value": "Mandatory, both sides",
            "format": "text"
          }
        ],
        "revision": 3,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ]
  }
}

Publish the itinerary's current draft

POST
/v1/itineraries/{itinerary_id}/publication

Sets the itinerary's publication to its current draft: the draft's content is frozen into a publication and becomes what the public surfaces serve. Until the first publish, share links and embeds resolve nothing for the itinerary; after it, they serve that snapshot and are unaffected by any further draft edit until the itinerary is published again. The studio always reads and writes the draft, whatever is published.

Webhook events itinerary.published, recorded by the task itinerary.publish.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Response 200

The itinerary as published, with status published and published_at set, and its new ETag.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryWithDetails

required

An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.

See the ItineraryWithDetails object.

Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.

# No body. The answer is the itinerary with published_at and
# has_unpublished_changes reflecting the new publication.
curl -s -X POST https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/publication \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" | jq '.data.published_at'
200
Response
{
  "data": {
    "id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "is_private": false,
    "is_verified": true,
    "distance": 169800,
    "ascent": 9800,
    "count": {
      "groups": 3,
      "segments": 10,
      "waypoints": 24
    },
    "revision": 42,
    "etag": "\"d118\"",
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "status": "published",
    "published_at": "2026-06-28T16:05:00Z",
    "has_unpublished_changes": false,
    "groups": [
      {
        "id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "name": "Days 1-2",
        "color": "#2f80ed",
        "speed": 4.5,
        "revision": 2,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "segments": [
      {
        "id": "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "group_id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "name": "Day 1: Col de Voza",
        "description": "From Les Houches over the Col de Voza, down the Bon Nant valley.",
        "mode": "directions",
        "position": 0,
        "color": "#2f80ed",
        "speed": 4.5,
        "start_at": "2026-07-04T07:30:00Z",
        "distance": 17400,
        "duration": 14760,
        "ascent": 1080,
        "descent": 720,
        "altitude_min": 942,
        "altitude_max": 1653,
        "gradient_min": -18.4,
        "gradient_max": 21.7,
        "geojson": {
          "type": "GeometryCollection",
          "geometries": [
            {
              "type": "LineString",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.7621,
                  45.8842
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            },
            {
              "type": "MultiPoint",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            }
          ]
        },
        "slope_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 12.4
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": -8.1
          }
        ],
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 2.9
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": 5.6
          }
        ],
        "surface_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": "compacted-gravel"
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": "dirt"
          }
        ],
        "way_type_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "path"
          }
        ],
        "trail_difficulty_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "mountain-hiking"
          }
        ],
        "steps": [
          {
            "from_index": 0,
            "to_index": 1,
            "type": "depart",
            "name": "Route des Chavants",
            "distance": 8400,
            "duration": 7200,
            "exit_number": null
          },
          {
            "from_index": 1,
            "to_index": 2,
            "type": "goal",
            "name": "-",
            "distance": 9000,
            "duration": 7560,
            "exit_number": null
          }
        ],
        "road_access_info": [
          {
            "from_index": 1,
            "to_index": 2,
            "values": [
              "private"
            ]
          }
        ],
        "revision": 7,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "waypoints": [
      {
        "id": "e8b1d740-2a96-4c53-b7f8-15d0a3c69e42",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "mode": "poi",
        "position": 0,
        "name": "Refuge du Fioux",
        "description": "Half-board, book ahead in July.",
        "icon": "hut",
        "color": "#f2994a",
        "geojson": {
          "type": "Point",
          "coordinates": [
            6.7612,
            45.8479
          ]
        },
        "amenities": [
          "water",
          "hot-meal",
          "accommodation",
          "toilets",
          "timing-checkpoint"
        ],
        "timing": {
          "cutoff_at": "2026-08-28T21:30:00Z",
          "stop_duration": 900
        },
        "contact": {
          "website": "https://www.example.com/refuge",
          "phone": "+33 4 50 12 34 56",
          "email": "contact@example.com",
          "address": "74170 Les Contamines-Montjoie, France",
          "opening_hours": "Mid-June to mid-September, 07:00-21:00 daily.",
          "booking_url": "https://www.example.com/refuge/reserver"
        },
        "media": {
          "photos": [
            {
              "url": "https://cdn.example.com/refuge-du-fioux/terrace.jpg",
              "caption": "The terrace at sunrise."
            }
          ],
          "links": [
            {
              "label": "Access from Les Contamines",
              "url": "https://www.example.com/access/les-contamines"
            }
          ]
        },
        "properties": [
          {
            "key": "bib-check",
            "label": "Bib check",
            "value": "Mandatory, both sides",
            "format": "text"
          }
        ],
        "revision": 3,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ]
  }
}

Take the itinerary's publication down

DELETE
/v1/itineraries/{itinerary_id}/publication

Takes the itinerary off the public surfaces. Mountaya stops serving it from the next request: share links and embeds stop resolving it, and Mountaya's own caches stop serving its published tiles: they are not evicted, but nothing reaches them and they age out. An answer a shared cache between a reader and Mountaya already holds is served from there until its lifetime runs out, which taking the itinerary down does not shorten: at most 6 minutes for a published read of the itinerary or its pace (max-age=300 and stale-while-revalidate=60), and 5 for a public tile of it (max-age=300).

Webhook events itinerary.unpublished, recorded by the task itinerary.unpublish.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Response 200

The itinerary unpublished, with status draft and published_at null, and its ETag. An itinerary that was not published is answered the same way.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryWithDetails

required

An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.

See the ItineraryWithDetails object.

Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.

# Withdraws the live publication. Share links and embeds resolve nothing again;
# the draft is untouched, and the itinerary stops counting toward the
# organization's published-itineraries limit.
curl -s -X DELETE https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/publication \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data.status'
200
Response
{
  "data": {
    "id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
    "name": "Tour du Mont-Blanc",
    "description": "Ten stages from Les Houches, anticlockwise.",
    "is_private": false,
    "is_verified": true,
    "distance": 169800,
    "ascent": 9800,
    "count": {
      "groups": 3,
      "segments": 10,
      "waypoints": 24
    },
    "revision": 42,
    "etag": "\"d118\"",
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "status": "published",
    "published_at": "2026-06-28T16:05:00Z",
    "has_unpublished_changes": false,
    "groups": [
      {
        "id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "name": "Days 1-2",
        "color": "#2f80ed",
        "speed": 4.5,
        "revision": 2,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "segments": [
      {
        "id": "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "group_id": "5c6e2a71-3f84-4b9d-90e5-8a1c7b4f6d23",
        "name": "Day 1: Col de Voza",
        "description": "From Les Houches over the Col de Voza, down the Bon Nant valley.",
        "mode": "directions",
        "position": 0,
        "color": "#2f80ed",
        "speed": 4.5,
        "start_at": "2026-07-04T07:30:00Z",
        "distance": 17400,
        "duration": 14760,
        "ascent": 1080,
        "descent": 720,
        "altitude_min": 942,
        "altitude_max": 1653,
        "gradient_min": -18.4,
        "gradient_max": 21.7,
        "geojson": {
          "type": "GeometryCollection",
          "geometries": [
            {
              "type": "LineString",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.7621,
                  45.8842
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            },
            {
              "type": "MultiPoint",
              "coordinates": [
                [
                  6.7986,
                  45.8918
                ],
                [
                  6.728,
                  45.8215
                ]
              ]
            }
          ]
        },
        "slope_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 12.4
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": -8.1
          }
        ],
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 2.9
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": 5.6
          }
        ],
        "surface_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": "compacted-gravel"
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": "dirt"
          }
        ],
        "way_type_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "path"
          }
        ],
        "trail_difficulty_info": [
          {
            "from_index": 0,
            "to_index": 2,
            "value": "mountain-hiking"
          }
        ],
        "steps": [
          {
            "from_index": 0,
            "to_index": 1,
            "type": "depart",
            "name": "Route des Chavants",
            "distance": 8400,
            "duration": 7200,
            "exit_number": null
          },
          {
            "from_index": 1,
            "to_index": 2,
            "type": "goal",
            "name": "-",
            "distance": 9000,
            "duration": 7560,
            "exit_number": null
          }
        ],
        "road_access_info": [
          {
            "from_index": 1,
            "to_index": 2,
            "values": [
              "private"
            ]
          }
        ],
        "revision": 7,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ],
    "waypoints": [
      {
        "id": "e8b1d740-2a96-4c53-b7f8-15d0a3c69e42",
        "itinerary_id": "9c2a7f60-1d4b-4e83-a5c7-6f0b8e91d245",
        "mode": "poi",
        "position": 0,
        "name": "Refuge du Fioux",
        "description": "Half-board, book ahead in July.",
        "icon": "hut",
        "color": "#f2994a",
        "geojson": {
          "type": "Point",
          "coordinates": [
            6.7612,
            45.8479
          ]
        },
        "amenities": [
          "water",
          "hot-meal",
          "accommodation",
          "toilets",
          "timing-checkpoint"
        ],
        "timing": {
          "cutoff_at": "2026-08-28T21:30:00Z",
          "stop_duration": 900
        },
        "contact": {
          "website": "https://www.example.com/refuge",
          "phone": "+33 4 50 12 34 56",
          "email": "contact@example.com",
          "address": "74170 Les Contamines-Montjoie, France",
          "opening_hours": "Mid-June to mid-September, 07:00-21:00 daily.",
          "booking_url": "https://www.example.com/refuge/reserver"
        },
        "media": {
          "photos": [
            {
              "url": "https://cdn.example.com/refuge-du-fioux/terrace.jpg",
              "caption": "The terrace at sunrise."
            }
          ],
          "links": [
            {
              "label": "Access from Les Contamines",
              "url": "https://www.example.com/access/les-contamines"
            }
          ]
        },
        "properties": [
          {
            "key": "bib-check",
            "label": "Bib check",
            "value": "Mandatory, both sides",
            "format": "text"
          }
        ],
        "revision": 3,
        "created_by": {
          "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
        },
        "created_at": "2026-05-12T09:14:00Z"
      }
    ]
  }
}

Export an itinerary as a downloadable file

GET
/v1/itineraries/{itinerary_id}/export

Exports the itinerary in the requested format. The optional segment_id query parameter limits the export to a single segment within the itinerary. Every format carries track point elevation when the geometry holds it. GPX emits a single track with one segment per itinerary segment; GeoJSON returns a FeatureCollection; KML and KMZ carry per-segment styling; FIT and TCX are time-series formats whose file type the optional variant query parameter selects; CSV is a flat coordinate table and is lossy. The format query parameter is required.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Query parameters

format

string

in query

required

One of: gpx, geojson, kml, kmz, fit, tcx, csv

File format to render. Required: there is no default, because a download whose format the caller did not choose is never the right guess. One of gpx, geojson, kml, kmz, fit, tcx, or csv; the schema below describes what each one carries. The value also decides the response Content-Type and the extension in Content-Disposition, so it is the single input that determines what the browser saves.

variant

string

in query

One of: course, activity

File type of a time-series export, applicable to the fit and tcx formats only and defaulting to course when omitted. Supplying it for any other format is rejected.

segment_id

string (uuid)

in query

Narrows the export to one segment of the itinerary. Omit it to export the whole itinerary. A single-segment export carries that segment's geometry alone and no waypoints, since a waypoint belongs to the itinerary rather than to any one segment, and the download is named <itinerary name> - <segment name>. An id that names no segment of this itinerary answers 404, the same as an unknown itinerary, so the response never confirms that a segment exists elsewhere.

surface

string

in query

One of: published

Reads the published snapshot rather than the draft. published is the only accepted value: there is deliberately no draft spelling, because the param only ever narrows what the caller is served. An unrecognized value is rejected with a validation error rather than silently ignored. A read of one itinerary, or of one zone, refuses it with 403 when it is personal, owned by no organization, to the person whose it is: the published surface is what a video and an embed are made of, and a personal itinerary or zone makes neither. Every other caller reads a personal itinerary or zone as published, and since one is never published it is answered as one that does not exist.

Response 200 application/gpx+xml, application/geo+json, application/vnd.google-earth.kml+xml, application/vnd.google-earth.kmz, application/vnd.ant.fit, application/vnd.garmin.tcx+xml, text/csv

The rendered file, not an envelope. Its Content-Type is determined by the format query parameter: gpx → application/gpx+xml, geojson → application/geo+json, kml → application/vnd.google-earth.kml+xml, kmz → application/vnd.google-earth.kmz, fit → application/vnd.ant.fit, tcx → application/vnd.garmin.tcx+xml, csv → text/csv. In a CSV, a name beginning with =, +, -, @, a tab or a carriage return, or with the full-width =, +, - or @, is prefixed with a single quote ('), as the second waypoint of the example is, so a spreadsheet reads it as text rather than as a formula.

Errors 400, 401, 402, 403, 404, 413, 429, 500, 504. See Errors.

# The body is the file itself, not an envelope. -OJ keeps the filename the
# Content-Disposition header names.
curl -s -OJ \
  "https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/export?format=gpx" \
  -H "X-API-Key: pk_your_publishable_key"

Re-time an itinerary at a travel pace the caller names

GET
/v1/itineraries/{itinerary_id}/pace

Answers how long the itinerary takes at the flat pace the speed query parameter names, for the caller asking and for nobody else. The itinerary's stored speeds are not touched, no revision is written, and the next reader without a pace of their own is served the author's figures. This is what lets an embedded visitor read a route at their own rate: a fast walker and a slow one are looking at the same published itinerary.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Query parameters

speed

number (double)

in query

required

Travel speed in km/h on LEVEL ground: the flat pace the travel-time model starts from, the same quantity ItinerarySegment.speed carries and never the resolved per-stretch speed speed_info reports. Required: there is no default, because the itinerary already has one and a caller who did not name a pace should read that instead.

surface

string

in query

One of: published

Reads the published snapshot rather than the draft. published is the only accepted value: there is deliberately no draft spelling, because the param only ever narrows what the caller is served. An unrecognized value is rejected with a validation error rather than silently ignored. A read of one itinerary, or of one zone, refuses it with 403 when it is personal, owned by no organization, to the person whose it is: the published surface is what a video and an embed are made of, and a personal itinerary or zone makes neither. Every other caller reads a personal itinerary or zone as published, and since one is never published it is answered as one that does not exist.

Response 200

The itinerary's total duration at the requested pace, and the duration and resolved speeds of every segment that made it up.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ItineraryPace

required

An itinerary re-timed at one flat pace: the total, and every segment that made it up. Nothing here is stored. The itinerary's committed speeds are untouched and the next reader without a pace of their own is served the author's figures.

Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.

# `speed` is km/h on LEVEL ground, the flat pace the model starts from,
# never a speed actually travelled anywhere on the line.
curl -s "https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/pace?speed=4.5" \
  -H "X-API-Key: pk_your_publishable_key" | jq '.data.duration'
200
Response
{
  "data": {
    "duration": 23040,
    "segments": [
      {
        "duration": 11520,
        "id": "2b8d4f19-6a05-4e73-8c1f-9d3b7e05a24c",
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 3.7
          },
          {
            "from_index": 1,
            "to_index": 2,
            "value": 7.2
          }
        ]
      },
      {
        "duration": 11520,
        "id": "6a05f19b-2b8d-4e73-8c1f-05a24c9d3b7e",
        "speed_info": [
          {
            "from_index": 0,
            "to_index": 1,
            "value": 4.1
          }
        ]
      }
    ]
  }
}
GET
/v1/itineraries/{itinerary_id}/share-link

Returns the itinerary's share link, its token and when it was minted, or data: null when the itinerary has none: none was ever minted, or the last one was removed. An itinerary has at most one link at a time. postItineraryShareLink mints one, postItineraryShareLinkRotate replaces its token and deleteItineraryShareLink removes it.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Response 200

The itinerary's share link, or data: null when it has none. An itinerary without a link is not a 404: the itinerary exists, and it has no link.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ShareLink | null

required

Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.

# `data` is null when the itinerary has no link.
curl -s https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/share-link \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "share_token": "share_4f9c2a7e15b83d06e4a91c7fb250d83a",
    "created_at": "2026-09-14T10:22:05Z"
  }
}
POST
/v1/itineraries/{itinerary_id}/share-link

Sets the itinerary's share link: mints one when the itinerary has none, answering 201 with Location naming the link, and returns the existing one otherwise, answering 200 with the same token as before. Calling it again never mints a second link and never changes the token, so it is safe to repeat; postItineraryShareLinkRotate is what replaces a token. Both private and public itineraries can be shared.

Webhook events itinerary.share_link.created, recorded by the task itinerary.share_link.create.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Response 200

The itinerary already had a share link, and this is it, token unchanged. Nothing was minted.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ShareLink

required

The share link of one itinerary or one collection: the token that opens it and when it was minted. A resource has at most one link at a time.

See the ShareLink object.

Errors 400, 401, 402, 403, 404, 409, 429, 500, 504. See Errors.

# No body. Calling it again returns the same token rather than a second one:
# 201 the first time, 200 after.
curl -s -X POST https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/share-link \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq -r '.data.share_token'
200
Response
{
  "data": {
    "share_token": "share_4f9c2a7e15b83d06e4a91c7fb250d83a",
    "created_at": "2026-09-14T10:22:05Z"
  }
}
DELETE
/v1/itineraries/{itinerary_id}/share-link

Removes the itinerary's share link, so every URL built from its token stops resolving. Mountaya refuses the old token from the next request on, with a 401. An answer a shared cache already holds for a request carrying it is served from there until its lifetime runs out: at most 5 minutes for a public tile and 25 hours for the layer catalog, as each states in its Cache-Control. It takes the same write role the mint takes. There is no undo: minting again produces a new token, not the old one.

Webhook events itinerary.share_link.deleted, recorded by the task itinerary.share_link.delete.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Response 200

The itinerary has no share link: a request carrying the old token gets a 401 from the next request on, but for an answer a shared cache already holds. An itinerary that had none is answered the same way. data is null.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 402, 403, 404, 409, 429, 500, 504. See Errors.

# Breaks every URL already handed out. There is no undo: minting again produces a
# new token, not the old one.
curl -s -X DELETE https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/share-link \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": null
}

Rotate the itinerary's share link

POST
/v1/itineraries/{itinerary_id}/share-link/rotate

Replaces the token of the itinerary's share link with a freshly generated one and returns it, so every URL built from the previous token stops resolving: the cut-off for a link that has spread too far or outlived its intended audience, without a window where no link works. It takes the same write role the mint takes. Refused with 409 when the itinerary has no share link to rotate: mint one with postItineraryShareLink.

Webhook events itinerary.share_link.rotated, recorded by the task itinerary.share_link.rotate.

Path parameters

itinerary_id

string (uuid)

in path

required

Identifier of the itinerary the operation acts on. An itinerary this credential does not reach is a 404 rather than a 403, and so is one that does not exist, so the parameter cannot be used to learn which itinerary ids exist.

Headers

Idempotency-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Response 200

The share link with its new token and created_at. The previous token is refused from the next request on, but for an answer a shared cache already holds for it, which is served until its lifetime runs out: at most 5 minutes for a public tile and 25 hours for the layer catalog.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ShareLink

required

The share link of one itinerary or one collection: the token that opens it and when it was minted. A resource has at most one link at a time.

See the ShareLink object.

Errors 400, 401, 402, 403, 404, 409, 429, 500, 504. See Errors.

# Rotating breaks every URL already handed out and returns a new token in the same
# call. Keep the Idempotency-Key for a retry: it is answered with this rotation's
# token rather than rotating again.
curl -s -X POST https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/share-link/rotate \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)"
200
Response
{
  "data": {
    "share_token": "share_4f9c2a7e15b83d06e4a91c7fb250d83a",
    "created_at": "2026-09-14T10:22:05Z"
  }
}