Create a new route
Creates a new route for the authenticated user. PAT callers need `write` scope (#170) and must set X-Routess-Confirm: true when creating with `visibility: public`, mirroring the PATCH gate.
AuthorizationBearer <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.
X-Routess-Confirm?stringSet to true when a PAT call creates a route with visibility: public. Cookie sessions ignore this header.
application/json- body
name*stringName of the route
1 <= lengthdescription?stringOptional description of the route
activity?stringActivity associated with the route
"run""cycle""walk"visibility?stringVisibility of the route
"private""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?booleanWhether the owner marked this route as a favourite
falsewaypoints*array<>Array of waypoints that define the route
1 <= itemsgeometry?array<string>Routed polyline as an array of [lng, lat] coordinate pairs
distance?numberTotal distance of the route in meters
duration?numberEstimated duration of the route in seconds
elevationGain?numberTotal elevation gain of the route in meters
startAddress?stringHuman-readable starting address
endAddress?stringHuman-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.
provenance?stringHow this route was produced. Defaults to 'valhalla' for new routes.
"valhalla""mapbox-legacy""gpx-import""generation"Route created successfully
application/json- response
id*numbername*stringdescription?stringactivity?string"run""cycle""walk"visibility*string"private""unlisted""public"tags*array<string>favourite*booleanWhether the owner marked this route as a favourite
waypoints*array<>geometry?array<string>Routed polyline as an array of [lng, lat] coordinate pairs
distance?numberDistance in meters
duration?numberDuration in seconds
elevationGain?numberElevation gain in meters
startAddress?stringendAddress?stringplaceCity?stringDerived Place city (CONTEXT.md 'Place'). Server-derived, never user-edited.
placeRegion?stringDerived Place region.
placeCountryCode?stringDerived Place ISO 3166-1 alpha-2 country code.
routingPreferences?Inputs that produced this route's geometry. Null for legacy / GPX-imported routes.
provenance*stringHow this route was produced.
"valhalla""mapbox-legacy""gpx-import""generation"shareToken*stringUnguessable 32-hex handle for share links. Unlisted routes are only reachable anonymously via this token.
user*createdAt*stringupdatedAt*stringcurl -X POST 'https://api.routess.com/routes' \ -H 'Content-Type: application/json' \ -d '{ "name": "Morning Jog Route", "waypoints": [ { "coord": [ -74.006, 40.7128 ], "type": "routed", "timestamp": "2024-01-15T10:00:00Z" }, { "coord": [ -73.9851, 40.7589 ], "type": "direct", "timestamp": "2024-01-15T10:30:00Z" } ]}'{ "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 all user routes
Retrieves the authenticated user's routes (any visibility), newest first. Paginated via `limit` and `offset`; the total number of routes is returned in the `X-Total-Count` response header.
List public routes
Anonymous public route listing behind two gates. gate=indexable (default): Routes clearing the Indexable quality gate (see CONTEXT.md), newest-updated first; feeds the landing sitemap. gate=public: every public Route, newest-published first with downsampled geometry; the in-app Discover surface. Filterable by bbox (viewport overlap), activity, placeCity, and distance bounds. Total count in X-Total-Count.