Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
Run an automated checkPOST /api/orgs/{org}/tool-runswrite
List tool runsGET /api/orgs/{org}/tool-runsread
Get a tool runGET /api/orgs/{org}/tool-runs/{id}read
Get a tool run's logGET /api/orgs/{org}/tool-runs/{id}/logsread
Cancel a tool runPOST /api/orgs/{org}/tool-runs/{id}/cancelwrite

#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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
toolstringyesThe check's id, as the list gives it. Up to 80 characters.
repoIdstringnoThe repository or uploaded archive to read. Required for a check that reads files; not accepted by one that tests an address.
refstringnoThe branch, tag or commit to read. Default: the repository's default branch.
pathsarray of stringnoFolders or files to limit the run to, at most 50. They must be relative and stay inside the repository. Only with repoId.
urlstringnoThe 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.
optionsobjectnoThe 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.
liveStateChangingbooleannoPermit requests that change data on the target. Only for a check that needs it, and only with disposableConfirmed.
disposableConfirmedbooleannoConfirms 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

StatusCodeWhen
400not_configuredThe sandboxed checks are not switched on for this server.
400bad_requestThe 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.
400confirmation_requiredliveStateChanging was sent without disposableConfirmed.
400out_of_scopeThe address is private or loopback, or is not on the organisation's scope list.
403insufficient_scopeThe check tests a running application and the caller is not an admin (or the key lacks the admin scope).
403tool_disabledThe check is switched off on this server. The message says why.
403org_suspendedThe workspace is suspended. Nothing new can be started until it is resumed.
403tool_refusedThe 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.
404unknown_toolThere is no check with that id. The message lists the ids that exist.
404not_foundThe organisation has no repository with the repoId sent.
429too_manyThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
toolstringnoOnly runs of this check.
statusstringnoOnly runs in this status. One of: queued, running, completed, failed, cancelled.
limitintegernoHow many to return, 1 to 200. Default 50.
offsetintegernoHow 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)

FieldTypeAlways presentDescription
itemsarray of ToolRunyesTool runs, at most limit of them.
totalintegeryesHow 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

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

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

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

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

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

StatusCodeWhen
404not_foundNo tool run of this organisation has that id.
400not_runningThe 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.

FieldTypeAlways presentDescription
idstringyesThe run id.
orgIdstringyesThe organisation it belongs to.
toolstringyesThe check's id. A run started before checks were named by capability is shown under its capability.
toolTitlestringyesThe check's name.
categorystringyesThe capability, or built-in.
targetToolRunTargetyes
statusstringyesWhere the run stands. One of: queued, running, completed, failed, cancelled.
stateChangingbooleanyesWhether requests that change data on the target were permitted for this run. Always false for a run on a repository.
createdBystringyesWho started it: a person, or the name of an API key.
createdAtstringyesWhen it was asked for.
startedAtstring or nullyesWhen work began.
finishedAtstring or nullyesWhen it ended.
errorstring or nullyesWhy the run failed, in words fit to show.
leadsCountintegeryesHow many leads were kept.
truncatedbooleanyesWhether a size limit cut the result short. At most 1000 leads are kept from one run.
notestring or nullyesWhat was cut, or why there is nothing.
toolFailurestring or nullyesSet 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.
networkobject or nullyesFor a run against a running application: what was sent. Null for a run on a repository.
network.requestsintegeryesRequests the scope proxy let through.
network.refusedintegeryesRequests it refused because they left the scope.
hasDocumentbooleanyesWhether the run produced a document (an SBOM, or decompiled sources).
leadsarray of ToolLeadnoThe leads. Present only when one run is read, not in lists or in the answer to starting a run.
documentToolRunDocument or nullnoThe document, or null. Present only when one run is read.

#LogLine

One line of a run's progress log.

FieldTypeAlways presentDescription
atstringyesWhen the line was written.
levelstringyesHow serious the line is. One of: info, warn, error.
messagestringyesWhat 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.

FieldTypeAlways presentDescription
ruleIdstringyesThe rule that raised it: the rule's own identifier, or an advisory id such as a CVE- or GHSA- id.
titlestringyesWhat the rule calls it.
severitystringyesHow serious the rule rates it. One of: critical, high, medium, low, info.
filestringnoThe file, relative to the repository root, when the lead is about a place in the code.
startLineintegernoThe first line.
endLineintegernoThe last line.
packageobjectnoThe affected package, for a lead about a dependency or an image.
package.ecosystemstringyesThe package ecosystem.
package.namestringyesThe package name.
package.versionstringnoThe version found.
package.fixedVersionstringnoThe first version without the problem, when one is known.
urlstringnoThe address flagged, for a lead about a running application.
snippetstringnoA short excerpt of the text flagged, with credentials masked.
messagestringyesThe 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.
cwearray of stringnoWeakness ids attached to the lead.
cvearray of stringnoVulnerability ids attached to the lead.
confidencenumberyesConfidence 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.

FieldTypeAlways presentDescription
kindstringyesWhat 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.
formatstringyescyclonedx-json or spdx-json for an SBOM; java or csharp for decompiled sources; text for a built-in tool's answer.
textstringnoThe document itself, for an SBOM or a built-in tool's answer. Credentials in it are masked.
filesarray of objectnoThe recovered files, for decompiled sources. At most 300 files and 4 MB in all are kept.
files[].pathstringyesThe file, relative to the output folder.
files[].textstringyesIts text, with credentials masked.
countintegeryesComponents in the SBOM, or source files recovered (which can be more than are kept).

Nullgap documentation