Skip to content

The API for agents

Coding agents can read the whole API in one file, and AI assistants can call it through an MCP server. Both are generated from the same verified OpenAPI as the reference, so they stay in step with it.

Read: llms.txt

  • /api/llms.txt: what the API does, the basics (hosts, keys, coordinate order, units, errors, attribution) and a link to every operation.
  • /api/llms-full.txt: every operation in one file, with its parameters, request and response fields, a working curl request and its errors.

Point a coding agent at https://trailsplits.com/api/llms-full.txt and ask for what you want to build; the quickstart and the TypeScript client help it start.

Call: the MCP server

https://trailsplits.com/api/mcp speaks the Model Context Protocol over Streamable HTTP. It has 27 tools, one per operation, all read-only. Calls need your key, from the API console (free, 30,000 credits a month); they count against your project like any other call. Listing the tools needs no key.

Claude Code

Add the server
claude mcp add --transport http trailsplits https://trailsplits.com/api/mcp \
  --header "Authorization: Bearer $TRAILSPLITS_API_KEY"

Other clients (Claude Desktop, Cursor, VS Code…)

Most take a JSON entry like this; where a client cannot send headers, use it through a local MCP proxy that can.

MCP configuration
{
  "mcpServers": {
    "trailsplits": {
      "type": "http",
      "url": "https://trailsplits.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ts_live_…"
      }
    }
  }
}

By hand

One tool call with curl
curl -sS https://trailsplits.com/api/mcp -H 'Content-Type: application/json' -H "Authorization: Bearer $TRAILSPLITS_API_KEY" \
  --data '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"roundtrips","arguments":{"start":[7.7491,46.0207],"distance_km":8}}}'

Answers come back as the API's JSON, with the credits left this month. A static map comes back as an image.

From two places to a brief and a best day

  1. waypoint-route with waypoints as [lon, lat] and profile: "hike": a route on signed trails, with its geometry (a GeoJSON LineString).
  2. route-brief with that geometry (add a departure with its offset for the weather along it): climb, time, surfaces and grades, water, huts and stops, snow and fires, in one answer.
  3. route-windows with the same geometry, from_date and days: the start times ordered by your preferences, each saying why.

The same geometry goes to route-places, route-exits, route-slopes and route-card. A route brief is a large answer: quote its parts (analysis, places, weather), not all of it.

Tools

ToolWhat it does
elevationTerrain pixel sampling
route-analysisAnalyse a route you already have
roundtripsRound trips from a start point
route-weatherWeather along a route at arrival time
elevation-profileElevation profile of a line
waypoint-routeRoute through waypoints
route-exitsExits along a route
outingsDay outings near a point
time-model-fitYour own walking pace (time model)
route-cardRoute card to print
route-windowsGo windows: which day and start time
route-slopesSlope at the path (experimental)
route-briefRoute brief
route-placesPlaces along a route
pace-planPace plan for a course
gpx-cleanClean a GPX file
gpx-simplifySimplify a GPX file or line
searchPlace search
reversePlaces near a point
trailsTrail search
trails-bboxTrails in an area
trail-relationA trail relation’s line
poisOutdoor places in an area
static-mapStatic map image
trace-attributesMap matching and trace attributes
snowSnow along a route
routeOutdoor point-to-point route

Map tiles, styles and terrain are not tools: a map client loads them directly (recipe). Weather forecasts are reached through route-weather.