Get started

Collections

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.

The Collection object

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.

count

object

required

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_at

string (date-time)

required

Timestamp of the collection's creation.

created_by

object

required

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.

description

string | null

required

Free-text description of the collection. Null when it has none.

etag

string

required

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.

id

string (uuid)

required

Unique identifier of the collection.

is_private

boolean

required

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.

name

string

required

Display name of the collection.

organization_id

string (uuid) | null

required

Identifier of the organization that owns this collection. Null for a personal collection, made from an individual account and owned by no organization.

role

string

required

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.

sources

array of TileSource

required

Tile sources available for rendering this collection on a map.

updated_at

string (date-time)

required

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.

List collections

Returns 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

cursor

string

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.

limit

integer (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_id

string (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_id

string (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_id

string (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_private

boolean

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_since

string (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.

q

string

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.

sort

string

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.

extensions

object

required

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.

data

array of Collection

required

Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.

# Where an itinerary is filed, most recently changed first. With a session
# token naming a member the private collections are listed too.
curl -s "https://api.mountaya.com/v1/collections?itinerary_id=0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": [
    {
      "id": "3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13",
      "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
      "name": "Mont-Blanc classics",
      "description": "Multi-day hikes around the Mont-Blanc massif.",
      "is_private": true,
      "sources": [
        {
          "id": "0e9788ba-f680-4a74-8354-e7b7fe5ee061",
          "type": "vector",
          "attribution": "<a href=\"https://mountaya.com/\" target=\"_blank\">&copy; Mountaya</a>",
          "tiles": [
            "https://tiles.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/{z}/{x}/{y}"
          ],
          "zoom_min": 5,
          "zoom_max": 18,
          "layers": [
            {
              "id": "itineraries/0e9788ba-f680-4a74-8354-e7b7fe5ee061/lines",
              "key": "",
              "type": "line",
              "source": "0e9788ba-f680-4a74-8354-e7b7fe5ee061",
              "source_layer": "itinerary_lines",
              "zoom_min": 5,
              "zoom_max": 18,
              "layout": {
                "line-cap": "round",
                "line-join": "round"
              },
              "paint": {
                "line-color": "#2f80ed",
                "line-width": 3
              }
            }
          ]
        }
      ],
      "created_by": {
        "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
      },
      "created_at": "2026-05-12T09:14:00Z",
      "updated_at": "2026-06-28T16:02:00Z",
      "etag": "\"d12\"",
      "count": {
        "itineraries": 6,
        "zones": 2
      },
      "role": "owner"
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

Create a new collection

Creates 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-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

Body

The new collection's name, description and privacy, and the organization that owns it, which can only be the key's.

description

string

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_private

boolean

in body

required

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.

name

string

in body

required

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_id

string (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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

Collection

required

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.

See the Collection object.

Errors 400, 401, 402, 403, 404, 409, 413, 429, 500, 504. See Errors.

# The key makes a retry safe: the same key and body are answered with the first
# create's 201 rather than a second collection.
curl -s https://api.mountaya.com/v1/collections \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mont-Blanc classics",
    "description": "Multi-day hikes around the Mont-Blanc massif.",
    "is_private": true
  }'
201
Response
{
  "data": {
    "id": "3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Mont-Blanc classics",
    "description": "Multi-day hikes around the Mont-Blanc massif.",
    "is_private": true,
    "sources": [
      {
        "id": "0e9788ba-f680-4a74-8354-e7b7fe5ee061",
        "type": "vector",
        "attribution": "<a href=\"https://mountaya.com/\" target=\"_blank\">&copy; Mountaya</a>",
        "tiles": [
          "https://tiles.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/{z}/{x}/{y}"
        ],
        "zoom_min": 5,
        "zoom_max": 18,
        "layers": [
          {
            "id": "itineraries/0e9788ba-f680-4a74-8354-e7b7fe5ee061/lines",
            "key": "",
            "type": "line",
            "source": "0e9788ba-f680-4a74-8354-e7b7fe5ee061",
            "source_layer": "itinerary_lines",
            "zoom_min": 5,
            "zoom_max": 18,
            "layout": {
              "line-cap": "round",
              "line-join": "round"
            },
            "paint": {
              "line-color": "#2f80ed",
              "line-width": 3
            }
          }
        ]
      }
    ],
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "etag": "\"d12\"",
    "count": {
      "itineraries": 6,
      "zones": 2
    },
    "role": "owner"
  }
}

Retrieve a single collection with its itineraries and zones

GET
/v1/collections/{collection_id}

Returns the collection details, with counts of the itineraries and zones it contains.

Path parameters

collection_id

string (uuid)

in path

required

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

Collection

required

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.

See the Collection object.

Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.

# `count` is every itinerary and zone the collection holds, whoever asks. Its
# member listings hold only what YOU may see, so they can be shorter.
curl -s https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": {
    "id": "3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Mont-Blanc classics",
    "description": "Multi-day hikes around the Mont-Blanc massif.",
    "is_private": true,
    "sources": [
      {
        "id": "0e9788ba-f680-4a74-8354-e7b7fe5ee061",
        "type": "vector",
        "attribution": "<a href=\"https://mountaya.com/\" target=\"_blank\">&copy; Mountaya</a>",
        "tiles": [
          "https://tiles.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/{z}/{x}/{y}"
        ],
        "zoom_min": 5,
        "zoom_max": 18,
        "layers": [
          {
            "id": "itineraries/0e9788ba-f680-4a74-8354-e7b7fe5ee061/lines",
            "key": "",
            "type": "line",
            "source": "0e9788ba-f680-4a74-8354-e7b7fe5ee061",
            "source_layer": "itinerary_lines",
            "zoom_min": 5,
            "zoom_max": 18,
            "layout": {
              "line-cap": "round",
              "line-join": "round"
            },
            "paint": {
              "line-color": "#2f80ed",
              "line-width": 3
            }
          }
        ]
      }
    ],
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "etag": "\"d12\"",
    "count": {
      "itineraries": 6,
      "zones": 2
    },
    "role": "owner"
  }
}

Update an existing collection

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_id

string (uuid)

in path

required

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-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Body

The collection fields to change. Every field is optional; omitted fields are left as they are.

description

string | 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_private

boolean

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.

name

string

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

Collection

required

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.

See the Collection object.

Errors 400, 401, 402, 403, 404, 409, 412, 413, 429, 500, 504. See Errors.

# PATCH merges: an omitted field is left alone. Flipping `is_private` takes effect at
# once for key reads; a share link reaches the collection whatever its privacy.
curl -s -X PATCH https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mont-Blanc classics",
    "description": "Multi-day hikes around the Mont-Blanc massif, refreshed for summer.",
    "is_private": false
  }'
200
Response
{
  "data": {
    "id": "3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13",
    "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
    "name": "Mont-Blanc classics",
    "description": "Multi-day hikes around the Mont-Blanc massif.",
    "is_private": true,
    "sources": [
      {
        "id": "0e9788ba-f680-4a74-8354-e7b7fe5ee061",
        "type": "vector",
        "attribution": "<a href=\"https://mountaya.com/\" target=\"_blank\">&copy; Mountaya</a>",
        "tiles": [
          "https://tiles.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/{z}/{x}/{y}"
        ],
        "zoom_min": 5,
        "zoom_max": 18,
        "layers": [
          {
            "id": "itineraries/0e9788ba-f680-4a74-8354-e7b7fe5ee061/lines",
            "key": "",
            "type": "line",
            "source": "0e9788ba-f680-4a74-8354-e7b7fe5ee061",
            "source_layer": "itinerary_lines",
            "zoom_min": 5,
            "zoom_max": 18,
            "layout": {
              "line-cap": "round",
              "line-join": "round"
            },
            "paint": {
              "line-color": "#2f80ed",
              "line-width": 3
            }
          }
        ]
      }
    ],
    "created_by": {
      "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
    },
    "created_at": "2026-05-12T09:14:00Z",
    "updated_at": "2026-06-28T16:02:00Z",
    "etag": "\"d12\"",
    "count": {
      "itineraries": 6,
      "zones": 2
    },
    "role": "owner"
  }
}

Delete a collection

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_id

string (uuid)

in path

required

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-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

If-Match

string

in header

Makes the write conditional on the resource still being the version the caller read: the ETag an earlier answer carried, which is also that resource's etag field, or * for any version. When the resource has changed since, the write is refused with 412 PRECONDITION_FAILED, nothing is changed, and the answer carries the current ETag, so the caller reads the resource again and decides. Omitted, the write is unconditional and the last write wins.

Response 200

The collection is deleted. The itineraries and zones it held survive. data is null.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 402, 403, 404, 409, 412, 429, 500, 504. See Errors.

# Deletes the folder only. The itineraries and zones inside it are not deleted.
curl -s -X DELETE https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": null
}
GET
/v1/collections/{collection_id}/share-link

Returns 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_id

string (uuid)

in path

required

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ShareLink | null

required

Errors 400, 401, 402, 403, 404, 429, 500, 504. See Errors.

# `data` is null when the collection has no link; this never mints one.
curl -s https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/share-link \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq '.data'
200
Response
{
  "data": {
    "share_token": "share_4f9c2a7e15b83d06e4a91c7fb250d83a",
    "created_at": "2026-09-14T10:22:05Z"
  }
}
POST
/v1/collections/{collection_id}/share-link

Sets 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_id

string (uuid)

in path

required

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-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ShareLink

required

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.

# No body. Calling it again returns the same token rather than a second one.
curl -s -X POST https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/share-link \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" | jq -r '.data.share_token'
200
Response
{
  "data": {
    "share_token": "share_4f9c2a7e15b83d06e4a91c7fb250d83a",
    "created_at": "2026-09-14T10:22:05Z"
  }
}
DELETE
/v1/collections/{collection_id}/share-link

Removes 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_id

string (uuid)

in path

required

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-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

any | null

required

Always null: this operation answers with no payload.

Errors 400, 401, 402, 403, 404, 409, 429, 500, 504. See Errors.

# Breaks every URL already handed out. There is no undo: minting again produces a
# new token, not the old one.
curl -s -X DELETE https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/share-link \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": null
}

Rotate the collection's share link

POST
/v1/collections/{collection_id}/share-link/rotate

Replaces 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_id

string (uuid)

in path

required

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-Key

string

in header

A value the caller chooses once per logical write and sends again, unchanged, on every retry of it, so a write whose answer was lost runs at most once. A UUID is the usual choice; any 1 to 255 printable ASCII characters without a space are accepted. The key is held for 12 hours, for the credential that sent it (the publishable key and the user its session token names) and for this operation.

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.

extensions

object

Top-level extensions map for 2xx responses. Mirrors the GraphQL-spec response extensions: a free-form map for response-scoped metadata.

data

ShareLink

required

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.

# Rotating breaks every URL already handed out and returns a new token in the same
# call, so a link can be replaced without a window where none works. Reuse the
# same key on a retry, or the retry rotates again.
curl -s -X POST https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/share-link/rotate \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Idempotency-Key: $(uuidgen)"
200
Response
{
  "data": {
    "share_token": "share_4f9c2a7e15b83d06e4a91c7fb250d83a",
    "created_at": "2026-09-14T10:22:05Z"
  }
}