# Tredict API - Comprehensive LLM System Description

## Overview
This document provides a comprehensive description of the Tredict API for Large Language Models (LLMs) to understand and interact with the Tredict OAuth2 system and endpoints.

## Authentication Flow

Tredict supports two authentication methods:

### 1. OAuth2 Authorization (for applications)
- **Authorization URL**: `https://www.tredict.com/authorization/`
- **Token URL**: `https://www.tredict.com/user/oauth/v2/token`
- **Supported Flows**: Standard OAuth2 and OAuth2.1 with PKCE
- **Use Case**: Applications accessing data for multiple users

### 2. Personal API (for individual users)
- **Access**: Generate personal tokens via Tredict web interface (Settings -> Personal API)
- **Authentication**: Bearer token in Authorization header
- **Use Case**: Individual users accessing their own data

## OAuth2 Authorization

### Required Parameters for Authorization Request
- `client_id`: Your client ID (required)
- `state`: Optional URL-encoded state for CSRF protection
- `redirect_uri`: Optional override for default callback URL
- `code_challenge`: Optional for PKCE flow
- `code_challenge_method`: Must be "S256" for PKCE

### PKCE (Proof Key for Code Exchange) Flow
PKCE is recommended for public clients and provides enhanced security:

1. **Code Verifier Generation**:
   - Generate a random code verifier (32-96 characters)
   - Example: `code_verifier = base64url_encode(random_bytes(32))`

2. **Code Challenge Creation**:
   - Transform code verifier using SHA-256
   - Example: `code_challenge = base64url_encode(sha256(code_verifier))`

3. **Authorization Request**:
   - Include `code_challenge` and `code_challenge_method="S256"`

4. **Token Request**:
   - Include `code_verifier` when exchanging authorization code for tokens

5. **Refresh Token Rotation**:
   - Each refresh token request with PKCE invalidates the old refresh token
   - A new refresh token is returned with each access token refresh

### Token Request Examples

**Standard Flow (without PKCE):**
```
POST /user/oauth/v2/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE
```

**PKCE Flow:**
```
POST /user/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=AUTH_CODE&code_verifier=CODE_VERIFIER&client_id=CLIENT_ID
```

**Refresh Token Flow:**
```
POST /user/oauth/v2/token
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=REFRESH_TOKEN
```

**PKCE Refresh Token Flow (with token rotation):**
```
POST /user/oauth/v2/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=REFRESH_TOKEN&client_id=CLIENT_ID
```

### Token Request
- **Method**: POST
- **Headers**: 
  - `Authorization`: Basic auth with client_id:client_secret (or omit for PKCE)
  - `Content-Type`: application/x-www-form-urlencoded
- **Parameters**:
  - `grant_type`: "authorization_code" or "refresh_token"
  - `code`: Authorization code (for authorization_code grant)
  - `refresh_token`: Refresh token (for refresh_token grant)
  - `code_verifier`: Required for PKCE (only with authorization_code grant)
  - `client_id`: Required for PKCE (only with authorization_code grant)

### Refresh Token Behavior
- **Initial Refresh Token**: Returned when `grant_type` is "authorization_code"
- **PKCE Refresh Behavior**: When using PKCE, each refresh token request invalidates the old refresh token and returns a new one
- **Non-PKCE Behavior**: Refresh token remains the same across multiple uses
- **Security**: PKCE provides enhanced security by rotating refresh tokens

### Token Response
- **access_token**: Bearer token (valid for 2 days)
- **expires_at**: Token lifetime in seconds (not Unix timestamp)
- **refresh_token**: Long-lived token (returned with initial authorization_code grant or PKCE refresh)
  - `client_id`: Required for PKCE

## Personal API

The Tredict Personal API provides an alternative authentication method for individual users to access their own data without requiring full OAuth2 application registration.

### Personal API Overview

- **Purpose**: Designed for individual users to access their personal Tredict data
- **Authentication**: Uses personal access tokens generated via Tredict web interface
- **Endpoints**: Same endpoints as OAuth2 API
- **Use Cases**: Personal scripts, custom integrations, personal applications

### Personal API Authentication

Personal access tokens are used as bearer tokens:

```
Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN
```

### Personal API vs OAuth2 API

| Feature | Personal API | OAuth2 API |
|---------|-------------|-----------|
| Target Users | Individual users | Developers for multiple users |
| Registration | None (via settings) | Required (apply to Tredict) |
| Token Management | Automatic (web interface) | Manual (application flow) |
| Multi-User | No (personal data only) | Yes |
| Scopes | Full access to your data | Configurable per application |
| Token Lifetime | Auto-deactivated after 2 weeks inactivity | Long-lived refresh tokens |
| Reactivation | Automatic on web visit | Manual refresh |

### When to Use Personal API

- **Personal projects**: Scripts for your own data analysis
- **Custom integrations**: Personal workout uploaders or data processors
- **Testing**: Quick API testing without full OAuth2 setup
- **Single-user tools**: Applications only you will use

### When to Use OAuth2 API

- **Multi-user applications**: Apps used by multiple Tredict users
- **Production applications**: Publicly available services
- **Commercial integrations**: Platforms connecting to Tredict
- **Enhanced security**: Applications requiring configurable scopes

## API Endpoints

### Activity Endpoints

#### Activity List
- **URL**: `GET https://www.tredict.com/api/oauth/v2/activityList`
- **Scope**: activityRead
- **Parameters**:
  - `startDate`: Optional start date (ISO format)
  - `pageSize`: Optional page size (50-1000, default 500)
  - `extendedSummary`: Optional (set to 1 for extended activity metrics)
- **Response**: Paginated list of activities with self and next links
- **Extended Summary**: When `extendedSummary=1`, includes additional metrics like pace, speed, heartrate, power, cadence, etc.

#### Activity Details
- **URL**: `GET https://www.tredict.com/api/oauth/v2/activity/${activityId}`
- **Scope**: activityRead
- **Response**: Complete activity data including summary and time series

#### Activity Update
- **URL**: `POST https://www.tredict.com/api/oauth/v2/activity/update/${activityId}`
- **Scope**: activityWrite
- **Body**: `{ "training": { "title": "...", "notes": "..." } }`

#### Activity File Upload
- **URL**: `POST https://www.tredict.com/api/oauth/v2/activity/upload`
- **Scope**: activityWrite
- **Content-Type**: multipart/form-data
- **Supported Formats**: .fit, .tcx

**Request Form Data Fields:**
- `file`: The activity file (required)
  - `Content-Disposition`: `form-data; name="file"; filename="activity.fit"`
- `name`: Optional workout name (e.g., "Morning Run")
  - `Content-Disposition`: `form-data; name="name"`
- `notes`: Optional workout description (max 1024 characters)
  - `Content-Disposition`: `form-data; name="notes"`

**Response Formats:**
- **Success (200)**: `{ "success": [{ "date": "ISO_DATE", "trainingId": "ID" }] }`
- **Error**: `{ "error": "ERROR_TYPE", "meta": [...] }`
  - Possible errors: FILE_EXISTS, FILE_EXTENSION_UNSUPPORTED, SPORT_TYPE_UNSUPPORTED

### Planned Training Endpoints

#### Planned Training List
- **URL**: `GET https://www.tredict.com/api/oauth/v2/plannedTrainingList`
- **Scope**: activityRead
- **Parameters**:
  - `startDate`: Optional start date
  - `endDate`: Optional end date
  - `sportType`: Optional filter (running, cycling, swimming, misc)

#### Planned Training Details
- **URL**: `GET https://www.tredict.com/api/oauth/v2/plannedTraining/file/json/${trainingId}`
- **Scope**: activityRead
- **Parameters**:
  - `language`: Optional (en, de)
  - `extraValues`: Optional (1 to include Tredict-specific values)

### Health and Body Data Endpoints

#### Body Values
- **URL**: `GET https://www.tredict.com/api/oauth/v2/bodyvalues`
- **Scope**: bodyvaluesRead
- **Response**: Array of body value revisions with timestamps

#### Body Values Upload
- **URL**: `POST https://www.tredict.com/api/oauth/v2/bodyvalues`
- **Scope**: bodyvaluesWrite
- **Body**: `{ "bodyvalues": [...] }`

#### Capacity Values
- **URL**: `GET https://www.tredict.com/api/oauth/v2/capacity`
- **Scope**: bodyvaluesRead
- **Parameters**: `sportType` (optional filter)

#### HRV Data
- **URL**: `GET https://www.tredict.com/api/oauth/v2/hrv`
- **Scope**: bodyvaluesRead
- **Parameters**: `startDate`, `endDate` (optional)

#### Sleep Data
- **URL**: `GET https://www.tredict.com/api/oauth/v2/sleep`
- **Scope**: bodyvaluesRead
- **Parameters**: `startDate`, `endDate` (optional)

### Training Plan Endpoints

#### Plan Creation
- **URL**: `POST https://www.tredict.com/api/oauth/v2/plan`
- **Scope**: activityWrite
- **Body Structure**:
```json
{
  "plan": {
    "title": "string (5-255 chars)",
    "description": "string (10-10240 chars)",
    "categories": ["general", "base", "building", "intensity", "race_specific", "race_phase", "recovery", "special"],
    "targetgroups": ["general", "beginner", "intermediate", "profi"],
    "zonetypes": ["heartrate", "power", "pace"],
    "language": "de" or "en"
  },
  "planTrainings": [
    {
      "day": 1-1024,
      "time": 0-1449, // minutes from midnight
      "structuredWorkout": {
        // Either note workout or planned workout
      }
    }
  ]
}
```

#### Add Plan Training
- **URL**: `POST https://www.tredict.com/api/oauth/v2/plan/training`
- **Scope**: activityWrite
- **Body**: `{ "planId": "...", "planTraining": { ... } }`
- **planTraining structure**: Same as in Plan Creation

### Other Endpoints

#### Training Efforts
- **URL**: `GET https://www.tredict.com/api/oauth/v2/efforts`
- **Scope**: activityRead
- **Parameters**: `startDate`, `endDate` (optional)

#### Zones
- **URL**: `GET https://www.tredict.com/api/oauth/v2/zones`
- **Scope**: bodyvaluesRead
- **Parameters**: `sportType` (optional filter)

#### Deregistration
- **URL**: `DELETE https://www.tredict.com/user/oauth/v2/token`
- **Scope**: Any valid token
- **Purpose**: Revoke access token and refresh token

## Data Structures

### Workout Types

#### Note Workout
```json
{
  "title": "string",
  "notes": "string (optional)",
  "trainingType": "note",
  "sportType": "misc",
  "subSportType": "note" or "rest_day"
}
```

#### Planned Workout
```json
{
  "title": "string",
  "notes": "string (optional)",
  "trainingType": "planned",
  "sportType": "running", "cycling", "swimming", or "misc",
  "subSportType": "...", // See sport-specific sub types
  "poolLength": number, // For swimming only
  "steps": [...] // Array of workout steps
}
```

### Workout Steps

#### Base Step
```json
{
  "note": "string (optional)",
  "intensityType": "warmup", "active", "recover", "rest", "cooldown", or "misc",
  "duration": number, // seconds (optional)
  "distance": number, // meters (optional)
  "durationType": "time", "distance", or "open",
  "progressionType": "steady" or "ramp" (default: "steady"),
  "targetMode": "range" or "padding" (default: "range"),
  "targetZoneType": "cadence", "heartrate", "pace", or "power",
  "targets": { ... } // Target zone definitions
}
```

#### Repetition Step
```json
{
  "repetitions": number, // 1 or more
  "steps": [...] // Array of base steps to repeat
}
```

### Target Modes

#### Range Target (for targetMode "range")
```json
{
  "ftp": {"from": 0.5, "to": 1.0}, // FTP percentage
  "ftpa": {"from": 0.5, "to": 1.0}, // FTPa percentage
  "hrMax": {"from": 0.5, "to": 1.0} // HRMax percentage
}
```

#### Padding Target (for targetMode "padding")
```json
{
  "pace": {"value": 300, "padding": 10}, // seconds per km
  "heartrate": {"value": 140, "padding": 10}, // bpm
  "power": {"value": 200, "padding": 10}, // watts
  "cadence": {"value": 90, "padding": 5} // spm or rpm
}
```

## Sport Types and Sub Types

### Running
- generic, treadmill, street, trail, orienteering, track, obstacle, running_abc, transition, virtual_activity

### Cycling
- generic, virtual_activity, spin, indoor_cycling, road, mountain, gravel_cycling, downhill, bmx, recumbent, hand_cycling, track_cycling, commuting

### Swimming
- generic, open_water, lap_swimming, virtual_activity

### Misc
- generic, virtual_activity, walking, speed_walking, hiking, strength_training, core_training, pilates, flexibility_training, yoga, cardio_training, jump_rope, elliptical, backcountry, cross_country_skiing, alpine_skiing, snowboarding, mountaineering, rock_climbing, ice_climbing, indoor_rowing, rowing, kayaking, paddling, stand_up_paddleboarding, surfing, windsurfing, kitesurfing, inline_skating, ice_skating, stair_climbing, sailing, golf, horseback_riding, volleyball, basketball, handball, soccer, american_football, tennis, badminton, squash

## Error Handling

### Common Status Codes
- 200: Success
- 400: Bad request/invalid data
- 401: Invalid authorization
- 403: Forbidden/expired token
- 404: Not found
- 429: Rate limited
- 500: Server error
- 503: Service unavailable

### Rate Limits
- Activity upload: 8 requests/second
- Activity download: 10 requests/second
- Token endpoint: 20 requests/second

## Best Practices

1. **Token Management**: Store refresh tokens securely and use them to obtain new access tokens
2. **PKCE**: Use PKCE for public clients (mobile, SPAs) for enhanced security
3. **State Parameter**: Always use state parameter to prevent CSRF attacks
4. **Error Handling**: Implement proper retry logic for rate limits
5. **Data Validation**: Validate all input data before sending to API

## Scopes

- `activityWrite`: Upload activity files and create/update plans
- `activityRead`: Download activity list and details
- `bodyvaluesWrite`: Upload health data
- `bodyvaluesRead`: Download health data and capacity values

## Localization

- Use `https://www.tredict.de/` for German authorization dialog
- Use `https://www.tredict.com/` for English authorization dialog
- API responses use language specified in user profile or request parameters

## Implementation Notes for LLMs

1. **Authentication First**: Always ensure proper OAuth2 authentication before making API calls
2. **Scope Checking**: Verify required scopes before attempting operations
3. **Data Structure Validation**: Use the documented schemas to validate input/output
4. **Error Recovery**: Implement robust error handling and retry logic
5. **User Context**: Maintain user context and preferences across interactions
6. **Rate Limit Awareness**: Be mindful of rate limits when making multiple requests
7. **Security**: Never expose client secrets or tokens in logs or responses

This comprehensive description provides LLMs with all necessary information to understand and interact with the Tredict API effectively.