User GuideDeveloper DocsAPI Reference
EndpointsRoutes

Update route

Updates a specific route for the authenticated user.

PATCH
/routes/{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

Route 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 route

Length1 <= length
description?string

Optional description of the route

activity?string

Activity associated with the route

Value in"run""cycle""walk"
visibility?string

Visibility of the route

Default"private"
Value in"private""unlisted""public"
tags?array<string>

Free-form tags for the route. Each tag is lowercase alphanumeric plus '-', 1 to 24 characters, must start with a letter or digit. Max 10 tags per route. Values are normalised server-side (lowercased, whitespace collapsed to hyphens).

favourite?boolean

Whether the owner marked this route as a favourite

Defaultfalse
waypoints?array<>

Array of waypoints that define the route

Items1 <= items
geometry?array<string>

Routed polyline as an array of [lng, lat] coordinate pairs

distance?number

Total distance of the route in meters

duration?number

Estimated duration of the route in seconds

elevationGain?number

Total elevation gain of the route in meters

startAddress?string

Human-readable starting address

endAddress?string

Human-readable ending address

routingPreferences?

Inputs that produced this route's geometry. Optional: routes saved from clients without this metadata (e.g. legacy clients, GPX imports, agents that didn't capture the prefs) are persisted with routingPreferences = null and remain usable but cannot be recalculated against their original inputs.

Response Body

Route updated successfully

application/json
  1. response
id*number
name*string
description?string
activity?string
Value in"run""cycle""walk"
visibility*string
Value in"private""unlisted""public"
tags*array<string>
favourite*boolean

Whether the owner marked this route as a favourite

waypoints*array<>
geometry?array<string>

Routed polyline as an array of [lng, lat] coordinate pairs

distance?number

Distance in meters

duration?number

Duration in seconds

elevationGain?number

Elevation gain in meters

startAddress?string
endAddress?string
placeCity?string

Derived Place city (CONTEXT.md 'Place'). Server-derived, never user-edited.

placeRegion?string

Derived Place region.

placeCountryCode?string

Derived Place ISO 3166-1 alpha-2 country code.

routingPreferences?

Inputs that produced this route's geometry. Null for legacy / GPX-imported routes.

provenance*string

How this route was produced.

Value in"valhalla""mapbox-legacy""gpx-import""generation"
shareToken*string

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

user*
createdAt*string
updatedAt*string
curl -X PATCH 'https://api.routess.com/routes/0' \  -H 'Content-Type: application/json' \  -d '{}'
{  "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"}

Get route by ID or share token

Returns the route. `ref` is either a numeric route ID (owners see any visibility; non-owners only public, so sequential IDs can't be walked to discover unlisted routes) or a 32-hex share token (serves public and unlisted to anyone with the link). Private routes return 404 to non-owners. Owners authenticate with a cookie session or any PAT.

Delete route

Deletes a specific route for the authenticated user. PAT callers must set X-Routess-Confirm: true.