Get started
Collections

Collection Itineraries

Collection Itineraries

Which itineraries belong to a collection, and in what order.

List the itineraries a collection contains

GET
/v1/collections/{collection_id}/itineraries

Returns the itineraries filed in the collection, one page at a time, in the collection's own ordering unless sort names another.

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.

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.

sort

string

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.

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 Itinerary

required

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

# A share token enumerates the same way a key does, and is the credential a
# link-visitor holds. Swap `X-API-Key` for `X-Share-Token` to read as one.
curl -s "https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/itineraries?limit=50" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": [
    {
      "id": "8f14e45f-ceea-467a-9ba5-2b6d3a71c9e0",
      "name": "Tour du Mont-Blanc",
      "description": "Ten stages from Les Houches, anticlockwise.",
      "activity_id": "a1c4e7b2-3d59-4f08-8b6a-2e5c9d0f7134",
      "organization_id": "2b7d6e5f-4c3a-4918-8f07-6e5d4c3b2a19",
      "status": "draft",
      "is_private": true,
      "is_verified": false,
      "distance": 169842.5,
      "ascent": 9827,
      "count": {
        "segments": 10,
        "waypoints": 24,
        "groups": 10
      },
      "revision": 7,
      "etag": "\"d31\"",
      "created_at": "2026-07-04T09:12:41Z",
      "updated_at": "2026-07-11T16:03:08Z",
      "created_by": {
        "id": "4d9a2f13-7c60-4b85-9e12-3a8f6b0c5d74"
      }
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

Add itineraries to a collection

POST
/v1/collections/{collection_id}/itineraries

Adds 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_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 itineraries to add to the collection, by id.

itinerary_ids

array of string (uuid)

in body

required

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.

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.

# Membership is a set: adding an itinerary that is already in the collection is
# not an error. `data` is the collection after the add.
curl -s https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/itineraries \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "itinerary_ids": [
      "0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21",
      "b47d1e08-5c93-4a6f-8e21-3d9f7a0c5b64"
    ]
  }'
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"
  }
}

Set an itinerary's position within a collection

PATCH
/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_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.

itinerary_id

string (uuid)

in path

required

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-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 membership fields to change for one itinerary in the collection, such as its position in the ordering.

position

integer (int32)

in body

required

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.

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.

# `position` is where it lands, zero-based. Everything between the old and new
# position shifts by one.
curl -s -X PATCH https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/itineraries/0b6d1a4e-6d3f-4f7a-9c2e-1f0a5b8c3d21 \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "position": 2
  }'
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"
  }
}

Remove an itinerary from a collection

DELETE
/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_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.

itinerary_id

string (uuid)

in path

required

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

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, 429, 500, 504. See Errors.

# Removes the membership only; the itinerary itself is untouched. The
# collection's ordering closes up around the gap.
curl -s -X DELETE https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/itineraries/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"
  }
}