# Turf SaaS — API v1 Reference

Sprint 3-4 · HRT-29 — Refacto API /v1/

## Base URL

```
http://<host>:8792
```

## Authentication

All endpoints (except `/api/v1/health` and `/api/v1/auth/*`) require a **Bearer JWT** token.

```
Authorization: Bearer <access_token>
```

### Get a token

```bash
# Register
curl -X POST http://localhost:8792/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "mypassword"}'

# Login → returns access_token + refresh_token
curl -X POST http://localhost:8792/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com", "password": "mypassword"}'
```

## Plans & Access Control

| Plan      | Inclus                                             |
|-----------|----------------------------------------------------|
| `free`    | health, auth, courses/today, predictions/top3 (1/j)|
| `premium` | + predictions/all, valuebets, metrics              |
| `pro`     | + backtest, export/csv                             |

## Endpoints

### System

| Method | Path             | Auth | Description          |
|--------|------------------|------|----------------------|
| GET    | `/api/v1/health` | Non  | Healthcheck public   |
| GET    | `/api/v1/docs`   | Non  | Swagger UI           |

### Auth

| Method | Path                      | Description                    |
|--------|---------------------------|--------------------------------|
| POST   | `/api/v1/auth/register`   | Créer un compte (plan=free)    |
| POST   | `/api/v1/auth/login`      | Login → JWT tokens             |
| POST   | `/api/v1/auth/refresh`    | Renouveler l'access token      |
| POST   | `/api/v1/auth/logout`     | Révoquer le refresh token      |

### Courses

| Method | Path                                  | Plan    | Description                        |
|--------|---------------------------------------|---------|------------------------------------|
| GET    | `/api/v1/courses/today`               | free+   | Courses du jour (paginé)           |
| GET    | `/api/v1/courses/{id}/predictions`    | free+   | Prédictions ML pour une course     |

Query params `courses/today`: `filter=[all|quinte|trot|plat]`, `limit`, `offset`

`{id}` format: `{num_reunion}-{num_course}` ex: `1-3`

### Prédictions

| Method | Path                      | Plan      | Description                  |
|--------|---------------------------|-----------|------------------------------|
| GET    | `/api/v1/predictions/top3`| free+     | Top 3 chevaux du jour        |
| GET    | `/api/v1/predictions/all` | premium+  | Toutes les prédictions ML    |

Query params: `date=YYYY-MM-DD`, `limit`, `offset`

### Value Bets

| Method | Path                | Plan      | Description              |
|--------|---------------------|-----------|--------------------------|
| GET    | `/api/v1/valuebets` | premium+  | Value bets du jour       |

Query params: `date`, `min_odds` (défaut 2.0), `limit`, `offset`

### Backtest

| Method | Path                | Plan | Description                      |
|--------|---------------------|------|----------------------------------|
| GET    | `/api/v1/backtest`  | pro  | Résultats historiques des paris  |

Query params: `start`, `end` (YYYY-MM-DD), `limit`, `offset`

### Export

| Method | Path                    | Plan | Description          |
|--------|-------------------------|------|----------------------|
| GET    | `/api/v1/export/csv`    | pro  | Export CSV           |

Query params: `type=[predictions|bets]`, `date`, `start`, `end`

### Métriques

| Method | Path                | Plan     | Description           |
|--------|---------------------|----------|-----------------------|
| GET    | `/api/v1/metrics`   | premium+ | Métriques ML et paris |

Query params: `days` (int, défaut 30)

## Réponse uniforme

Toutes les erreurs retournent :

```json
{
  "status": "error",
  "message": "Description de l'erreur",
  "code": 400
}
```

Les listes paginées incluent :

```json
{
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}
```

## Démarrage

```bash
cd /home/h3r7/turf_saas
source venv/bin/activate
python app_v1.py
# ou
gunicorn -w 2 -b 0.0.0.0:8792 app_v1:app
```

## Tests

```bash
cd /home/h3r7/turf_saas
source venv/bin/activate
python -m pytest tests/test_api_v1.py -v
```

## Documentation Swagger

Accessible sur : `http://localhost:8792/api/v1/docs`