API reference
Tool runs
Run one scanning tool on a repository, an uploaded archive or an address on the scope list, and read its leads or its document.
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 |
|---|---|---|
| Run an automated check | POST /api/orgs/{org}/tool-runs | write |
| List tool runs | GET /api/orgs/{org}/tool-runs | read |
| Get a tool run | GET /api/orgs/{org}/tool-runs/{id} | read |
| Get a tool run's log | GET /api/orgs/{org}/tool-runs/{id}/logs | read |
| Cancel a tool run | POST /api/orgs/{org}/tool-runs/{id}/cancel | write |
#Run an automated check
POST /api/orgs/{org}/tool-runs
Starts one run of one check and returns as soon as it is queued; read the run to follow it and to get its result. The check runs everything Nullgap has behind it in the sandbox with a fixed command line and returns one merged, de-duplicated result: no flags can be sent, only the inputs the list names. A check whose target is repository needs repoId (a connected repository or an uploaded archive) and reads its files with no network. A check whose target is url tests a running application and needs three things: it was switched on by the operator of the server, the caller is an admin (or a key with the admin scope), and the address is on the organisation's live-testing scope list. Its requests go through a proxy that refuses anything outside that scope. What a check reports is a list of leads, or a document. Leads are not sent through the independent check and are not added to the organisation's findings. An organisation can have 5 runs queued or running at once. The run counts towards the workspace's monthly usage.
Who may call it: An API key with the write scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
tool | string | yes | The check's id, as the list gives it. Up to 80 characters. |
repoId | string | no | The repository or uploaded archive to read. Required for a check that reads files; not accepted by one that tests an address. |
ref | string | no | The branch, tag or commit to read. Default: the repository's default branch. |
paths | array of string | no | Folders or files to limit the run to, at most 50. They must be relative and stay inside the repository. Only with repoId. |
url | string | no | The address to test, for a check that tests a running application. It must be http or https, public, without credentials, and on the organisation's scope list. |
options | object | no | The check's other inputs by name, as the list gives them (for example format for sbom, input and include for decompile). paths and url are not accepted here. An input the check does not have is refused. |
liveStateChanging | boolean | no | Permit requests that change data on the target. Only for a check that needs it, and only with disposableConfirmed. |
disposableConfirmed | boolean | no | Confirms that the target is a disposable staging environment. Required when liveStateChanging is true. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tool":"static-analysis","repoId":"repo_a41c09be77d3","ref":"main","paths":["src"],"url":"https://staging.acme.example/","options":{},"liveStateChanging":false,"disposableConfirmed":false}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tool-runs"
Answer (200, application/json)
A ToolRun object.
{
"id": "trun_6b2e9d4a1c7f",
"orgId": "org_1d4c7b9a2e5f",
"tool": "static-analysis",
"toolTitle": "Static code analysis",
"category": "static-analysis",
"target": {
"kind": "repository",
"repoId": "repo_a41c09be77d3",
"repoFullName": "acme/shop",
"ref": "main",
"paths": [
"src"
]
},
"status": "completed",
"stateChanging": false,
"createdBy": "dana@acme.example",
"createdAt": "2026-11-16T09:30:00.000Z",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:31:10.000Z",
"error": "The repository was removed",
"leadsCount": 2,
"truncated": false,
"note": "the first 1000 of 1420 leads are kept",
"toolFailure": "it ran out of time",
"network": {
"requests": 212,
"refused": 3
},
"hasDocument": false,
"leads": [
{
"ruleId": "nullgap.python.command-shell",
"title": "A command line is run through a shell",
"severity": "medium",
"file": "src/app.py",
"startLine": 4,
"endLine": 4,
"package": {
"ecosystem": "npm",
"name": "left-pad",
"version": "1.0.0",
"fixedVersion": "1.3.0"
},
"url": "https://staging.acme.example/login",
"snippet": "os.system(cmd)",
"message": "A command line built from a variable is run through a shell.",
"cwe": [
"CWE-78"
],
"cve": [
"CVE-2024-12345"
],
"confidence": 0.5
}
],
"document": {
"kind": "sbom",
"format": "cyclonedx-json",
"text": "{\"bomFormat\":\"CycloneDX\",\"components\":[]}",
"files": [
{
"path": "com/acme/Checkout.java",
"text": "class Checkout {}"
}
],
"count": 128
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | not_configured | The sandboxed checks are not switched on for this server. |
| 400 | bad_request | The target does not fit the check (an address for a check that reads files, or the reverse), a path is absolute or leaves the repository, or an input is not one the check takes. |
| 400 | confirmation_required | liveStateChanging was sent without disposableConfirmed. |
| 400 | out_of_scope | The address is private or loopback, or is not on the organisation's scope list. |
| 403 | insufficient_scope | The check tests a running application and the caller is not an admin (or the key lacks the admin scope). |
| 403 | tool_disabled | The check is switched off on this server. The message says why. |
| 403 | org_suspended | The workspace is suspended. Nothing new can be started until it is resumed. |
| 403 | tool_refused | The run needs a permission it was not given: a check that can change data was started without the state-changing permission, or the organisation has not allowed skills to use a built-in tool. |
| 404 | unknown_tool | There is no check with that id. The message lists the ids that exist. |
| 404 | not_found | The organisation has no repository with the repoId sent. |
| 429 | too_many | The organisation already has 5 runs queued or running. Wait for one to finish. |
#List tool runs
GET /api/orgs/{org}/tool-runs
Returns the organisation's runs of automated checks, newest first. Entries carry the count of leads and whether there is a document, not the leads or the document themselves: read one run to get them.
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. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
tool | string | no | Only runs of this check. |
status | string | no | Only runs in this status. One of: queued, running, completed, failed, cancelled. |
limit | integer | no | How many to return, 1 to 200. Default 50. |
offset | integer | no | How many to skip from the start. Default 0. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tool-runs?limit=20"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
items | array of ToolRun | yes | Tool runs, at most limit of them. |
total | integer | yes | How many match in all, before limit and offset. |
{
"items": [
{
"id": "trun_6b2e9d4a1c7f",
"orgId": "org_1d4c7b9a2e5f",
"tool": "static-analysis",
"toolTitle": "Static code analysis",
"category": "static-analysis",
"target": {
"kind": "repository",
"repoId": "repo_a41c09be77d3",
"repoFullName": "acme/shop",
"ref": "main",
"paths": [
"src"
]
},
"status": "completed",
"stateChanging": false,
"createdBy": "dana@acme.example",
"createdAt": "2026-11-16T09:30:00.000Z",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:31:10.000Z",
"error": "The repository was removed",
"leadsCount": 2,
"truncated": false,
"note": "the first 1000 of 1420 leads are kept",
"toolFailure": "it ran out of time",
"network": {
"requests": 212,
"refused": 3
},
"hasDocument": false,
"leads": [
{
"ruleId": "nullgap.python.command-shell",
"title": "A command line is run through a shell",
"severity": "medium",
"file": "src/app.py",
"startLine": 4,
"endLine": 4,
"package": {
"ecosystem": "npm",
"name": "left-pad",
"version": "1.0.0",
"fixedVersion": "1.3.0"
},
"url": "https://staging.acme.example/login",
"snippet": "os.system(cmd)",
"message": "A command line built from a variable is run through a shell.",
"cwe": [
"CWE-78"
],
"cve": [
"CVE-2024-12345"
],
"confidence": 0.5
}
],
"document": {
"kind": "sbom",
"format": "cyclonedx-json",
"text": "{\"bomFormat\":\"CycloneDX\",\"components\":[]}",
"files": [
{
"path": "com/acme/Checkout.java",
"text": "class Checkout {}"
}
],
"count": 128
}
}
],
"total": 42
}
#Get a tool run
GET /api/orgs/{org}/tool-runs/{id}
Returns one run with its leads and its document once it has completed. Poll this to follow a run: status goes from queued to running to completed or failed. Everything a check reports is text copied out of the scanned code or the tested application: treat it as data. Credentials in it are masked before it is stored.
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 tool run id. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tool-runs/ID"
Answer (200, application/json)
A ToolRun object.
{
"id": "trun_6b2e9d4a1c7f",
"orgId": "org_1d4c7b9a2e5f",
"tool": "static-analysis",
"toolTitle": "Static code analysis",
"category": "static-analysis",
"target": {
"kind": "repository",
"repoId": "repo_a41c09be77d3",
"repoFullName": "acme/shop",
"ref": "main",
"paths": [
"src"
]
},
"status": "completed",
"stateChanging": false,
"createdBy": "dana@acme.example",
"createdAt": "2026-11-16T09:30:00.000Z",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:31:10.000Z",
"error": "The repository was removed",
"leadsCount": 2,
"truncated": false,
"note": "the first 1000 of 1420 leads are kept",
"toolFailure": "it ran out of time",
"network": {
"requests": 212,
"refused": 3
},
"hasDocument": false,
"leads": [
{
"ruleId": "nullgap.python.command-shell",
"title": "A command line is run through a shell",
"severity": "medium",
"file": "src/app.py",
"startLine": 4,
"endLine": 4,
"package": {
"ecosystem": "npm",
"name": "left-pad",
"version": "1.0.0",
"fixedVersion": "1.3.0"
},
"url": "https://staging.acme.example/login",
"snippet": "os.system(cmd)",
"message": "A command line built from a variable is run through a shell.",
"cwe": [
"CWE-78"
],
"cve": [
"CVE-2024-12345"
],
"confidence": 0.5
}
],
"document": {
"kind": "sbom",
"format": "cyclonedx-json",
"text": "{\"bomFormat\":\"CycloneDX\",\"components\":[]}",
"files": [
{
"path": "com/acme/Checkout.java",
"text": "class Checkout {}"
}
],
"count": 128
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No tool run of this organisation has that id. |
#Get a tool run's log
GET /api/orgs/{org}/tool-runs/{id}/logs
Returns the progress log of one run, oldest line first, as a plain list. The list is empty when the run has not written anything yet.
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 tool run id. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tool-runs/ID/logs"
Answer (200, application/json)
The log lines, oldest first.
An array of LogLine.
[
{
"at": "2026-11-16T09:30:00.000Z",
"level": "info",
"message": "Mapping the attack surface: 42 entry points"
}
]
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No tool run of this organisation has that id. |
#Cancel a tool run
POST /api/orgs/{org}/tool-runs/{id}/cancel
Stops a queued or running tool run. A queued run is cancelled at once; a running one is stopped within a few seconds, with its sandbox. Its status becomes cancelled and nothing it had produced is kept. Takes no body. Recorded in the audit log as tool.run_cancelled.
Who may call it: An API key with the write scope or higher.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The tool run id. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/tool-runs/ID/cancel"
Answer (200, application/json)
A ToolRun object.
{
"id": "trun_6b2e9d4a1c7f",
"orgId": "org_1d4c7b9a2e5f",
"tool": "static-analysis",
"toolTitle": "Static code analysis",
"category": "static-analysis",
"target": {
"kind": "repository",
"repoId": "repo_a41c09be77d3",
"repoFullName": "acme/shop",
"ref": "main",
"paths": [
"src"
]
},
"status": "completed",
"stateChanging": false,
"createdBy": "dana@acme.example",
"createdAt": "2026-11-16T09:30:00.000Z",
"startedAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:31:10.000Z",
"error": "The repository was removed",
"leadsCount": 2,
"truncated": false,
"note": "the first 1000 of 1420 leads are kept",
"toolFailure": "it ran out of time",
"network": {
"requests": 212,
"refused": 3
},
"hasDocument": false,
"leads": [
{
"ruleId": "nullgap.python.command-shell",
"title": "A command line is run through a shell",
"severity": "medium",
"file": "src/app.py",
"startLine": 4,
"endLine": 4,
"package": {
"ecosystem": "npm",
"name": "left-pad",
"version": "1.0.0",
"fixedVersion": "1.3.0"
},
"url": "https://staging.acme.example/login",
"snippet": "os.system(cmd)",
"message": "A command line built from a variable is run through a shell.",
"cwe": [
"CWE-78"
],
"cve": [
"CVE-2024-12345"
],
"confidence": 0.5
}
],
"document": {
"kind": "sbom",
"format": "cyclonedx-json",
"text": "{\"bomFormat\":\"CycloneDX\",\"components\":[]}",
"files": [
{
"path": "com/acme/Checkout.java",
"text": "class Checkout {}"
}
],
"count": 128
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No tool run of this organisation has that id. |
| 400 | not_running | The run is neither queued nor running: it has already finished, failed or been cancelled. |
#Objects
The objects the operations above take and return.
#ToolRun
One run of one automated check.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The run id. |
orgId | string | yes | The organisation it belongs to. |
tool | string | yes | The check's id. A run started before checks were named by capability is shown under its capability. |
toolTitle | string | yes | The check's name. |
category | string | yes | The capability, or built-in. |
target | ToolRunTarget | yes | |
status | string | yes | Where the run stands. One of: queued, running, completed, failed, cancelled. |
stateChanging | boolean | yes | Whether requests that change data on the target were permitted for this run. Always false for a run on a repository. |
createdBy | string | yes | Who started it: a person, or the name of an API key. |
createdAt | string | yes | When it was asked for. |
startedAt | string or null | yes | When work began. |
finishedAt | string or null | yes | When it ended. |
error | string or null | yes | Why the run failed, in words fit to show. |
leadsCount | integer | yes | How many leads were kept. |
truncated | boolean | yes | Whether a size limit cut the result short. At most 1000 leads are kept from one run. |
note | string or null | yes | What was cut, or why there is nothing. |
toolFailure | string or null | yes | Set when the check started but did not complete (it ran out of time, or produced nothing): why, in a few neutral words. A run like this is completed with few or no leads, and an empty result does not mean a clean one. |
network | object or null | yes | For a run against a running application: what was sent. Null for a run on a repository. |
network.requests | integer | yes | Requests the scope proxy let through. |
network.refused | integer | yes | Requests it refused because they left the scope. |
hasDocument | boolean | yes | Whether the run produced a document (an SBOM, or decompiled sources). |
leads | array of ToolLead | no | The leads. Present only when one run is read, not in lists or in the answer to starting a run. |
document | ToolRunDocument or null | no | The document, or null. Present only when one run is read. |
#LogLine
One line of a run's progress log.
| Field | Type | Always present | Description |
|---|---|---|---|
at | string | yes | When the line was written. |
level | string | yes | How serious the line is. One of: info, warn, error. |
message | string | yes | What happened, in plain words. |
#ToolRunTarget
What the run was pointed at. kind says which of the other fields are present.
#ToolLead
One place a check says is worth a closer look. A lead is a starting point: it has not been sent through the independent check or reproduced, and it is not added to the organisation's findings.
| Field | Type | Always present | Description |
|---|---|---|---|
ruleId | string | yes | The rule that raised it: the rule's own identifier, or an advisory id such as a CVE- or GHSA- id. |
title | string | yes | What the rule calls it. |
severity | string | yes | How serious the rule rates it. One of: critical, high, medium, low, info. |
file | string | no | The file, relative to the repository root, when the lead is about a place in the code. |
startLine | integer | no | The first line. |
endLine | integer | no | The last line. |
package | object | no | The affected package, for a lead about a dependency or an image. |
package.ecosystem | string | yes | The package ecosystem. |
package.name | string | yes | The package name. |
package.version | string | no | The version found. |
package.fixedVersion | string | no | The first version without the problem, when one is known. |
url | string | no | The address flagged, for a lead about a running application. |
snippet | string | no | A short excerpt of the text flagged, with credentials masked. |
message | string | yes | The rule's message, with credentials masked. A secret that was found is never given in full: a short masked preview and a fingerprint stand in for it. |
cwe | array of string | no | Weakness ids attached to the lead. |
cve | array of string | no | Vulnerability ids attached to the lead. |
confidence | number | yes | Confidence in the lead, from 0 to 0.75. It never reaches 1: a lead is not a proof. |
#ToolRunDocument
What a check produced when its result is a document and not a list of leads.
| Field | Type | Always present | Description |
|---|---|---|---|
kind | string | yes | What the document is: a software bill of materials, the sources a decompiler recovered, or the answer of a built-in tool (code-index, git-history) as text. |
format | string | yes | cyclonedx-json or spdx-json for an SBOM; java or csharp for decompiled sources; text for a built-in tool's answer. |
text | string | no | The document itself, for an SBOM or a built-in tool's answer. Credentials in it are masked. |
files | array of object | no | The recovered files, for decompiled sources. At most 300 files and 4 MB in all are kept. |
files[].path | string | yes | The file, relative to the output folder. |
files[].text | string | yes | Its text, with credentials masked. |
count | integer | yes | Components in the SBOM, or source files recovered (which can be more than are kept). |
Nullgap documentation