Get started
Collections

Collection Zones

Collection Zones

Which zones belong to a collection.

List the zones a collection contains

GET
/v1/collections/{collection_id}/zones

Returns the zones filed in the collection, one page at a time.

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: -updated_at

One of: -updated_at, updated_at, name, -name

The order the listing is served in, by one key: updated_at or name, ascending as written and descending with a leading -. -updated_at when omitted, so the zone 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 zones 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 Zone

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/zones?limit=50&sort=name" \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token"
200
Response
{
  "data": [
    {
      "id": "c40f8a25-7e63-4d19-b8a0-9f2e5c31d764",
      "organization_id": "d5a83e17-92c6-4b0f-a7d3-1e6482f9c05b",
      "name": "Tricot trailhead, one hour",
      "description": "Terrain reachable on foot within an hour of the Col du Tricot trailhead.",
      "level": "info",
      "mode": "polygon",
      "is_private": false,
      "status": "published",
      "published_at": "2026-06-28T16:05:00Z",
      "has_unpublished_changes": false,
      "start_at": "2026-07-01T00:00:00Z",
      "end_at": "2026-08-31T23:59:59Z",
      "source": {
        "kind": "isochrones",
        "activity": "hiking-and-trail",
        "location": [
          6.7845,
          45.8612
        ],
        "range_type": "time",
        "range": 3600
      },
      "geojson": {
        "type": "Feature",
        "id": "c40f8a25-7e63-4d19-b8a0-9f2e5c31d764",
        "properties": {},
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                6.7845,
                45.8612
              ],
              [
                6.7961,
                45.8612
              ],
              [
                6.7961,
                45.8698
              ],
              [
                6.7845,
                45.8698
              ],
              [
                6.7845,
                45.8612
              ]
            ]
          ]
        }
      },
      "revision": 4,
      "etag": "\"d4\"",
      "created_by": {
        "id": "7a3e5d18-4c60-49b2-8f75-e2d1c9a4b607"
      },
      "created_at": "2026-05-12T09:14:00Z",
      "updated_at": "2026-06-28T16:02:00Z"
    }
  ],
  "extensions": {
    "metadata": {
      "pagination": {
        "limit": 50,
        "next_cursor": "eyJ2IjoxLCJzIjoiLXVwZGF0ZWRfYXQifQ"
      }
    }
  }
}

Add zones to a collection

Adds one or more zones to the collection. Zones that are already in the collection are 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.zone.added, recorded by the task collection.zone.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 zones to add to the collection, by id.

zone_ids

array of string (uuid)

in body

required

The zones 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 zones are in the collection. data is the collection after the change, as getCollection reads it, with its new etag. 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 a zone already in the collection is not an error. Every
# zone must belong to the same organization as the collection.
curl -s -X POST https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/zones \
  -H "X-API-Key: pk_your_publishable_key" \
  -H "X-Session-Token: sess_your_session_token" \
  -H "Content-Type: application/json" \
  -d '{
    "zone_ids": [
      "5e8c3a91-7b24-4f0d-9c68-1a5e2d7b3f90",
      "0d6f2b47-9e13-4c8a-b5f0-7a2c4e8d1b39"
    ]
  }'
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 a zone from a collection

DELETE
/v1/collections/{collection_id}/zones/{zone_id}

Removes one zone from the collection. The zone 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.zone.removed, recorded by the task collection.zone.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.

zone_id

string (uuid)

in path

required

Identifier of the zone the operation acts on.

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

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 zone itself is untouched.
curl -s -X DELETE https://api.mountaya.com/v1/collections/3f1b9c42-8a6e-4d55-9f1a-2c7e5b0d4a13/zones/5e8c3a91-7b24-4f0d-9c68-1a5e2d7b3f90 \
  -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"
  }
}