Skip to content
Puck Docs

Reports API

Every completed investigation generates a structured report: a narrative written by the brain’s LLM layer that synthesises all agent findings into a coherent story with severity, per-endpoint detail, and recommended actions. The Reports API lets you fetch that report programmatically and trigger a regeneration if you want a fresh synthesis after new findings have been added.

Scope required: reports:read

GET /v1/investigations/{id}/report

Fetch the structured report for a completed investigation. Returns 404 if the investigation does not exist, and 409 if the investigation has not yet reached completed status.

The report body includes:

  • narrative — full prose summary written by the brain, suitable for a security bulletin
  • severity — overall severity: low, medium, high, or critical
  • findings_summary — array of per-finding summaries with node references
  • recommended_actions — prioritised list of remediation steps
  • generated_at — ISO-8601 timestamp of when this version was generated
  • model — the LLM model tier used to generate the narrative
Terminal window
curl "https://puck.acme.com/v1/investigations/inv_01hx/report" \
  -H "Authorization: Bearer $PUCK_API_KEY"
const res = await fetch(
  `https://puck.acme.com/v1/investigations/${investigationId}/report`,
  { headers: { Authorization: `Bearer ${process.env.PUCK_API_KEY}` } }
);
if (res.status === 409) throw new Error("investigation not yet complete");
const report = await res.json();
console.log("severity:", report.severity);

POST /v1/investigations/{id}/report/regenerate

Trigger a fresh narrative generation for a completed investigation. Useful when new findings have been added, findings have been dismissed, or you want a deeper synthesis from a higher-tier model.

Returns 202 Accepted immediately. The new report replaces the existing one once generation completes; poll GET /v1/investigations/{id}/report and compare generated_at to know when the new version is ready.

Regeneration re-runs the narrative LLM step only — it does not re-dispatch plans to agents. For fresh endpoint data, trigger a new investigation.

Terminal window
curl -X POST "https://puck.acme.com/v1/investigations/inv_01hx/report/regenerate" \
  -H "Authorization: Bearer $PUCK_API_KEY"
const res = await fetch(
  `https://puck.acme.com/v1/investigations/${investigationId}/report/regenerate`,
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.PUCK_API_KEY}` },
  }
);
const { job_id } = await res.json();