# API

The Split's anonymous HTTP API: the same merge, crop, split and export operations as the site, for scripts and agents. No key, no account.

Canonical: https://thesplit.fit/api
Last updated: 2026-11-15

Everything the website does to an activity file, merge, crop, split, concatenate, heart-rate repair and the rest, is also available as a plain HTTP API that returns JSON, for scripts and AI agents. There is no key and no account: you call it anonymously, and it runs the same operations as the site.

The base address is <https://thesplit.fit/api/v1>. Anything under that prefix is a stable contract; the other routes the website itself uses can change without notice.

Try the calls in your browser on the interactive documentation (/api/v1/docs), or read the machine-readable OpenAPI description (/api/v1/openapi.json), which is the full list of calls, fields and errors.

## Quickstart

These scripts upload a file, look at it, keep its first ten minutes, download the result and clean up. Pick the language you work in; the steps are the same in each.

Upload a FIT, TCX or GPX file as a multipart form field named file. The answer holds the activity id every other call needs.

Read the summary: sport, start time, duration, distance and which data streams the file carries.

Crop to the first ten minutes. The result is staged as a new activity with its own id; the original is not changed.

Export the cropped activity as fit, tcx or gpx. Exporting does not delete it.

Delete the original and the cropped copy. The Python and TypeScript versions do this in a finally block, so it happens even when an earlier step fails, and they wait out a 429 using its Retry-After header.

### curl

Needs curl and jq. Save as quickstart.sh next to ride.fit and run it with bash quickstart.sh.

```bash
BASE=https://thesplit.fit/api/v1

# 1. Upload
ID=$(curl -s -F "file=@ride.fit" $BASE/activities | jq -r .activityId)

# 2. Summary (and the start time in epoch milliseconds, for the crop)
curl -s $BASE/activities/$ID
START=$(curl -s $BASE/activities/$ID | jq -r '.startedAt | sub("[.][0-9]+"; "") | fromdate * 1000')

# 3. Crop to the first ten minutes
END=$((START + 600000))
NEW=$(curl -s -X POST -H "Content-Type: application/json" -d '{"unit":"time","startMs":'$START',"endMs":'$END'}' $BASE/activities/$ID/crop | jq -r .activityId)

# 4. Export
curl -s -o cropped.fit "$BASE/activities/$NEW/export?format=fit"

# 5. Delete both
curl -s -X DELETE $BASE/activities/$ID
curl -s -X DELETE $BASE/activities/$NEW
```

### Python

Needs Python 3.11 or newer and requests (pip install requests). Save as quickstart.py next to ride.fit and run python quickstart.py.

```python
import time
from datetime import datetime

import requests

BASE = "https://thesplit.fit/api/v1"


def call(method, path, **kwargs):
    """Send a request; on 429, wait as long as Retry-After says and try once more."""
    response = requests.request(method, BASE + path, **kwargs)
    if response.status_code == 429:
        time.sleep(int(response.headers.get("Retry-After", "5")))
        response = requests.request(method, BASE + path, **kwargs)
    response.raise_for_status()
    return response


ids = []
try:
    # 1. Upload
    with open("ride.fit", "rb") as f:
        upload = call("POST", "/activities", files={"file": ("ride.fit", f.read())}).json()
    ids.append(upload["activityId"])

    # 2. Summary
    summary = call("GET", f"/activities/{ids[0]}").json()
    print(summary["sport"], summary["durationSec"], summary["streams"])

    # 3. Crop to the first ten minutes
    start_ms = int(datetime.fromisoformat(summary["startedAt"].replace("Z", "+00:00")).timestamp() * 1000)
    body = {"unit": "time", "startMs": start_ms, "endMs": start_ms + 600_000}
    cropped = call("POST", f"/activities/{ids[0]}/crop", json=body).json()
    ids.append(cropped["activityId"])

    # 4. Export
    exported = call("GET", f"/activities/{ids[1]}/export", params={"format": "fit"})
    with open("cropped.fit", "wb") as f:
        f.write(exported.content)
finally:
    # 5. Delete both, even if a step above failed
    for activity_id in ids:
        requests.delete(f"{BASE}/activities/{activity_id}")
```

### TypeScript

Needs Node 24 or newer and no packages. Save as quickstart.ts next to ride.fit and run node quickstart.ts.

```typescript
import { readFile, writeFile } from "node:fs/promises";

const BASE = "https://thesplit.fit/api/v1";

// Send a request; on 429, wait as long as Retry-After says and try once more.
async function call(method: string, path: string, init: RequestInit = {}): Promise<Response> {
  let response = await fetch(BASE + path, { method, ...init });
  if (response.status === 429) {
    const seconds = Number(response.headers.get("Retry-After") ?? "5");
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
    response = await fetch(BASE + path, { method, ...init });
  }
  if (!response.ok) throw new Error(`${method} ${path} failed: ${response.status} ${await response.text()}`);
  return response;
}

const ids: string[] = [];
try {
  // 1. Upload
  const form = new FormData();
  form.append("file", new Blob([await readFile("ride.fit")]), "ride.fit");
  const upload = await (await call("POST", "/activities", { body: form })).json();
  ids.push(upload.activityId);

  // 2. Summary
  const summary = await (await call("GET", `/activities/${ids[0]}`)).json();
  console.log(summary.sport, summary.durationSec, summary.streams);

  // 3. Crop to the first ten minutes
  const startMs = Date.parse(summary.startedAt);
  const crop = { unit: "time", startMs, endMs: startMs + 600_000 };
  const cropped = await (
    await call("POST", `/activities/${ids[0]}/crop`, {
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(crop),
    })
  ).json();
  ids.push(cropped.activityId);

  // 4. Export
  const exported = await call("GET", `/activities/${ids[1]}/export?format=fit`);
  await writeFile("cropped.fit", Buffer.from(await exported.arrayBuffer()));
} finally {
  // 5. Delete both, even if a step above failed
  for (const id of ids) await fetch(`${BASE}/activities/${id}`, { method: "DELETE" });
}
```

Calls that create a new activity (upload, crop, split and the other operations that stage a result) answer with a new activity id; split answers with two. Calls that only read, such as the summary, the data series and export, return data and create nothing.

## How long files live

Files are held in the server's memory only and are never written to disk. Every answer about a live activity includes an expiresAt time (in epoch milliseconds); export carries it in the X-Activity-Expires-At header instead. An activity expires 30 minutes after you last used it, and in any case 2 hours after it was created. Please delete each activity you no longer need, including the in-between results, with a DELETE call as in step 5.

## MCP and workflows

For a whole job rather than one operation there are four workflows: clean up wrong data in a recording (heart-rate spikes, an idle start or end), combine two recordings of one workout, fix a multisport file, and join the pieces of a workout your watch stopped and restarted. You call a workflow to analyze your files: it proposes numbered steps with a plain-English reason for each, and changes nothing. Show the steps to the person who owns the files; only the steps they confirm are applied, in a second call, and the result is a new activity with download links and a before and after comparison. Your uploaded files are never changed.

The same four workflows, and four basic tools (upload, summary, export and delete), are available to AI assistants as a hosted MCP server at <https://thesplit.fit/mcp>, with no key and no account: add that address as a remote MCP server in your assistant. The workflows are also plain HTTP calls under /api/v1/workflows, described in the OpenAPI description. They have been checked on a limited set of device combinations; other combinations have not been tested, so look at the result.

## Limits

Uploads can be up to 15 MB. Each address can hold up to 12 activities at once, and uploads and operation results both count; past that, the oldest result is dropped first, and a later call using its id answers 404. Calls are also rate limited per address: an over-limit call answers 429, and its Retry-After header says how many seconds to wait before trying again. If the service is full it answers 503 with the same header.

Errors always have the same shape: a JSON object with an error that holds a code and a message. For how the site treats your files, see Privacy.
