Imago/docs/API_GUIDE.md

# Guide d'utilisation de l'API Imago

Bienvenue dans la documentation officielle de l'API REST d'Imago.
**Note :** Tous les terminaux (endpoints) principaux présentés ici sont désormais servis sous le préfixe `/api/v1/` dans l'application locale.

## 📍 Sommaire
- [🔐 Authentification](#-Authentification)
- [🛡️ Scopes (Permissions)](#-scopes-permissions)
- [📊 Plans et Rate Limiting](#-plans-et-rate-limiting)
- [👥 Gestion des Clients (Admin uniquement)](#-gestion-des-clients-admin-uniquement)
- [📁 Multi-tenancy et Isolation](#-multi-tenancy-et-isolation)
- [📖 Référence des Endpoints](#-référence-des-endpoints)
  - [📸 Gestion des Images](#-gestion-des-images)
  - [🤖 Intelligence Artificielle](#-intelligence-artificielle)
  - [🔑 Administration (Admin uniquement)](#-administration-admin-uniquement)
  - [🏥 Santé et Status](#-santé-et-status)
- [🚀 Exemples Rapides](#-exemples-rapides)

---

## 🔐 Authentification

Tous les endpoints (sauf `/health` et `/`) nécessitent une authentification via une **Clé API**.

### Header Authorization

Vous devez inclure votre clé dans le header `Authorization` de chaque requête :

```http
Authorization: Bearer VOTRE_CLE_API_SECRET
```

> [!WARNING]
> Traitez votre clé API comme un mot de passe. Ne la partagez jamais et ne l'incluez pas dans du code client (frontend) accessible publiquement.

---

## 🛡️ Scopes (Permissions)

L'accès aux fonctionnalités est contrôlé par des **scopes**. Chaque clé API est limitée à un ensemble de permissions :

| Scope | Description | Fonctions incluses |
|-------|-------------|-------------------|
| `images:read` | Lecture seule | Lister les images, voir les détails, EXIF, OCR, AI. |
| `images:write` | Écriture | Uploader des images, relancer le pipeline de traitement. |
| `images:delete`| Suppression | Supprimer définitivement des images. |
| `ai:use` | Utilisation IA | Résumé d'URL, rédaction de tâches. |
| `admin` | Administration | Gérer les clients API, voir les clés, modifier les plans. |

---

## 📊 Plans et Rate Limiting

Le système applique des limites de requêtes (Rate Limits) basées sur le **Plan** de votre client. Les compteurs sont réinitialisés toutes les heures.

| Plan | Uploads / heure | Requêtes AI / heure |
|------|-----------------|---------------------|
| `free` | 20 | 50 |
| `standard` | 100 | 200 |
| `premium` | 500 | 1000 |

*Les requêtes de lecture (`GET`) ne sont pas limitées par défaut.*

---

## 👥 Gestion des Clients (Admin uniquement)

Si vous avez le scope `admin`, vous pouvez gérer les accès.

### Créer un nouveau client

```bash
curl -X POST http://localhost:8000/auth/clients \
  -H "Authorization: Bearer CLE_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Application Mobile",
    "scopes": ["images:read", "images:write", "ai:use"],
    "plan": "standard"
  }'
```

**Réponse (Importante) :**
```json
{
  "id": "uuid-...",
  "api_key": "cle_generee_en_clair_une_seule_fois",
  "name": "Application Mobile",
  ...
}
```
> [!CAUTION]
> La clé API n'est affichée **qu'une seule fois** à la création. Stockez-la immédiatement de manière sécurisée.

### Régénérer une clé (Rotation)

En cas de compromission, invalidez l'ancienne clé et générez-en une nouvelle :

```bash
curl -X POST http://localhost:8000/auth/clients/{id}/rotate-key \
  -H "Authorization: Bearer CLE_ADMIN"
```

---

## 📁 Multi-tenancy et Isolation

L'API est **multi-tenant**. Cela signifie que :
- Vous ne voyez **que** les images uploadées avec votre clé.
- Les IDs d'images sont globaux, mais si vous tentez d'accéder à l'ID d'un autre client, vous recevrez une erreur `404 Not Found`.
- Vos fichiers physiques sont stockés dans un sous-répertoire dédié sur le serveur (`/data/uploads/{votre_client_id}/`).

---

## 📖 Référence des Endpoints

### 📸 Gestion des Images

#### Lister les images
`GET /api/v1/images`
- **Scope required** : `images:read`
- **Query Params** :
  - `page` : Numéro de page (défaut: 1)
  - `page_size` : Taille de page (défaut: 20, max: 100)
  - `tag` : Filtrer par tag AI
  - `status` : Filtrer par statut (`pending`, `processing`, `done`, `error`)
  - `search` : Recherche textuelle dans le nom, la description AI ou l'OCR.

#### Uploader une image
`POST /api/v1/images/upload`
- **Scope required** : `images:write`
- **Body** : `multipart/form-data`
  - `file` : Le fichier image (JPEG, PNG, WebP, etc.)
- **Note** : Lance automatiquement le pipeline AI en arrière-plan.

#### Détail complet d'une image
`GET /api/v1/images/{id}`
- **Scope required** : `images:read`
- **Description** : Retourne toutes les données (Source, EXIF, OCR, AI).

#### Statut du traitement
`GET /api/v1/images/{id}/status`
- **Scope required** : `images:read`
- **Description** : Pour savoir si l'analyse par l'IA est terminée.

#### Métadonnées spécifiques
- `GET /api/v1/images/{id}/exif` : Données techniques de l'appareil et GPS.
- `GET /api/v1/images/{id}/ocr` : Texte extrait de l'image.
- `GET /api/v1/images/{id}/ai` : Description textuelle et tags générés.

#### Retraitement
`POST /api/v1/images/{id}/reprocess`
- **Scope required** : `images:write`
- **Description** : Réinitialise et relance le pipeline d'analyse AI.

#### Suppression
`DELETE /api/v1/images/{id}`
- **Scope required** : `images:delete`
- **Description** : Supprime l'entrée en base et les fichiers sur le disque.

#### Tags globaux
`GET /api/v1/images/tags/all`
- **Scope required** : `images:read`
- **Description** : Liste tous les tags uniques utilisés par le client.

---

### 🤖 Intelligence Artificielle

#### Résumé d'URL
`POST /api/v1/ai/summarize`
- **Scope required** : `ai:use`
- **Body** (JSON) :
  ```json
  {
    "url": "https://...",
    "language": "français"
  }
  ```

#### Rédaction de tâche
`POST /api/v1/ai/draft-task`
- **Scope required** : `ai:use`
- **Body** (JSON) :
  ```json
  {
    "description": "Texte libre décrivant la tâche",
    "context": "Contexte optionnel",
    "language": "fr"
  }
  ```

---

### 🔑 Administration (Admin uniquement)
*Nécessite le scope `admin`.*

- `POST /api/v1/auth/clients` : Créer un client (retourne la clé).
- `GET /api/v1/auth/clients` : Lister tous les clients.
- `GET /api/v1/auth/clients/{id}` : Voir les détails d'un client.
- `PATCH /api/v1/auth/clients/{id}` : Modifier un client (nom, scopes, plan).
- `POST /api/v1/auth/clients/{id}/rotate-key` : Changer la clé API.
- `DELETE /api/v1/auth/clients/{id}` : Désactiver un client (suspension d'accès).

---

### 🏥 Santé et Status
Ces endpoints sont **publics** et ne nécessitent aucune clé API.

- `GET /` : Informations de base sur l'application (Version, Status).
- `GET /health` : Vérification complète de l'état (AI configurée, OCR actif, Modèle utilisé).

---

## 🚀 Exemples Rapides

### Lister mes images (Python / httpx)

```python
import httpx

headers = {"Authorization": "Bearer ma_super_cle"}
r = httpx.get("http://localhost:8000/images", headers=headers)

for img in r.json()["items"]:
    print(f"ID: {img['id']} | Name: {img['original_name']}")
```

### Uploader une image (Node.js / Axios)

```javascript
const axios = require('axios');
const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('file', fs.createReadStream('vacances.jpg'));

axios.post('http://localhost:8000/images/upload', form, {
    headers: {
        ...form.getHeaders(),
        'Authorization': 'Bearer ma_super_cle'
    }
}).then(console.log);
```