Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
List reportsGET /api/orgs/{org}/reportsread
Download a reportGET /api/orgs/{org}/reports/{id}/htmlread
Share or unshare a reportPOST /api/orgs/{org}/reports/{id}/shareadmin

#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

NameTypeRequiredDescription
orgstringyesThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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

StatusCodeWhen
404not_foundNo 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
sharedbooleanyesTrue 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

StatusCodeWhen
404not_foundNo 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.

FieldTypeAlways presentDescription
idstringyesThe report id.
orgIdstringyesThe organisation it belongs to.
pentestIdstringyesThe pentest it reports on.
kindstringyesfull: 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.
titlestringyesThe report title.
shareTokenstring or nullyesThe 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.
sharedbooleanyesWhether the report has a public link. Given to everyone who can read the report, unlike the link itself.
createdAtstringyesWhen the report was issued.
snapshotIdstring or nullnoThe 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.
revisedAtstring or nullnoSet 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