Documentation contents
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
-
projectpath · string (uuid) · required
Responses
-
200OK. -
401Missing, invalid or expired token, or a member who left the team. -
403The 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`). -
404No such resource for the token's team. Resources of another team answer 404 as well, never 403. -
429The plan rate limit is exhausted for one window.
cURL
curl "https://api.nessflow.com/v1/projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations" \
-H "Authorization: Bearer $NESSFLOW_TOKEN"PHP
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.nessflow.com/v1/']);
$response = $client->request('GET', 'projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations', [
'headers' => [
'Authorization' => 'Bearer '.getenv('NESSFLOW_TOKEN'),
],
]);
$data = json_decode((string) $response->getBody(), true);JavaScript
const response = await fetch('https://api.nessflow.com/v1/projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations', {
headers: {
Authorization: `Bearer ${process.env.NESSFLOW_TOKEN}`,
},
});
const data = await response.json();Python
import os
import requests
response = requests.get(
"https://api.nessflow.com/v1/projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations",
headers={
"Authorization": f"Bearer {os.environ['NESSFLOW_TOKEN']}",
},
timeout=30,
)
response.raise_for_status()
data = response.json()Response example
{
"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
- Idempotency-Key required
- Rate-limit cost
- Consumes a plan quota
Parameters
-
projectpath · string (uuid) · required
Responses
-
202OK. -
400Malformed request, such as an invalid pagination cursor (`pagination.invalid_cursor`). -
401Missing, invalid or expired token, or a member who left the team. -
403The 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`). -
404No such resource for the token's team. Resources of another team answer 404 as well, never 403. -
409The request conflicts with the current state (a crawl already running, an idempotency key in use, a project not ready). -
422Invalid query or body values (`validation_failed`), with `errors` by field. -
429The plan rate limit is exhausted for one window.
cURL
curl -X POST "https://api.nessflow.com/v1/projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations" \
-H "Authorization: Bearer $NESSFLOW_TOKEN" \
-H "Idempotency-Key: $(uuidgen)"PHP
$client = new GuzzleHttp\Client(['base_uri' => 'https://api.nessflow.com/v1/']);
$response = $client->request('POST', 'projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations', [
'headers' => [
'Authorization' => 'Bearer '.getenv('NESSFLOW_TOKEN'),
'Idempotency-Key' => bin2hex(random_bytes(16)),
],
]);
$data = json_decode((string) $response->getBody(), true);JavaScript
const response = await fetch('https://api.nessflow.com/v1/projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.NESSFLOW_TOKEN}`,
'Idempotency-Key': crypto.randomUUID(),
},
});
const data = await response.json();Python
import os
import uuid
import requests
response = requests.post(
"https://api.nessflow.com/v1/projects/0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57/recommendations",
headers={
"Authorization": f"Bearer {os.environ['NESSFLOW_TOKEN']}",
"Idempotency-Key": str(uuid.uuid4()),
},
timeout=30,
)
response.raise_for_status()
data = response.json()Response example
{
"data": {
"project_id": "0190f5a2-7c4e-7b1a-9d3e-2f6b8c1a4e57",
"status": "queued"
}
}