Collections
Named groups of itineraries and zones, scoped to an organization. A collection is how a set of routes is handed out together: to an embed, to a share link, or to a client filtering by one id instead of many.
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.
countobject
How many itineraries and zones the collection holds, whoever asks: a member the caller cannot see is counted all the same, so walking a member listing to its end can yield fewer than this.
created_atstring (date-time)
Timestamp of the collection's creation.
created_byobject
The user who created the collection. It is the author rather than the last editor, and it does not move when another member edits the collection.
descriptionstring | null
Free-text description of the collection. Null when it has none.
etagstring
The version of everything a read of this collection returns, the one the ETag of that read carries, opaque and compared whole. It moves on every write that changes the read, its contents included: an itinerary or a zone added, removed or moved. Send it as If-Match to make a write to the collection conditional.
idstring (uuid)
Unique identifier of the collection.
is_privateboolean
Whether the collection is private. A private collection is reached only with the key of the organization that owns it, so a private personal collection, owned by no organization, is reached by no key. A public collection is readable by id, read-only, with any publishable key that knows its identifier, and it is listed only in its own organization's listings. A share token reaches only what its link names, and reaches the collection it names whatever this says. Public never grants editing, which takes a write role in the owning organization.
namestring
Display name of the collection.
organization_idstring (uuid) | null
Identifier of the organization that owns this collection. Null for a personal collection, made from an individual account and owned by no organization.
rolestring
One of: owner, admin, contributor, viewer
The role this request carries in the organization that owns the collection, not a property of the collection: viewer on a read made with a publishable key or a share token, neither of which holds a membership, and on a write's response the role of the user the session token names. Offer edit controls from the role of the member who will act.
sourcesarray of TileSource
Tile sources available for rendering this collection on a map.
updated_atstring (date-time)
When the collection itself last changed. Every patchCollection moves it, even one that changes nothing, while adding, removing or reordering its itineraries and zones never does. Always present: it equals created_at until the first patch.
/v1/collectionsReturns the collections of the key's organization that this credential reaches, one page at a time. A collection belongs to the organization that owns it, not to the user who created it, so this is the listing every member shares.
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.
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.
itinerary_idstring (uuid)
in query
Lists only the collections holding this itinerary. An identifier that names nothing this credential can view lists nothing, the same answer as an itinerary no collection holds.
zone_idstring (uuid)
in query
Lists only the collections holding this zone. An identifier that names nothing this credential can view lists nothing, the same answer as a zone no collection holds.
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.
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, by one key: updated_at, created_at or name, ascending as written and descending with a leading -. -updated_at when omitted, so the collection changed last comes first. 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 collections this credential reaches, 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 Collection
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/collectionsCreates a new collection in the key's organization. Returns 409 Conflict when another collection in that organization already carries the name.
Webhook events collection.created, recorded by the task collection.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 collection's name, description and privacy, and the organization that owns it, which can only be the key's.
descriptionstring
in body
Free-text description of the collection, at most 100 characters as sent, stored with leading and trailing whitespace trimmed. Omit it, or send one that trims to nothing, to create the collection without one.
is_privateboolean
in body
Whether the collection is private. A private collection is reached only with the key of the organization that owns it, so a private personal collection, owned by no organization, is reached by no key. A public collection is readable by id, read-only, with any publishable key that knows its identifier, and it is listed only in its own organization's listings. A share token reaches only what its link names, and reaches the collection it names whatever this says. Public never grants editing, which takes a write role in the owning organization.
namestring
in body
Display name of the collection, at most 30 characters as sent, and at least 2 once leading and trailing whitespace is trimmed. Refused with a 409 when another collection in the organization already carries it. Names are compared exactly after trimming, case included, so Alps and alps are two different names. 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 collection. It must be the key's organization; omitted, it is that organization.
Response 201
The collection as created, empty. Location names it, /v1/collections/{collection_id}, and ETag carries its first version.
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, 413, 429, 500, 504. See Errors.
/v1/collections/{collection_id}Returns the collection details, with counts of the itineraries and zones it contains.
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.
Response 200
The collection, with counts of the itineraries and zones it holds.
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, 429, 500, 504. See Errors.
/v1/collections/{collection_id}Updates the collection's name, description and privacy. Every field is optional and an omitted field keeps its current value; send null, or a description that trims to nothing, to clear the description.
Webhook events collection.updated, recorded by the task collection.update.
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 collection fields to change. Every field is optional; omitted fields are left as they are.
descriptionstring | null
in body
Free-text description of the collection, at most 100 characters as sent, stored with leading and trailing whitespace trimmed. Omit to keep the current value; null, or a value that trims to nothing, clears it.
is_privateboolean
in body
Whether the collection is private. A private collection is reached only with the key of the organization that owns it, so a private personal collection, owned by no organization, is reached by no key. A public collection is readable by id, read-only, with any publishable key that knows its identifier, and it is listed only in its own organization's listings. A share token reaches only what its link names, and reaches the collection it names whatever this says. Public never grants editing, which takes a write role in the owning organization. Omit to keep the current value.
namestring
in body
Display name of the collection. Omit to keep the current value. At most 30 characters as sent, and at least 2 once leading and trailing whitespace is trimmed; refused with a 409 when another collection in the organization already carries it. Names are compared exactly after trimming, case included, so Alps and alps are two different names. 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 collection after the change, with 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.
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}Permanently deletes the collection. The itineraries and zones it held are NOT deleted: only the references linking them to this collection are, so every resource survives in the organization that owns it. This action cannot be undone.
Webhook events collection.deleted, recorded by the task collection.delete.
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.
Response 200
The collection is deleted. The itineraries and zones it held survive. 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/collections/{collection_id}/share-linkReturns the collection's share link, its token and when that token was minted, or null when the collection has none. Reading never mints one: postCollectionShareLink does.
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.
Response 200
The collection's share link, or null when it has none: none was minted, or the last one was removed. An absent link is not an error, so a client reads it here and offers to mint one when 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.
dataShareLink | null
See the ShareLink object.
Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.
/v1/collections/{collection_id}/share-linkSets the collection's share link: mints one when the collection has none, answering 201, and returns the existing one otherwise, answering 200, so calling again never mints a second token. Both private and public collections are shareable.
Webhook events collection.share_link.created, recorded by the task collection.share_link.create.
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.
Response 200
The collection already had a share link, and this is it, unchanged. getCollectionShareLink reads the same link back; getCollection never carries the token.
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/collections/{collection_id}/share-linkRemoves the collection'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. A collection with no share link is answered the same way, so removing a link that is already gone is not an error.
Webhook events collection.share_link.deleted, recorded by the task collection.share_link.delete.
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.
Response 200
The collection has no share link: this call removed it, or it had none. A request carrying the old token gets a 401 from the next request on, but for an answer a shared cache already holds. 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/collections/{collection_id}/share-link/rotateReplaces the collection's share token with a freshly generated one and returns the link with 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). It takes the same write role the mint takes. A collection with no share link has nothing to rotate, and is a 409: mint one with postCollectionShareLink. A personal collection, owned by no organization, has no share link, and rotating one for it, which only Mountaya's web application could ask for, is refused with a 403 as the mint is.
Webhook events collection.share_link.rotated, recorded by the task collection.share_link.rotate.
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.
Response 200
The share link with its new token. 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.