# Recommendations

AI recommendations, global and per page.

## Read AI recommendations

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

Global recommendations, prioritised by impact and effort, and per-page
recommendations, crossing crawl results with every connected module.


- Required scopes: `recommendations:read`
- Rate-limit cost: 5 unit(s)

### Parameters

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

### Responses

- `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.

### Request example (cURL)

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

### Response example

```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
        }
    }
}
```

## Generate AI recommendations

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

Starts a generation in the background (`202`); read the recommendations
until `status` is `ready`. Consumes the plan monthly generation quota, so an
`Idempotency-Key` is required.


- Required scopes: `recommendations:write`
- Rate-limit cost: 1 unit(s)
- Idempotency-Key required
- Consumes a plan quota

### Parameters

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

### Responses

- `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.

### Request example (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)"
```

### Response example

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