User GuideDeveloper DocsAPI Reference
EndpointsCollections

Set collection routes

Replaces the collection's full ordered membership. All route IDs must reference routes owned by the caller; array order defines position.

PUT
/collections/{id}/routes

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

Request Body

application/json
  1. body
routeIds*array<number>

Full ordered membership of the collection. Replaces the existing membership; order defines the position of each route.

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
routes*array<>

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

curl -X PUT 'https://api.routess.com/collections/0/routes' \  -H 'Content-Type: application/json' \  -d '{  "routeIds": [    12,    7,    31  ]}'
{  "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",  "routes": [    {      "id": 0,      "name": "string",      "description": "string",      "activity": "run",      "visibility": "private",      "tags": [        "string"      ],      "favourite": true,      "waypoints": [        {          "coord": [            -74.006,            40.7128          ],          "type": "routed",          "name": "string",          "timestamp": "string"        }      ],      "geometry": [        "string"      ],      "distance": 0,      "duration": 0,      "elevationGain": 0,      "startAddress": "string",      "endAddress": "string",      "placeCity": "string",      "placeRegion": "string",      "placeCountryCode": "string",      "routingPreferences": {        "surfacePreference": "mixed",        "avoidFerries": true,        "avoidHighways": true      },      "provenance": "valhalla",      "shareToken": "9f86d081884c7d659a2feaa0c55ad015",      "user": {        "id": 1,        "name": "Jane Doe",        "handle": "jane-doe",        "avatar": "https://example.com/avatar.jpg",        "idHash": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"      },      "createdAt": "string",      "updatedAt": "string"    }  ]}

Delete collection

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

Match a recorded shape against the road network

Forwards the shape to the self-hosted Valhalla `trace_attributes` endpoint and returns per-edge surface data. Used by the web app to render surface composition for a Route.