# Tredict API: Activities

This document covers reading, uploading, updating, and downloading activities. It assumes that authentication is already set up (see `setup.md`), regardless of whether you use a Personal Access Token or an OAuth2 application.

An activity in Tredict represents a completed training session. It carries summary metrics (distance, duration, average heart rate, etc.), optional sampled time series (per-second data points), assigned equipment, and the original device file.

## Required Scopes

- `activityRead` for listing, fetching details, and downloading files.
- `activityWrite` for uploading new activities and updating existing ones.

## Listing Activities

```
GET https://www.tredict.com/api/oauth/v2/activityList
```

**Parameters:**

- `startDate` (optional, ISO-8601): the newest activity to include. If omitted, the list starts at the most recent activity.
- `pageSize` (optional, 50 to 1000, default 500): number of activities per page.
- `extendedSummary` (optional, set to `1`): include aggregated metrics like average pace, heart rate, power, and cadence on each entry.

**Response shape:**

```json
{
  "activities": [
    {
      "id": "3F321GQqJjViDBnJNnSCrh",
      "date": "2026-04-25T07:14:00Z",
      "sportType": "running",
      "subSportType": "street",
      "title": "Easy morning run",
      "summary": { ... }
    }
  ],
  "links": {
    "self": "https://www.tredict.com/api/oauth/v2/activityList?...",
    "next": "https://www.tredict.com/api/oauth/v2/activityList?..."
  }
}
```

The list is ordered newest first. To get older activities, follow the `next` link until it is null. Do not assume one page covers the period you need.

**With `extendedSummary=1`** the `summary` object contains additional aggregated values, including effort. Without it, the entry is leaner and faster to fetch in bulk.

## Activity Details

```
GET https://www.tredict.com/api/oauth/v2/activity/{activityId}
```

Returns the full activity, including:

- `summary`: aggregated metrics for the whole activity.
- `seriesSampled`: time series of per-point measurements (latitude, longitude, speed, altitude, heart rate, cadence, power, etc.). Not every key is present in every activity, only what the device recorded.
- `equipment`: array of assigned equipment objects (shoes, bikes, etc.) with their own usage metrics.

**Possible keys in `summary`:**
`durationTotal`, `duration`, `distance`, `altitude`, `positionLat`, `positionLong`, `walkingDuration`, `calories`, `speed`, `speedMax`, `heartrate`, `heartrateMax`, `respirationRate`, `respirationRateMax`, `power`, `powerMax`, `pace`, `paceMax`, `cadence`, `cadenceMax`, `temperature`, `strokes`, `poolLength`.

**Possible keys in `seriesSampled`:**
`positionLat`, `positionLong`, `speed`, `distance`, `altitude`, `heartrate`, `cadence`, `power`, `respirationRate`, `temperature`.

`pace` values are seconds per kilometer (e.g. 240 = 4:00/km).

For most consumer use cases, the activity list with `extendedSummary=1` already provides what you need. Fetch the full detail only when you need the time series or equipment breakdown.

## Updating an Activity

```
POST https://www.tredict.com/api/oauth/v2/activity/update/{activityId}
```

**Body:**

```json
{
  "training": {
    "title": "New title",
    "notes": "Felt strong, no niggles"
  }
}
```

Only `title` and `notes` can be updated through this endpoint. Other fields like distance, sport type, or equipment assignment cannot be changed via the API.

## Downloading the Original File

```
GET https://www.tredict.com/api/oauth/v2/activity/file/{activityId}
```

Returns the raw binary `.fit` or `.tcx` file as `application/octet-stream`. The filename is in the `Content-Disposition` header. The file extension depends on the original source: Garmin usually produces `.fit`, some platforms produce `.tcx`.

This is the file as Tredict received it from the source platform. It is suitable for re-importing into other tools or for archival.

## Uploading an Activity

```
POST https://www.tredict.com/api/oauth/v2/activity/upload
```

**Content-Type:** `multipart/form-data`

**Form fields:**

- `file` (required): the activity file. Supported formats are `.fit` and `.tcx`.
- `name` (optional): a workout name, e.g. "Morning Run".
- `notes` (optional, max 1024 characters): a workout description.

**Success response:**

```json
{
  "success": [
    { "date": "2026-04-26T07:14:00Z", "trainingId": "3F321GQqJjViDBnJNnSCrh" }
  ]
}
```

**Error responses:**

```json
{ "error": "ERROR_TYPE", "meta": [ ... ] }
```

Common error types:

- `FILE_EXISTS`: an activity with the same content is already in Tredict (e.g. Garmin already pushed it).
- `FILE_EXTENSION_UNSUPPORTED`: only `.fit` and `.tcx` are accepted.
- `SPORT_TYPE_UNSUPPORTED`: the sport type recorded in the file cannot be mapped to a Tredict sport type.

**Rate limits:** 8 uploads per second, 10 downloads per second. Add a small delay if you batch-process many files.

## Pace and Other Unit Conventions

This trips up most new users at least once.

- **Pace**: seconds per kilometer. 4:00/km is `240`, not `4.0` or `4.00`. Convert to a string with `floor(pace / 60) + ":" + pad2(pace % 60)`.
- **Distance**: meters. 5 km is `5000`.
- **Duration**: seconds. 1 hour is `3600`.
- **Heart rate**: BPM.
- **Power**: watts.
- **Cadence**: steps per minute for running, revolutions per minute for cycling.
- **Speed**: meters per second.

These conventions apply both in summary fields and in time series points.

## Equipment in Activities

If activities have equipment assigned (shoes, bike, etc.), the equipment objects are included in the activity detail response. Each equipment entry has its own aggregated usage metrics computed from all activities it was assigned to.

To see all equipment, regardless of a single activity, use `GET /equipmentList` (covered in `recipes.md`, recipe 3).

Equipment cannot be assigned or unassigned via the API. This is done in the Tredict web interface.