Get started
Itineraries

Waypoints

Waypoints

The named places along a route: a hut, a summit, a water point, a cut-off time. Waypoints are ordered against the route rather than positioned independently, so one that moves keeps its place in the sequence.

Create a new waypoint within an itinerary

POST
/v1/itineraries/{itinerary_id}/waypoints

Creates a new waypoint within the specified itinerary. Its position is stored as the request gives it: a waypoint's order is the author's choice rather than something the route derives.

Webhook events itinerary.waypoint.created, recorded by the task itinerary.waypoint.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.

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 new waypoint: its location, its mode, and the presentation and contact detail carried with it.

amenities

array of string

in body

Services and facilities available at this waypoint. Duplicates are rejected. Optional and not nullable: omit it for none.

color

string

in body

Hex color code for rendering this waypoint on the map. Both the three-digit and the six-digit forms are accepted, in either case, and either is stored as six lowercase digits (#F60 and #FF6600 both as #ff6600), which is the form every read returns.

contact

object

in body

How to reach the place this waypoint marks. An object whose members are all null or absent is stored as none, and reads back as null.

description

string

in body

Free-text description of the waypoint, 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 waypoint without one.

geojson

GeoJSONPoint | GeoJSONMultiPoint | GeoJSONLineString | GeoJSONMultiLineString | GeoJSONPolygon | GeoJSONMultiPolygon | GeoJSONGeometryCollection

in body

required

A bare GeoJSON Point representing the waypoint location, the shape a waypoint's geojson is read in. Any other geometry, a GeometryCollection holding a Point included, is a 400 naming geojson. Both modes require it, so omitting it is a 400. A position outside the longitude and latitude ranges, or one of more than three numbers, is a 400 naming the position at fault, for example geojson[0].

icon

string

in body

One of: circle-warning, megaphone, bed, apartment-building, camper-van, circle-check, parking-sign, medical-cross, droplet, eye, flag, flag-start, flag-end, hut, circle-info, map-pin, camping, trophy, cutlery, bus, train, cable-car, charging-station, gate, toilet, shower, trash, shop, picnic, helicopter, signal, climbing, ladder

Icon displayed on the waypoint. Required for a poi, which sent without one is a 400 naming icon; optional for a point, which shows it when set. flag-start and flag-end are refused on every write (400). Not nullable: omit it for a point without one.

media

object

in body

Photos and external links attached to this waypoint. An object whose members are all null, absent or empty lists is stored as none, and reads back as null.

mode

string

in body

required

One of: poi, point

Whether the waypoint is a point of interest, which carries a name and an icon, or a standalone point marker, which may be unnamed.

name

string

in body

Display name of the waypoint, 2 to 30 characters as sent. Leading and trailing whitespace is then trimmed, and what remains must still be at least 2 characters. Required when mode is poi; a point may omit it. A poi sent without one is a 400 naming name. 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.

position

integer (int32)

in body

required

Zero-based position of the waypoint within its parent itinerary, stored as given: a waypoint's order is the author's choice, and no other waypoint moves to make room. Between 0 and 9999.

properties

array of WaypointProperty

in body

Customer-defined fields for this waypoint, in the order they should be shown. Keys must be unique within the waypoint. At most 20: the server enforces the ceiling, and a list over it is a validation error rather than a truncation.

timing

object

in body

Cut-off and expected-arrival timing for this waypoint. An object whose members are all null or absent is stored as none, and reads back as null.

Response 201

The whole itinerary, with the new waypoint among its waypoints. Location names the waypoint, /v1/itineraries/{itinerary_id}/waypoints/{waypoint_id}, and extensions.metadata.created.id is its identifier. ETag carries the itinerary's new version.

extensions

object

required

The envelope's second half, everything the answer carries that is not the answer itself. Here that is metadata.created, the waypoint this request created.

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.

curl -s https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/waypoints \
  -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 '{
    "mode": "poi",
    "position": 0,
    "name": "Refuge du Fioux",
    "icon": "hut",
    "geojson": {"type": "Point", "coordinates": [6.7612, 45.8479]}
  }'
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"
      }
    ]
  },
  "extensions": {
    "metadata": {
      "created": {
        "id": "2c8e5f13-7a94-4b06-8d21-9e3f0a6c7b58"
      }
    }
  }
}

Update an existing waypoint

PATCH
/v1/itineraries/{itinerary_id}/waypoints/{waypoint_id}

Updates an existing waypoint within the itinerary. Every field is optional: an omitted field keeps its current value, and null clears a nullable one. A contact, media or timing object whose members are all null or absent (a media with empty lists included) is stored as none, so sending one clears the field.

Webhook events itinerary.waypoint.updated, recorded by the task itinerary.waypoint.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.

waypoint_id

string (uuid)

in path

required

Identifier of the waypoint within the itinerary named by itinerary_id. A waypoint belonging to another itinerary is a 404.

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 fields to change. A field you omit keeps its stored value, and a nullable field sent as null is cleared. A field the body does not declare, such as mode, is a 400 naming it: a waypoint's mode is set when it is created.

amenities

array of string | null

in body

Services and facilities available at this waypoint. Replaces the stored list wholesale rather than merging into it. Duplicates are rejected. Omit it to keep the current list; null or an empty array clears it.

color

string | null

in body

Hex color code for rendering this waypoint on the map. Both the three-digit and the six-digit forms are accepted, in either case, and either is stored as six lowercase digits (#F60 and #FF6600 both as #ff6600), which is the form every read returns. Omit it to keep the current value; null returns the waypoint to the default activity color.

contact

WaypointContact | null

in body

How to reach the place this waypoint marks. Replaces the stored object wholesale rather than merging into it. Omit it to keep the current value; null, or an object whose members are all null or absent, clears it.

description

string | null

in body

Free-text description of the waypoint, 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.

geojson

GeoJSONPoint | GeoJSONMultiPoint | GeoJSONLineString | GeoJSONMultiLineString | GeoJSONPolygon | GeoJSONMultiPolygon | GeoJSONGeometryCollection

in body

A bare GeoJSON Point representing the waypoint location, the shape a waypoint's geojson is read in, so a location read can be sent back as it is. Any other geometry, a GeometryCollection holding a Point included, is a 400 naming geojson. Optional and not nullable: omit it to leave the stored location untouched; a null is a 400. A position outside the longitude and latitude ranges, or one of more than three numbers, is a 400 naming the position at fault, for example geojson[0].

icon

string

in body

One of: circle-warning, megaphone, bed, apartment-building, camper-van, circle-check, parking-sign, medical-cross, droplet, eye, flag, flag-start, flag-end, hut, circle-info, map-pin, camping, trophy, cutlery, bus, train, cable-car, charging-station, gate, toilet, shower, trash, shop, picnic, helicopter, signal, climbing, ladder

Icon displayed on the waypoint. Required for a poi; optional for a point, which shows it when set. flag-start and flag-end are refused on every write (400). Optional and not nullable: omit it to leave the stored icon untouched. Unlike name, description and color, which are nullable here, an icon cannot be cleared through this operation.

media

WaypointMedia | null

in body

Photos and external links attached to this waypoint. Replaces the stored object wholesale rather than merging into it. Omit it to keep the current value; null, or an object whose members are all null, absent or empty lists, clears it.

name

string | null

in body

Display name of the waypoint, 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; null clears it. A poi requires a name, so clearing a poi's name is a 400 naming name; a point may be unnamed. 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.

position

integer (int32)

in body

Zero-based position of the waypoint within its parent itinerary, stored as given: no other waypoint moves to make room. Optional and not nullable: omit it to keep the current position. Between 0 and 9999.

properties

array of WaypointProperty | null

in body

Customer-defined fields for this waypoint. Replaces the stored list wholesale rather than merging into it. Keys must be unique within the waypoint. Omit it to keep the current list; null or an empty array clears it. At most 20: the server enforces the ceiling, and a list over it is a validation error rather than a truncation.

timing

WaypointTiming | null

in body

Cut-off and expected-arrival timing for this waypoint. Replaces the stored object wholesale rather than merging into it. Omit it to keep the current value; null, or an object whose members are all null or absent, clears it.

Response 200

The whole itinerary after the update, 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, 413, 429, 500, 504. See Errors.

# A field you omit keeps its stored value. A field you send replaces it whole:
# `amenities` is the complete new list, not the entries to add.
curl -s -X PATCH https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/waypoints/e8b1d740-2a96-4c53-b7f8-15d0a3c69e42 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Refuge du Fioux",
    "description": "Half-board, book ahead. Water point at the door.",
    "icon": "hut",
    "position": 1,
    "amenities": [
      "water",
      "hot-meal",
      "accommodation",
      "toilets",
      "timing-checkpoint"
    ],
    "timing": {
      "cutoff_at": "2026-08-28T21:30:00Z",
      "stop_duration": 900
    }
  }'
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 a waypoint from an itinerary

DELETE
/v1/itineraries/{itinerary_id}/waypoints/{waypoint_id}

Permanently deletes the waypoint. This action cannot be undone. The remaining waypoints keep their positions: nothing is renumbered.

Webhook events itinerary.waypoint.deleted, recorded by the task itinerary.waypoint.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.

waypoint_id

string (uuid)

in path

required

Identifier of the waypoint within the itinerary named by itinerary_id. A waypoint belonging to another itinerary is a 404.

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 whole itinerary after the delete, and its new ETag. The remaining waypoints keep their positions.

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.

# The remaining waypoints keep their positions: nothing is renumbered.
curl -s -X DELETE https://api.mountaya.com/v1/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21/waypoints/e8b1d740-2a96-4c53-b7f8-15d0a3c69e42 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
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"
      }
    ]
  }
}