API reference
Reports
List a pentest’s reports, download one, and share it by link.
Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.
| Operation | Method and path | Who may call it |
|---|---|---|
| List reports | GET /api/orgs/{org}/reports | read |
| Download a report | GET /api/orgs/{org}/reports/{id}/html | read |
| Share or unshare a report | POST /api/orgs/{org}/reports/{id}/share | admin |
#List reports
GET /api/orgs/{org}/reports
Returns every report of the organisation as a plain list, newest first. The list is not paged. Reports are written when a pentest finishes; the reports of one pentest are also on that pentest.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reports"
Answer (200, application/json)
The reports.
An array of Report.
[
{
"id": "rpt_0c7a5e13f8b2",
"orgId": "org_5b1e7a90c3d2",
"pentestId": "pen_7c2e9a41b6d0",
"kind": "full",
"title": "Penetration test report: acme/shop",
"shareToken": null,
"shared": false,
"createdAt": "2026-11-16T11:02:41.000Z",
"snapshotId": "rsn_5e2a8c1f9d47",
"revisedAt": "2026-11-18T15:20:00.000Z"
}
]
#Download a report
GET /api/orgs/{org}/reports/{id}/html
Returns one report as a complete, self-contained HTML page. The page is produced from the record stored when the report was issued, so it shows the findings as they were then: triage decisions taken later do not change it. A report issued before records were kept (no snapshotId) is produced from the findings as they are now and says so in its first line. It needs no other files and can be saved or printed to PDF from a browser.
Who may call it: An API key with the read scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reports/ID/html"
Answer (200, text/html)
The report as an HTML document.
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No report of this organisation has that id. |
#Share or unshare a report
POST /api/orgs/{org}/reports/{id}/share
Switches the public link of a report on or off. Sharing gives the report a shareToken; anyone who has the address /share/reports/{shareToken} on your Nullgap host can read the report without signing in, so treat the link as a secret. Sharing a report that is already shared keeps its link. Only admins and owners see shareToken (here and in the report lists); members and read-only keys see shared: true without the link. Unsharing sets shareToken to null and the old link stops working for good: sharing again makes a new one.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
shared | boolean | yes | True to switch the public link on, false to switch it off. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"shared":true}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/reports/ID/share"
Answer (200, application/json)
A Report object.
{
"id": "rpt_0c7a5e13f8b2",
"orgId": "org_5b1e7a90c3d2",
"pentestId": "pen_7c2e9a41b6d0",
"kind": "full",
"title": "Penetration test report: acme/shop",
"shareToken": null,
"shared": false,
"createdAt": "2026-11-16T11:02:41.000Z",
"snapshotId": "rsn_5e2a8c1f9d47",
"revisedAt": "2026-11-18T15:20:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No report of this organisation has that id. |
#Objects
The objects the operations above take and return.
#Report
A report issued for a finished pentest. It is a record: it shows the findings as they were when it was issued, whatever was decided about them later.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The report id. |
orgId | string | yes | The organisation it belongs to. |
pentestId | string | yes | The pentest it reports on. |
kind | string | yes | full: every finding with its evidence. executive: a summary for people who do not read code. attestation: a short statement that the test took place and what it covered. |
title | string | yes | The report title. |
shareToken | string or null | yes | The secret part of the public link, /share/reports/{shareToken}. Anyone who has the link can read the report. Null while the report is not shared, and always null for a member or a read-only key: only an admin or owner (or a key with the admin scope), who can switch the link on and off, is given it. shared says whether a link exists. |
shared | boolean | yes | Whether the report has a public link. Given to everyone who can read the report, unlike the link itself. |
createdAt | string | yes | When the report was issued. |
snapshotId | string or null | no | The stored record the report is produced from: the pentest and its findings as they were when the report was issued. The three reports of one pentest share it. Absent or null on a report issued before records were kept; such a report is produced from the findings as they are today and says so in its first line. |
revisedAt | string or null | no | Set when the report was revised, which happens once and only where Nullgap researchers review the findings after the pentest: when the last finding has been reviewed. Absent or null otherwise. |
Nullgap documentation