Collection Itineraries
Which itineraries belong to a collection, and in what order.
/v1/collections/{collection_id}/itinerariesReturns the itineraries filed in the collection, one page at a time, in the collection's own ordering unless sort names another.
Path parameters
collection_idstring (uuid)
in path
Identifier of the collection the operation acts on. A collection 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 collection ids exist.
Query parameters
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.
sortstring
in query
default: position
One of: position, -updated_at, name, -name
The order the listing is served in, by one key. position is the collection's own ordering, the one patchCollectionItinerary sets, and is used when this is omitted. -updated_at lists the itinerary changed last first, and name and -name list by name, ascending and descending. Ties break on id, so no two items share a place in the order, and a page boundary never falls between two that compare equal.
Response 200
One page of the itineraries this collection contains, in the order sort names. extensions.metadata.pagination.next_cursor asks for the next page, and is 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 alone: the limit this page was served at, and the next_cursor that asks for the next one, null on the last page.
dataarray of Itinerary
See the Itinerary object.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/collections/{collection_id}/itinerariesAdds one or more itineraries to the collection. New members are appended at the end of the collection's ordering. Itineraries that are already in the collection keep their place and are otherwise silently ignored, so re-sending the same set is safe: it changes nothing, and answers the collection as it stands. The answer is the collection after the change, as getCollection reads it, so its count and etag include what was added.
Webhook events collection.itinerary.added, recorded by the task collection.itinerary.add.
Path parameters
collection_idstring (uuid)
in path
Identifier of the collection the operation acts on. A collection 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 collection 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 itineraries to add to the collection, by id.
itinerary_idsarray of string (uuid)
in body
The itineraries to file into the collection. Every one is resolved and authorized before any membership is written, so the call succeeds or fails as a whole. A repeated identifier is collapsed rather than refused, which is the same answer as naming one that is already a member, and an empty array is a successful call that changes nothing.
Response 200
The itineraries are in the collection. data is the collection after the change, as getCollection reads it, with its new etag; list getCollectionItineraries for the ordering. Adding only what the collection already holds changes nothing, and data is the collection as it stands.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataCollection
A collection grouping itineraries and zones for shared access and map rendering, as it appears to the calling credential: the collection itself, what it contains, the role the request carries in the organization that owns it, and the tile sources that render its contents on a map.
Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.
/v1/collections/{collection_id}/itineraries/{itinerary_id}Sets the zero-based display position of an itinerary within the collection and renumbers the remaining itineraries so positions stay contiguous. A position beyond the current range is clamped to the last slot. The answer is the collection after the move, as getCollection reads it.
Webhook events collection.itinerary.moved, recorded by the task collection.itinerary.move.
Path parameters
collection_idstring (uuid)
in path
Identifier of the collection the operation acts on. A collection 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 collection ids exist.
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 membership fields to change for one itinerary in the collection, such as its position in the ordering.
positioninteger (int32)
in body
Zero-based display order of the itinerary within the collection, between 0 and 9999. A position beyond the last slot is clamped to it.
Response 200
The itinerary is at its new position. data is the collection after the move, as getCollection reads it, with its new etag; list getCollectionItineraries in its default position order to see the new ordering.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataCollection
A collection grouping itineraries and zones for shared access and map rendering, as it appears to the calling credential: the collection itself, what it contains, the role the request carries in the organization that owns it, and the tile sources that render its contents on a map.
Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.
/v1/collections/{collection_id}/itineraries/{itinerary_id}Removes one itinerary from the collection and closes the collection's ordering up around the gap. The itinerary itself is not deleted: only its place in this collection is, so it stays in its organization and in every other collection holding it. A link minted for this collection stops reaching it. The answer is the collection after the change, as getCollection reads it.
Webhook events collection.itinerary.removed, recorded by the task collection.itinerary.remove.
Path parameters
collection_idstring (uuid)
in path
Identifier of the collection the operation acts on. A collection 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 collection ids exist.
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 not in the collection. data is the collection after the removal, as getCollection reads it, with its new etag, or the collection as it stands when it did not hold the itinerary.
extensionsobject
Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.
dataCollection
A collection grouping itineraries and zones for shared access and map rendering, as it appears to the calling credential: the collection itself, what it contains, the role the request carries in the organization that owns it, and the tile sources that render its contents on a map.
Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.