# Recommandations

Les recommandations IA, globales et par page.

## Lire les recommandations IA

`GET /v1/projects/{project}/recommendations`

Les recommandations globales, priorisées par impact et effort, et les recommandations par page, qui croisent les résultats de crawl avec chaque module connecté.

- Scopes requis: `recommendations:read`
- Coût en débit: 5 unité(s)

### Paramètres

- `project` (path, string (uuid), requis)

### Réponses

- `200`: OK.
- `401`: Missing, invalid or expired token, or a member who left the team.
- `403`: The plan does not include the API (`api.not_in_plan`) or this verb
(`api.write_not_in_plan`), or the token lacks a scope
(`token.missing_scope`).

- `404`: No such resource for the token's team. Resources of another team answer 404 as well, never 403.
- `429`: The plan rate limit is exhausted for one window.

### Exemple de requête (cURL)

```bash
curl "https://api.nessflow.com/v1/projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```

### Exemple de réponse

```json
{
    "data": {
        "project_id": "0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57",
        "status": "ready",
        "crawl_id": "0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57",
        "generated_at": "2026-10-01T09:30:00Z",
        "global": [
            {}
        ],
        "pages": [
            {}
        ],
        "quota": {
            "used": 42,
            "limit": 100,
            "remaining": 100
        }
    }
}
```

## Générer les recommandations IA

`POST /v1/projects/{project}/recommendations`

Lance une génération en tâche de fond (`202`) ; lisez les recommandations jusqu’à ce que `status` vaille `ready`. Consomme le quota mensuel de générations de l’offre, d’où l’`Idempotency-Key` exigée.

- Scopes requis: `recommendations:write`
- Coût en débit: 1 unité(s)
- Idempotency-Key exigée
- Consomme un quota de l’offre

### Paramètres

- `project` (path, string (uuid), requis)

### Réponses

- `202`: OK.
- `400`: Malformed request, such as an invalid pagination cursor (`pagination.invalid_cursor`).
- `401`: Missing, invalid or expired token, or a member who left the team.
- `403`: The plan does not include the API (`api.not_in_plan`) or this verb
(`api.write_not_in_plan`), or the token lacks a scope
(`token.missing_scope`).

- `404`: No such resource for the token's team. Resources of another team answer 404 as well, never 403.
- `409`: The request conflicts with the current state (a crawl already running, an idempotency key in use, a project not ready).
- `422`: Invalid query or body values (`validation_failed`), with `errors` by field.
- `429`: The plan rate limit is exhausted for one window.

### Exemple de requête (cURL)

```bash
curl -X POST "https://api.nessflow.com/v1/projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

### Exemple de réponse

```json
{
    "data": {
        "project_id": "0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57",
        "status": "queued"
    }
}
```