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.
/v1/itineraries/{itinerary_id}/waypointsCreates 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_idstring (uuid)
in path
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-Keystring
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-Matchstring
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.
amenitiesarray of string
in body
Services and facilities available at this waypoint. Duplicates are rejected. Optional and not nullable: omit it for none.
colorstring
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.
contactobject
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.
descriptionstring
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.
geojsonGeoJSONPoint | 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. 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].
iconstring
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.
mediaobject
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.
modestring
in body
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.
namestring
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.
positioninteger (int32)
in body
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.
propertiesarray 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.
timingobject
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.
extensionsobject
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.
dataItineraryWithDetails
An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.
Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.
/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_idstring (uuid)
in path
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_idstring (uuid)
in path
Identifier of the waypoint within the itinerary named by itinerary_id. A waypoint belonging to another itinerary is a 404.
Headers
Idempotency-Keystring
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-Matchstring
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.
amenitiesarray 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.
colorstring | 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.
contactWaypointContact | 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.
descriptionstring | 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.
geojsonGeoJSONPoint | 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].
iconstring
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.
mediaWaypointMedia | 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.
namestring | 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.
positioninteger (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.
propertiesarray 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.
timingWaypointTiming | 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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataItineraryWithDetails
An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.
Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.
/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_idstring (uuid)
in path
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_idstring (uuid)
in path
Identifier of the waypoint within the itinerary named by itinerary_id. A waypoint belonging to another itinerary is a 404.
Headers
Idempotency-Keystring
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-Matchstring
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataItineraryWithDetails
An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.
Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.