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.
An itinerary organizing one or more segments into a multi-day or multi-stage plan for an outdoor activity.
activity_idstring (uuid)
Identifier of the activity type for the whole itinerary. Set at creation and immutable; every segment shares this activity.
ascentinteger (int32) | null
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).
countobject
How many segments and waypoints the itinerary holds. A summary count, so a client can size a list without fetching the details.
created_atstring (date-time)
Timestamp of the itinerary's creation.
created_byobject
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.
descriptionstring | null
Free-text description of the itinerary. Null when it has none.
distancenumber (double) | null
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).
idstring (uuid)
Unique identifier of the itinerary.
is_privateboolean
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_verifiedboolean
Whether the itinerary has been verified by the organization.
namestring
Display name of the itinerary.
organization_idstring (uuid) | null
Identifier of the organization that owns this itinerary. Null for a personal itinerary, made from an individual account and owned by no organization.
etagstring
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.
revisioninteger (int32)
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.
statusstring
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_atstring (date-time)
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.
An itinerary with its full list of segments, waypoints, and segment groups included, plus its derived publication state.
activity_idstring (uuid)
Identifier of the activity type for the whole itinerary. Set at creation and immutable; every segment shares this activity.
ascentinteger (int32) | null
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).
countobject
How many segments and waypoints the itinerary holds. A summary count, so a client can size a list without fetching the details.
created_atstring (date-time)
Timestamp of the itinerary's creation.
created_byobject
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.
descriptionstring | null
Free-text description of the itinerary. Null when it has none.
distancenumber (double) | null
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).
idstring (uuid)
Unique identifier of the itinerary.
is_privateboolean
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_verifiedboolean
Whether the itinerary has been verified by the organization.
namestring
Display name of the itinerary.
organization_idstring (uuid) | null
Identifier of the organization that owns this itinerary. Null for a personal itinerary, made from an individual account and owned by no organization.
etagstring
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.
revisioninteger (int32)
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.
statusstring
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_atstring (date-time)
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.
groupsarray of ItinerarySegmentGroup
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_changesboolean
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_atstring (date-time) | null
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.
segmentsarray of ItinerarySegment
Ordered list of segments belonging to this itinerary.
waypointsarray of ItineraryWaypoint
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_tokenstring
The share credential: the literal prefix share_ followed by 32 lowercase hexadecimal characters.
created_atstring (date-time)
When this token was minted: when the link was first made, or last rotated.
/v1/itinerariesReturns 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_idstring (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.
statusstring
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_privateboolean
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_idstring (uuid)
in query
Lists only the itineraries of this activity, one getActivities lists.
in_collectionboolean
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_sincestring (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.
qstring
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.
sortstring
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.
cursorstring
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.
limitinteger (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.
extensionsobject
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.
dataarray of Itinerary
See the Itinerary object.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/itinerariesCreates 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-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.
Body
The new itinerary's name, activity and ownership. Segments and waypoints are added afterwards, through their own operations.
activity_idstring (uuid)
in body
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.
descriptionstring
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_privateboolean
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.
namestring
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. 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_idstring (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.
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, 413, 429, 500, 504. See Errors.
/v1/itineraries/previewParses 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-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.
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.
providerstring
in body
One of: gpx, geojson, kml, kmz, fit, tcx
Format the upload is parsed in.
filestring (binary)
in body
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_idstring (uuid)
in body
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_idstring (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.
granularitystring
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataItineraryImportPreview
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.
/v1/itineraries/importPersists 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-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.
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.
namestring
in body
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.
descriptionstring
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_privateboolean
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.
activity_idstring (uuid)
in body
Identifier of the activity type for the itinerary, one getActivities lists; any other identifier is a 400.
organization_idstring (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.
segmentsarray of ItineraryImportConfirmSegment
in body
Ordered finalized segments to persist.
waypointsarray of ItineraryImportConfirmWaypoint
in body
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.
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, 413, 429, 500, 504. See Errors.
/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_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.
Query parameters
surfacestring
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.
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, 429, 500, 504. See Errors.
/v1/itineraries/{itinerary_id}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_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 itinerary fields to change. Every field is optional; omitted fields are left as they are.
descriptionstring | 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_privateboolean
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.
namestring
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.
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}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_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.
Response 200
The itinerary is deleted, along with its segments and waypoints. data is null.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.
/v1/itineraries/{itinerary_id}/duplicateCopies 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_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.
Query parameters
surfacestring
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-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.
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.
namestring
in body
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_idstring (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_idsarray 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_idsarray 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.
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, 413, 429, 500, 504. See Errors.
/v1/itineraries/{itinerary_id}/publicationSets 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_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.
Response 200
The itinerary as published, with status published and published_at set, 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, 429, 500, 504. See Errors.
/v1/itineraries/{itinerary_id}/publicationTakes 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_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.
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.
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.
/v1/itineraries/{itinerary_id}/exportExports 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_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.
Query parameters
formatstring
in query
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.
variantstring
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_idstring (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.
surfacestring
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.
/v1/itineraries/{itinerary_id}/paceAnswers 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_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.
Query parameters
speednumber (double)
in query
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.
surfacestring
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataItineraryPace
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.
/v1/itineraries/{itinerary_id}/share-linkReturns 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_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.
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataShareLink | null
See the ShareLink object.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/itineraries/{itinerary_id}/share-linkSets 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_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.
Response 200
The itinerary already had a share link, and this is it, token unchanged. Nothing was minted.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataShareLink
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.
/v1/itineraries/{itinerary_id}/share-linkRemoves 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_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.
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataany | null
Always null: this operation answers with no payload.
Errors 400, 401, 402, 403, 404, 409, 429, 500, 504. See Errors.
/v1/itineraries/{itinerary_id}/share-link/rotateReplaces 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_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.
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.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataShareLink
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.