# Tredict API: Setup and Getting Started

This document describes how to start using the Tredict API. It focuses on the Personal Access Token flow, which is the simplest path for individual users. Everything in this and the other skill files also applies to applications using OAuth2, since endpoints, scopes, and data structures are identical. Only the way the bearer token is obtained differs.

## Personal API vs. OAuth2

Tredict offers two access methods.

The **Personal API** is the right choice for individual users. You generate a static bearer token in the Tredict settings, store it securely, and send it with every request. No registration, no token refresh, no callback URLs. Good for personal scripts, LLM-assisted workflows, and single-user tools.

The **OAuth2 flow** is needed when you build an application that accesses Tredict on behalf of other users, or when you want refresh-token-based credential management for production use. It supports both standard OAuth2 and OAuth2.1 with PKCE. See `https://www.tredict.com/llms-full.txt` for the full OAuth2 specification.

Once a bearer token is in hand, the rest of this guide and all other skill files apply unchanged regardless of how the token was obtained.

## Generating a Personal Access Token

In the Tredict web interface, go to Settings, section "Personal API", and create a new token. When generating, you select the scopes you want to grant. The four available scopes are:

- `activityRead`: read activities and planned trainings
- `activityWrite`: upload activities, create or modify trainings and plans
- `bodyvaluesRead`: read health and body values
- `bodyvaluesWrite`: write health and body values

Only grant scopes you actually need. The token is shown once and should be stored securely, typically as an environment variable, never in source code.

## Authentication

Every request carries the token in the Authorization header:

```
Authorization: Bearer YOUR_PERSONAL_TOKEN
```

No token refresh, no PKCE, no authorization codes.

## Base URL and Conventions

All endpoints live under `https://www.tredict.com/api/oauth/v2/`. Both the Personal API and the OAuth2 API use this path.

Responses are JSON unless stated otherwise. File downloads (activity files, FIT workouts) return `application/octet-stream` with the filename in the Content-Disposition header.

Date parameters are ISO-8601. Timestamps in response bodies come either as ISO strings or as Unix seconds depending on the endpoint, check the specific endpoint when in doubt.

## Testing the First Connection

The simplest test is the activity list. It always works, provided `activityRead` is set on the token:

```
curl -H "Authorization: Bearer $TREDICT_TOKEN" \
  "https://www.tredict.com/api/oauth/v2/activityList?pageSize=50"
```

The response contains an array of recent activities plus `self` and `next` links for pagination. If this works, authentication is set up correctly.

## Common Errors

- **401 Unauthorized**: Token missing, mistyped, or deleted. Don't forget the Bearer prefix.
- **403 Forbidden**: Token exists, but the scope for this endpoint is missing. Generate a new token with the right scopes in settings.
- **429 Too Many Requests**: Rate limit reached. Throttle requests and retry with backoff.

The relevant rate limits:
- Activity upload: 8 per second
- Activity download: 10 per second
- Token endpoint: 20 per second

For personal use these limits are practically never an issue.

## Where to Go Next

Read the topic-specific files for your task:

- `activities.md`: read activities, upload them, download original files
- `workouts.md`: build structured workouts and training plans
- `health-data.md`: HRV, sleep, body values, capacities
- `recipes.md`: ready-made example workflows (weekly stats, equipment usage, CSV export)

For a complete endpoint reference: `https://www.tredict.com/llms-full.txt`.