KYRO Hackathon API

Build whatever you want with running data — your own, your friends', and the entire KYRO community (fully anonymized).

Get my token →How it works

What you can access

🏃

Your own runs (full detail)

Every run you've recorded on KYRO — GPS track, per-km splits with pace and elevation, distance, duration, calories, territory captured/stolen, location metadata, titles and notes.

👥

Friends' public runs

Runs from people you follow, filtered by each run's audience rule (public / follower / mutual_friend) — exactly what you'd see in the KYRO app.

🌍

KYRO-wide anonymized data

90-day activity histograms (hour, day-of-week, distance, pace), region distribution, anonymous user demographics (share-only, k≥5), plus a fully k-anonymized GPS trace dataset for spatial analysis.

Get started

  1. Install KYRO on your phone and sign up.
  2. Open the app → My Page → Settings → set your default run audience to Public (so other participants can include your runs in their friend feeds).
  3. Follow the other event participants in the KYRO app, and record at least one warm-up run (10 minutes is enough).
  4. Get the event passcode from the organizer (shared at the venue).
  5. Click Get my token, pick your KYRO sign-in method, paste the passcode — done.

Token reveal is one-time only. Copy it immediately. If you lose it, ask the organizer to revoke + reissue.

Endpoints

All endpoints use Authorization: Bearer kyro_pat_… and return JSON.

PathDescription
GET/api/v1/runs?limit=50&cursor=…Your own runs (most recent first). Cursor = ISO timestamp of last seen run.
GET/api/v1/runs/:idSingle run with full GPS track (GeoJSON LineString) and per-km splits.
GET/api/v1/friends/runs?limit=50&cursor=…Runs from KYRO users you follow, filtered by each run's audience rule.
GET/api/v1/aggregatesKYRO-wide anonymous activity histograms (last 90 days). No PII.
GET/api/v1/anon-traces?limit=100&region=SingaporeK-anonymized GPS trace dataset. Endpoints clipped, coordinates grid-rounded, k≥3 by hour+region.
GET/api/v1/demographicsAnonymous gender + age band distribution (share only, k≥5).
POST/api/mcpMCP transport — point Claude Desktop / Cursor here for natural-language access.

Code examples

cURL

TOKEN=kyro_pat_xxxxxxxxxx
BASE=https://hackathon.kyro.team

# Your runs
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/runs?limit=10"

# A specific run (with GPS trace + splits)
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/runs/01HX..."

# KYRO-wide aggregates
curl -H "Authorization: Bearer $TOKEN" "$BASE/api/v1/aggregates"

# Anonymized trace dataset (good for ML / route discovery)
curl -H "Authorization: Bearer $TOKEN" \
  "$BASE/api/v1/anon-traces?limit=50&region=Singapore"

Python

import requests

TOKEN = "kyro_pat_xxxxxxxxxx"
BASE  = "https://hackathon.kyro.team"
H     = {"Authorization": f"Bearer {TOKEN}"}

# Recent runs
runs = requests.get(f"{BASE}/api/v1/runs?limit=20", headers=H).json()["runs"]
print(f"You have {len(runs)} recent runs")

# Pull pace + elevation per km for your most recent run
detail = requests.get(f"{BASE}/api/v1/runs/{runs[0]['id']}", headers=H).json()
for s in detail["splits"]:
    print(f"km {s['split_index']:>2}  "
          f"pace {s['avg_pace_s_km']:>4}s/km  "
          f"+{s['elevation_gain_m']}m / -{s['elevation_loss_m']}m")

JavaScript / TypeScript

const TOKEN = "kyro_pat_xxxxxxxxxx";
const BASE  = "https://hackathon.kyro.team";

const headers = { Authorization: `Bearer ${TOKEN}` };

// Anonymized trace dataset for spatial analysis
const traces = await fetch(
  `${BASE}/api/v1/anon-traces?limit=100&region=Singapore`,
  { headers },
).then(r => r.json());

for (const t of traces.traces) {
  console.log(t.place_region_label, t.distance_m_binned, t.simplified_line_clipped_grid);
}

Claude Desktop / Cursor — natural language

Save this to your MCP config — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\\Claude\\claude_desktop_config.json. Restart Claude Desktop after.

{
  "mcpServers": {
    "kyro": {
      "url": "https://hackathon.kyro.team/api/mcp",
      "headers": {
        "Authorization": "Bearer kyro_pat_xxxxxxxxxx"
      }
    }
  }
}

Then talk to it in plain English: "Analyze my pace trends from the last month", "What time of day is most popular for KYRO runners in Singapore?", "Find the most-repeated routes near Marina Bay."

MCP tools (what Claude can call)

Tool nameWhat it does
list_my_runsYour own runs (most recent first). No GPS trace — pair with get_run_detail.
get_run_detailFull detail of one run: GPS trace (GeoJSON) + per-km splits (pace, elevation).
list_friend_runsRuns from people you follow, audience-filtered (public / follower / mutual_friend).
get_aggregate_statsKYRO-wide activity histograms over the last 90 days (hour, day-of-week, distance, pace, region).
list_anon_tracesK-anonymized GPS trace dataset (k≥3 by hour+region). Good for route discovery / clustering.
get_demographicsAnonymous gender + age band distribution. Share-only, no totals exposed (k≥5).

Build something cool

AI running coach

Feed a few weeks of your runs to Claude/GPT. Ask it to find pacing patterns, suggest workouts, flag overreaching weeks.

Popular route discovery

Cluster the anonymized trace dataset by start-grid + bearing. Find the most-run loops in any region.

Beginner course recommender

Filter anonymized traces by distance < 5km, low elevation, high repetition. Surface starter-friendly routes near you.

Pace-drop heatmap

Use per-km splits across many runs to find where runners consistently slow down. Hills? Traffic? Elevation? Map it.

Trace pattern clustering

Train a small ML model on simplified geometries — out-and-back vs loop vs grid. What archetypes exist?

Run-to-music generator

Map elevation profile to melody, pace to tempo. Turn your run into a song.

Territory strategy game

Use friends' runs + your own to predict where to run next for maximum territory capture.

Anything else

Show us. The data is yours for the day.

Rules + privacy

Need help?

Ready to build?

Get my token →