Report API

Report API

Generate immutable reports and inspect availability, cutoff, redaction, and download state.

Reports bind target scope, audience, and collection cutoff. Read report interpretation before using a report for customer or auditor review.

Use the shared API contract for authentication, pagination, request headers, idempotency, and error responses.

Generate a report

POST/organizations/{organization_id}/reports
Scope
reports:write
Auth
Bearer API key

Generates an immutable report. Requires access to every target; broader requests are rejected rather than silently omitting unauthorized assets.

Request body
typestringrequired

Report purpose.

one ofexecutive, incident, vulnerability, audit
asset_idsstring[]optional

Required for executive, vulnerability, and organization audit reports; 1–200 visible unique target IDs.

incident_idstringoptional

Required for incident reports; forbidden with asset_ids.

start_attimestamprequired

Inclusive occurrence-time range start.

end_attimestamprequired

Exclusive range end, after start_at and not in the future.

formatstringoptional

Output format. csv is supported only for vulnerability finding tables; other type/format combinations return 422.

one ofpdf, json, csvdefaultpdf
redactionstringoptional

Unmasked content additionally requires sensitive-data authorization.

one ofmasked, unmaskeddefaultmasked
202Accepted

Returns report ID and operation. The completed report records data cutoff and missing coverage.

List reports

GET/organizations/{organization_id}/reports
Scope
reports:read
Auth
Bearer API key

Returns report state, generation time, scope, cutoff, format, and redaction. Standard limit and cursor apply. Unknown filters return 422.

Query parameters
typestringoptional

Filter report type.

one ofexecutive, incident, vulnerability, audit
incident_idstringoptional

Filter visible incident.

200Result

Returns a data array and pagination.next_cursor. Entries include stable IDs and the resource fields described for this collection.

Read report availability

GET/organizations/{organization_id}/reports/{report_id}
Scope
reports:read
Auth
Bearer API key

Returns coverage metadata and a short-lived download URL after success. Authorization is rechecked before a URL is issued. New data requires a new report, not mutation of the completed artifact.

200Result

Returns data and request_id.

Delete a report

DELETE/organizations/{organization_id}/reports/{report_id}
Scope
reports:write
Auth
Bearer API key

Deletes a report. Requires If-Match; holds return 409. Deletion cannot revoke artifacts already downloaded by recipients.

202Accepted

Returns cleanup operation. Source incidents and findings are unaffected.