Terra Routes

Terra API Routes

Terra API Routes is a write-to-device product (pre-release): define a GPS route once with waypoints, and Terra API pushes it to your users' connected devices for on-device navigation. The route appears on the watch or bike computer after the user's next device sync, so your app never has to speak each provider's native route format.

From the terminal

Account configuration lives in the Terra dashboard, which an agent cannot click. The terra CLI does the same from a terminal. Routes is pre-release, so it has no generated commands and no endpoints in the description the CLI pins. That matters in a specific way: terra data-api checks a path against that description before sending, so a routes path is rejected locally as a typo unless you say otherwise.

terra api list --data-api                          # what the pinned description does cover
terra data-api /routes -X POST --body-file route.json --no-verify

--no-verify sends the path exactly as typed, which is what an endpoint newer than the pin needs. Everything else still applies: --dry-run to see the request, -i for the status line, --jq to filter the response.

The account configuration around Routes does have commands. terra unified-api sources list --env <dev-id> says which of the devices below are enabled, and terra users list --env <dev-id> --provider GARMIN says whether a user is connected to push a course to.

Install it with brew install tryterra/tap/terra on macOS or npm install -g @tryterra/cli elsewhere. The terra-cli skill carries the guardrails (--reveal on anything returning a credential, --yes on anything destructive), the exit codes, and a playbook per task. It administers the integration; it does not replace the API calls this skill describes.

Only Garmin, COROS, and Wahoo are supported. Feature coverage differs sharply between them (see the provider matrix below), so design routes for the lowest common denominator unless you know every user is on Garmin.

Two-Phase Workflow

Routes always take two steps: create a reusable template, then push that template to one or more users.

Phase 1  POST /routes                          -> route_id           (create template once)
Phase 2  POST /routes/{route_id}/push?user_id=X -> pushed_route_id    (push to a user's device)
                                                    provider_route_id

The route reaches the device on the user's next sync. Base URL is https://access.tryterra.co/api/v2. Every request needs two headers: dev-id and x-api-key.

curl -X POST "https://access.tryterra.co/api/v2/routes" \
  -H "Content-Type: application/json" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "name": "Morning Run Loop",
    "sport": "running",
    "waypoints": [
      { "latitude": 51.5074, "longitude": -0.1278 },
      { "latitude": 51.5150, "longitude": -0.1200 }
    ]
  }'
# -> { "status": "success", "route_id": "295581149349019648" }

curl -X POST "https://access.tryterra.co/api/v2/routes/295581149349019648/push?user_id=USER_ID" \
  -H "dev-id: YOUR_DEV_ID" \
  -H "x-api-key: YOUR_API_KEY"
# -> { "status": "success", "pushed_route_id": "...", "provider_route_id": "..." }

Endpoints

Update semantics. PUT /routes/{id} behaves like a patch and returns 200: every field is optional and only the fields you provide are updated (waypoints, speed_meters_per_second, and elevation as well as name, description, and sport). It does not touch already-pushed devices. Add ?cascade to also re-push the updated route to every device it was sent to; this runs asynchronously and returns 202 Accepted. Cascade is fire-and-forget: re-push failures are only logged server-side, never surfaced in the response or in GET /pushedRoutes, so a partial failure is invisible to the API. To confirm a device actually received the update, re-push to that user explicitly or verify out of band on the device.

Data Model

RouteTemplate

Waypoint

course_point is { "type": ..., "name": ... }. The API schema contains 15 types: generic, summit, valley, water, food, danger, first_aid, sprint, segment_start, segment_end, left, right, straight, left_fork, right_fork. Garmin support is documented for the first 10 (the POI types) only; do not rely on the five turn-direction types unless verified against current provider behavior (see Gotchas).

Sports (8): running, trail_running, hiking, cycling, road_biking, mountain_biking, gravel_cycling, other. cycling is distinct from road_biking but maps to ROAD_CYCLING on Garmin.

Validation (hard 400 on create and update): name non-empty, max 255 chars; description max 2,000 chars; sport valid; 2 to 10,000 waypoints; latitude in -90..90; longitude in -180..180; elevation_meters in -500..9000; speed_meters_per_second > 0.

Provider Matrix

All three support re-sync. COROS has no in-place update, so a re-sync re-POSTs a fresh GPX file while the provider_route_id stays stable. Delete works on Garmin and Wahoo only.

Gotchas

• Garmin-only fields fail silently elsewhere. course_point, speed_meters_per_second, and description are honored on Garmin but silently ignored by COROS and Wahoo. Do not depend on them unless every target user is on Garmin.
• Garmin elevation is all-or-nothing per route. If some waypoints carry elevation_meters and others do not, Terra API drops all elevation values and lets Garmin's own elevation model fill them in. Supply elevation on every waypoint or none.
• Course-point failures happen at different stages. An invalid type string fails at POST /routes with 400 (creation-time enum validation). The five turn-direction types (left, right, straight, left_fork, right_fork) pass creation-time validation but are not among the 10 documented Garmin course-point types – how the push handles them is not guaranteed (it may error or drop them), so stick to the 10 Garmin-supported POI types unless you have verified current behavior.
• COROS is the most limited provider. No delete (a delete only removes the record from Terra API's database; the route stays on the device), no retrieve, and it collapses all sports into two internal types (run and cycle), so the device display may not distinguish, say, gravel cycling from road biking.
• Pushing the same template repeatedly creates duplicate pushed routes. Each push is a new pushed route; there is no dedup. Track pushed_route_id values yourself if you need to avoid duplicates on a device.
• Elevation is auto-computed when absent, and the exact handling is provider-dependent.
• Unsupported operations still return success. A delete against COROS, for example, returns a success response even though the route remains on the device.

References

• references/provider-details.md – per-provider behavior: Garmin PUT-then-POST re-sync and elevation normalization, Wahoo stable terra-{pushed_route_id} external ID and granular sport mapping, COROS unique-GPX-per-push and provider_route_id meaning. Read when a route behaves differently across devices or you are debugging a re-sync or delete.

For full payload examples beyond the one above (trail running with course points, road biking with a speed target, the minimal 2-waypoint route), fetch the live page: https://docs.tryterra.co/routes-api-pre-release/sport-specific-examples.md

Full docs: Routes API overview, introduction, core concepts, provider compatibility. If the terra-docs MCP server (https://docs.tryterra.co/~gitbook/mcp) is connected, use its tools to search and fetch the docs instead.

Note: the Routes docs space is pre-release and may not be published yet. If a page above returns "Page Not Found", rely on this skill's bundled references and verify against the live API.