User GuideDeveloper DocsAPI Reference
EndpointsCollections

Update collection

PATCH
/collections/{id}

Authorization

headerAuthorizationBearer <token>

Personal access token for non-browser clients. Mint at Settings → API Tokens. Carries one of two scopes: read (list/get Routes, export GPX, profile) or write (read plus metadata-only mutations on owned routes and on preferences). Blocked from /admin/* and from DELETE /users/me. Destructive operations require X-Routess-Confirm: true and return 428 PRECONDITION_REQUIRED otherwise. See ADR-0022 and ADR-0023.

Path Parameters

id*number

Collection ID

Header Parameters

X-Routess-Confirm?string

Set to true when a PAT call sets visibility: public. Cookie sessions ignore this header.

Request Body

application/json
  1. body
name?string

Name of the collection

Length1 <= length <= 100
description?string

Optional description

Lengthlength <= 255
visibility?string

Visibility of the collection. Same semantics as route visibility.

Default"private"
Value in"private""unlisted""public"

Response Body

application/json
  1. response
id*number
name*string
description?string
visibility*string
Value in"private""unlisted""public"
routeIds*array<number>

Ordered route IDs in this collection. For non-owners, private routes are omitted.

routeCount*number

Number of routes in the collection (after visibility filtering)

shareToken*string

Unguessable 32-hex handle for share links. Unlisted collections are only reachable anonymously via this token.

user*
createdAt*string
updatedAt*string
curl -X PATCH 'https://api.routess.com/collections/0' \  -H 'Content-Type: application/json' \  -d '{}'
{  "id": 0,  "name": "string",  "description": "string",  "visibility": "private",  "routeIds": [    0  ],  "routeCount": 0,  "shareToken": "9f86d081884c7d659a2feaa0c55ad015",  "user": {    "id": 1,    "name": "Jane Doe",    "handle": "jane-doe",    "avatar": "https://example.com/avatar.jpg",    "idHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"  },  "createdAt": "string",  "updatedAt": "string"}

Get collection by ID or share token

`ref` is a numeric collection ID (owners: any visibility; non-owners: public only, so sequential IDs can't be walked to discover unlisted collections) or a 32-hex share token (public and unlisted). Private routes inside are omitted for non-owners. Private collections return 404 to non-owners. Owners authenticate with a cookie session or any PAT.

Delete collection

Deletes the collection (soft-delete). Routes inside it are not deleted. PAT callers must set X-Routess-Confirm: true.