API reference
Fixes
Start a verified fix, see what it would cover, follow a fix run, and manage automatic fix rules.
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 |
|---|---|---|
| Start a fix run | POST /api/orgs/{org}/findings/{id}/remediate | write |
| Fix dependency advisories | POST /api/orgs/{org}/pentests/{id}/advisories/fix | write |
| Preview a fix | GET /api/orgs/{org}/findings/{id}/fix-scope | read |
| List automations | GET /api/orgs/{org}/automations | read |
| Create an automation | POST /api/orgs/{org}/automations | admin |
| Update an automation | PATCH /api/orgs/{org}/automations/{id} | admin |
| Delete an automation | DELETE /api/orgs/{org}/automations/{id} | admin |
| List fix runs | GET /api/orgs/{org}/automation-runs | read |
| Get a fix run | GET /api/orgs/{org}/automation-runs/{id} | read |
| Cancel a fix run | POST /api/orgs/{org}/automation-runs/{id}/cancel | admin |
#Start a fix run
POST /api/orgs/{org}/findings/{id}/remediate
Starts a run that writes a fix for the finding, verifies it on a fresh checkout, and delivers it: as a suggested change on the pull request under review where that fits, otherwise as a pull request. The run is queued and the answer comes back at once; follow it with the fix-run routes. If a fix run for this finding is already queued or running (one started for another finding may cover this one), that run is returned and no new one is started. A dependency finding always takes the other open advisories on the same package with it. A fix uses automation credits, except a dependency fix, which uses none. A run that fails through an error on Nullgap's side (the engine or the infrastructure) is not charged: anything it took is given back. A run that did its work and concluded it could not make a fix is charged for the work done.
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 id of the finding, such as fnd_8f3a2c9d1b4e. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
scope | string | no | finding (the default): fix this finding. class: fix every open place of the same flaw in the repository with one change, up to the limit the fix-scope route reports. |
as | string | no | Send pull_request to always open a pull request, even where a suggested change on the reviewed lines would do. |
confirmDecided | boolean | no | Required, as true, when the finding is no longer open (marked an accepted risk, a false positive or patched): it confirms the fix should be started against that decision. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"scope":"finding","as":"pull_request","confirmDecided":true}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/remediate"
Answer (200, application/json)
A AutomationRun object.
{
"id": "run_7c1e4a9b2d6f",
"orgId": "org_1d4c7b9a2e5f",
"automationId": "aut_9a3f5c1e7b2d",
"findingId": "fnd_8f3a2c9d1b4e",
"findingTitle": "SQL injection in order lookup",
"repoFullName": "acme/shop",
"status": "completed",
"outcome": "fixed",
"detail": "The second input still reproduced the flaw after three attempts.",
"prUrl": "https://github.com/acme/shop/pull/131",
"verified": true,
"prDraft": true,
"creditsUsed": 0,
"startedBy": "dana@acme.example",
"createdAt": "2026-11-16T09:10:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"kind": "finding",
"findingIds": [
"fnd_8f3a2c9d1b4e"
],
"report": {
"kind": "finding",
"places": [
{
"findingId": "fnd_8f3a2c9d1b4e",
"title": "SQL injection in order lookup",
"place": "src/orders.js:42",
"result": "verified",
"detail": "Reproduced before the fix; no longer reproduces after it.",
"proofBefore": {
"command": "node probe.js",
"exitCode": 0,
"summary": "Three rows were returned for a single order id."
}
}
],
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"tests": {
"command": "npm test",
"result": "passed",
"detail": "48 tests passed."
},
"notVerified": [
"The project has no tests for the orders module."
],
"refused": [
"The patch removes the endpoint instead of fixing it."
],
"dependencies": [
{
"ecosystem": "npm",
"name": "lodash",
"from": "4.17.20",
"to": "4.17.21",
"manifest": "package.json",
"action": "upgrade",
"fixes": [
"GHSA-35jh-r3h4-6jhm"
],
"malicious": false,
"note": "No fixed version has been published yet."
}
],
"verifiedAt": "4e8a1c3b5d7f9a0b2c4d6e8f0a1b3c5d7e9f1a2b",
"notProven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"review": "accepted",
"independentReview": true
}
},
"suggestion": {
"prNumber": 128,
"path": "src/orders.js",
"line": 42,
"native": true
},
"fallbackRunIds": [
"run_1f8b3d6a0c5e"
],
"pentestId": "pen_3d7a0f2c9b5e"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | scope or as is not one of its allowed values. |
| 402 | no_credits | The organisation has no automation credits left and the fix is not a dependency fix. |
| 404 | not_found | No finding with this id exists in the organisation. |
| 409 | fork_pr | The finding came from a pull request opened from a fork. Nullgap does not open fix pull requests for forks. |
| 409 | read_only_repository | The code was added by address or by upload, so there is no code host to open a pull request on. |
| 409 | no_fix_class | scope is class and no other open finding is the same flaw in this repository. |
| 409 | finding_decided | The finding is marked an accepted risk, a false positive or patched, and confirmDecided was not true. |
| 409 | repository_removed | The finding's repository is no longer connected to the organisation, so there is nothing to open a fix on. Connect it again and start the fix once more. |
#Fix dependency advisories
POST /api/orgs/{org}/pentests/{id}/advisories/fix
Starts a fix for the advisories a pentest lists against one package: the smallest manifest and lockfile change that clears them, tested where the project has tests, opened as a pull request on the default branch. Advisories are not findings, so the run has an empty findingId, an empty findingIds and carries pentestId instead. At most 20 advisories are taken into one run. If such a run is already queued or running for this pentest and package, that run is returned. This uses no automation credits.
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 id of the pentest, such as pen_3d7a0f2c9b5e. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
package | string | yes | The package name, exactly as the advisory gives it. |
manifest | string or null | no | Only the advisories found in this manifest or lockfile. Leave out, or send null, for the package wherever it is listed. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"package":"lodash","manifest":"package-lock.json"}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests/pen_3d7a0f2c9b5e/advisories/fix"
Answer (200, application/json)
A AutomationRun object.
{
"id": "run_7c1e4a9b2d6f",
"orgId": "org_1d4c7b9a2e5f",
"automationId": "aut_9a3f5c1e7b2d",
"findingId": "fnd_8f3a2c9d1b4e",
"findingTitle": "SQL injection in order lookup",
"repoFullName": "acme/shop",
"status": "completed",
"outcome": "fixed",
"detail": "The second input still reproduced the flaw after three attempts.",
"prUrl": "https://github.com/acme/shop/pull/131",
"verified": true,
"prDraft": true,
"creditsUsed": 0,
"startedBy": "dana@acme.example",
"createdAt": "2026-11-16T09:10:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"kind": "finding",
"findingIds": [
"fnd_8f3a2c9d1b4e"
],
"report": {
"kind": "finding",
"places": [
{
"findingId": "fnd_8f3a2c9d1b4e",
"title": "SQL injection in order lookup",
"place": "src/orders.js:42",
"result": "verified",
"detail": "Reproduced before the fix; no longer reproduces after it.",
"proofBefore": {
"command": "node probe.js",
"exitCode": 0,
"summary": "Three rows were returned for a single order id."
}
}
],
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"tests": {
"command": "npm test",
"result": "passed",
"detail": "48 tests passed."
},
"notVerified": [
"The project has no tests for the orders module."
],
"refused": [
"The patch removes the endpoint instead of fixing it."
],
"dependencies": [
{
"ecosystem": "npm",
"name": "lodash",
"from": "4.17.20",
"to": "4.17.21",
"manifest": "package.json",
"action": "upgrade",
"fixes": [
"GHSA-35jh-r3h4-6jhm"
],
"malicious": false,
"note": "No fixed version has been published yet."
}
],
"verifiedAt": "4e8a1c3b5d7f9a0b2c4d6e8f0a1b3c5d7e9f1a2b",
"notProven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"review": "accepted",
"independentReview": true
}
},
"suggestion": {
"prNumber": 128,
"path": "src/orders.js",
"line": 42,
"native": true
},
"fallbackRunIds": [
"run_1f8b3d6a0c5e"
],
"pentestId": "pen_3d7a0f2c9b5e"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | package is missing or longer than 214 characters, or manifest is not a string of up to 400 characters. |
| 404 | not_found | The pentest does not exist, its repository was removed, or it lists no advisory for that package (in that manifest, when one is given). |
| 409 | read_only_repository | The code was added by address or by upload, so there is no code host to open a pull request on. |
#Preview a fix
GET /api/orgs/{org}/findings/{id}/fix-scope
Says what a fix started from this finding would cover: the finding alone, the same flaw in several places (offered as one fix with scope: "class"), or the advisories on one package. It reads only and starts nothing. It does not check whether a fix can be started, so a finding that the start route would refuse still gets an answer here.
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 of the finding, such as fnd_8f3a2c9d1b4e. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings/fnd_8f3a2c9d1b4e/fix-scope"
Answer (200, application/json)
A FixScope object.
{
"kind": "class",
"findings": [
{
"id": "fnd_8f3a2c9d1b4e",
"title": "SQL injection in order lookup",
"severity": "high",
"place": "src/orders.js:42"
}
],
"max": 6
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No finding with this id exists in the organisation. |
#List automations
GET /api/orgs/{org}/automations
Returns every automation of the organisation as a plain array. There is no paging and no envelope.
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/automations"
Answer (200, application/json)
The automations.
An array of Automation.
[
{
"id": "aut_9a3f5c1e7b2d",
"orgId": "org_1d4c7b9a2e5f",
"name": "Fix critical and high findings",
"enabled": true,
"trigger": {
"event": "finding.created",
"severities": [
"critical"
],
"repoIds": [
"repo_4b7e1a9c2d3f"
]
},
"environment": {
"branches": [
"main"
],
"maxCreditsPerRun": null
},
"action": "remediation",
"allowUnverifiedFixes": false,
"notifier": {
"slack": false,
"emails": [
"dana@acme.example"
]
},
"createdAt": "2026-11-01T10:00:00.000Z",
"updatedAt": "2026-11-16T09:30:00.000Z"
}
]
#Create an automation
POST /api/orgs/{org}/automations
Creates a rule that starts a fix run whenever a matching finding is first reported. Only name is required. Left out, enabled is false, trigger covers critical and high findings in every repository, environment allows any branch with no cap of its own, and notifier tells nobody. Each of trigger, environment and notifier is taken as a whole: a part you leave out of one becomes empty, not its default.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | A name, up to 80 characters. |
enabled | boolean | no | Whether the automation runs. Must be true or false. |
trigger | object | no | Which new findings start a fix run. |
trigger.severities | array of string | no | The severities to act on, up to 5. Left out, the automation acts on none. |
trigger.repoIds | array of string | no | The repositories to act on, up to 500. Each must exist. Empty or left out means every repository. |
environment | object | no | The limits its runs work within. |
environment.branches | array of string | no | The branches a fix may be written against, up to 2. Empty or left out means any branch. |
environment.maxCreditsPerRun | number or null | no | The most automation credits one run may use: a number above zero. null or left out for no cap of its own. |
allowUnverifiedFixes | boolean | no | Let a run of this automation open a draft pull request for a fix that was not proven by reproducing the flaw. Must be true or false. Left out when creating, it is false: such a run then ends as failed. It has no effect while the organisation setting unverifiedFixes is off. |
notifier | object | no | Who is told how a run ended. |
notifier.slack | boolean | no | Whether to post the result to the connected Slack channel. Left out, it is false. |
notifier.emails | array of string | no | Who is sent the result by email, up to 20 addresses. Each must be the address of a member of the organisation; an address that leaves the organisation later is skipped when sending. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Fix critical and high findings","enabled":true,"trigger":{"severities":["critical"],"repoIds":["repo_4b7e1a9c2d3f"]},"environment":{"branches":["main"],"maxCreditsPerRun":null},"allowUnverifiedFixes":false,"notifier":{"slack":false,"emails":["dana@acme.example"]}}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/automations"
Answer (200, application/json)
A Automation object.
{
"id": "aut_9a3f5c1e7b2d",
"orgId": "org_1d4c7b9a2e5f",
"name": "Fix critical and high findings",
"enabled": true,
"trigger": {
"event": "finding.created",
"severities": [
"critical"
],
"repoIds": [
"repo_4b7e1a9c2d3f"
]
},
"environment": {
"branches": [
"main"
],
"maxCreditsPerRun": null
},
"action": "remediation",
"allowUnverifiedFixes": false,
"notifier": {
"slack": false,
"emails": [
"dana@acme.example"
]
},
"createdAt": "2026-11-01T10:00:00.000Z",
"updatedAt": "2026-11-16T09:30:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | name is missing, empty or longer than 80 characters, or another field does not have the form described. |
| 404 | not_found | A repository named in trigger.repoIds does not exist in the organisation. |
#Update an automation
PATCH /api/orgs/{org}/automations/{id}
Changes the fields that are sent and leaves the others as they are. Each of trigger, environment and notifier is replaced as a whole when sent: a part you leave out of one becomes empty, so send the complete object.
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 of the automation, such as aut_9a3f5c1e7b2d. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | A new name, up to 80 characters. |
enabled | boolean | no | Whether the automation runs. Must be true or false. |
trigger | object | no | Which new findings start a fix run. |
trigger.severities | array of string | no | The severities to act on, up to 5. Left out, the automation acts on none. |
trigger.repoIds | array of string | no | The repositories to act on, up to 500. Each must exist. Empty or left out means every repository. |
environment | object | no | The limits its runs work within. |
environment.branches | array of string | no | The branches a fix may be written against, up to 2. Empty or left out means any branch. |
environment.maxCreditsPerRun | number or null | no | The most automation credits one run may use: a number above zero. null or left out for no cap of its own. |
allowUnverifiedFixes | boolean | no | Let a run of this automation open a draft pull request for a fix that was not proven by reproducing the flaw. Must be true or false. Left out when creating, it is false: such a run then ends as failed. It has no effect while the organisation setting unverifiedFixes is off. |
notifier | object | no | Who is told how a run ended. |
notifier.slack | boolean | no | Whether to post the result to the connected Slack channel. Left out, it is false. |
notifier.emails | array of string | no | Who is sent the result by email, up to 20 addresses. Each must be the address of a member of the organisation; an address that leaves the organisation later is skipped when sending. |
Example request
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Fix critical findings","enabled":true,"trigger":{"severities":["critical"],"repoIds":["repo_4b7e1a9c2d3f"]},"environment":{"branches":["main"],"maxCreditsPerRun":null},"allowUnverifiedFixes":false,"notifier":{"slack":false,"emails":["dana@acme.example"]}}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/automations/aut_9a3f5c1e7b2d"
Answer (200, application/json)
A Automation object.
{
"id": "aut_9a3f5c1e7b2d",
"orgId": "org_1d4c7b9a2e5f",
"name": "Fix critical and high findings",
"enabled": true,
"trigger": {
"event": "finding.created",
"severities": [
"critical"
],
"repoIds": [
"repo_4b7e1a9c2d3f"
]
},
"environment": {
"branches": [
"main"
],
"maxCreditsPerRun": null
},
"action": "remediation",
"allowUnverifiedFixes": false,
"notifier": {
"slack": false,
"emails": [
"dana@acme.example"
]
},
"createdAt": "2026-11-01T10:00:00.000Z",
"updatedAt": "2026-11-16T09:30:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | A field does not have the form described. |
| 404 | not_found | The automation does not exist, or a repository named in trigger.repoIds does not exist in the organisation. |
#Delete an automation
DELETE /api/orgs/{org}/automations/{id}
Removes the automation. Runs it already started are kept and carry on.
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 of the automation, such as aut_9a3f5c1e7b2d. |
Example request
curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/automations/aut_9a3f5c1e7b2d"
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | The automation does not exist. |
#List fix runs
GET /api/orgs/{org}/automation-runs
Lists the organisation’s fix runs, whoever or whatever started them: a person, an API key or an automation. There are no filters.
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 |
|---|---|---|---|
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/automation-runs?limit=20"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
items | array of AutomationRun | yes | The fix runs, at most limit of them. |
total | integer | yes | How many match in all, before limit and offset. |
{
"items": [
{
"id": "run_7c1e4a9b2d6f",
"orgId": "org_1d4c7b9a2e5f",
"automationId": "aut_9a3f5c1e7b2d",
"findingId": "fnd_8f3a2c9d1b4e",
"findingTitle": "SQL injection in order lookup",
"repoFullName": "acme/shop",
"status": "completed",
"outcome": "fixed",
"detail": "The second input still reproduced the flaw after three attempts.",
"prUrl": "https://github.com/acme/shop/pull/131",
"verified": true,
"prDraft": true,
"creditsUsed": 0,
"startedBy": "dana@acme.example",
"createdAt": "2026-11-16T09:10:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"kind": "finding",
"findingIds": [
"fnd_8f3a2c9d1b4e"
],
"report": {
"kind": "finding",
"places": [
{
"findingId": "fnd_8f3a2c9d1b4e",
"title": "SQL injection in order lookup",
"place": "src/orders.js:42",
"result": "verified",
"detail": "Reproduced before the fix; no longer reproduces after it.",
"proofBefore": {
"command": "node probe.js",
"exitCode": 0,
"summary": "Three rows were returned for a single order id."
}
}
],
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"tests": {
"command": "npm test",
"result": "passed",
"detail": "48 tests passed."
},
"notVerified": [
"The project has no tests for the orders module."
],
"refused": [
"The patch removes the endpoint instead of fixing it."
],
"dependencies": [
{
"ecosystem": "npm",
"name": "lodash",
"from": "4.17.20",
"to": "4.17.21",
"manifest": "package.json",
"action": "upgrade",
"fixes": [
"GHSA-35jh-r3h4-6jhm"
],
"malicious": false,
"note": "No fixed version has been published yet."
}
],
"verifiedAt": "4e8a1c3b5d7f9a0b2c4d6e8f0a1b3c5d7e9f1a2b",
"notProven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"review": "accepted",
"independentReview": true
}
},
"suggestion": {
"prNumber": 128,
"path": "src/orders.js",
"line": 42,
"native": true
},
"fallbackRunIds": [
"run_1f8b3d6a0c5e"
],
"pentestId": "pen_3d7a0f2c9b5e"
}
],
"total": 42
}
#Get a fix run
GET /api/orgs/{org}/automation-runs/{id}
Returns one fix run with everything it checked: each check (passed, failed or not run), each attempt at the patch, and what could not be verified. Poll it after starting a fix until status is no longer queued or running.
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 of the fix run, such as run_7c1e4a9b2d6f. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/automation-runs/run_7c1e4a9b2d6f"
Answer (200, application/json)
A AutomationRun object.
{
"id": "run_7c1e4a9b2d6f",
"orgId": "org_1d4c7b9a2e5f",
"automationId": "aut_9a3f5c1e7b2d",
"findingId": "fnd_8f3a2c9d1b4e",
"findingTitle": "SQL injection in order lookup",
"repoFullName": "acme/shop",
"status": "completed",
"outcome": "fixed",
"detail": "The second input still reproduced the flaw after three attempts.",
"prUrl": "https://github.com/acme/shop/pull/131",
"verified": true,
"prDraft": true,
"creditsUsed": 0,
"startedBy": "dana@acme.example",
"createdAt": "2026-11-16T09:10:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"kind": "finding",
"findingIds": [
"fnd_8f3a2c9d1b4e"
],
"report": {
"kind": "finding",
"places": [
{
"findingId": "fnd_8f3a2c9d1b4e",
"title": "SQL injection in order lookup",
"place": "src/orders.js:42",
"result": "verified",
"detail": "Reproduced before the fix; no longer reproduces after it.",
"proofBefore": {
"command": "node probe.js",
"exitCode": 0,
"summary": "Three rows were returned for a single order id."
}
}
],
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"tests": {
"command": "npm test",
"result": "passed",
"detail": "48 tests passed."
},
"notVerified": [
"The project has no tests for the orders module."
],
"refused": [
"The patch removes the endpoint instead of fixing it."
],
"dependencies": [
{
"ecosystem": "npm",
"name": "lodash",
"from": "4.17.20",
"to": "4.17.21",
"manifest": "package.json",
"action": "upgrade",
"fixes": [
"GHSA-35jh-r3h4-6jhm"
],
"malicious": false,
"note": "No fixed version has been published yet."
}
],
"verifiedAt": "4e8a1c3b5d7f9a0b2c4d6e8f0a1b3c5d7e9f1a2b",
"notProven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"review": "accepted",
"independentReview": true
}
},
"suggestion": {
"prNumber": 128,
"path": "src/orders.js",
"line": 42,
"native": true
},
"fallbackRunIds": [
"run_1f8b3d6a0c5e"
],
"pentestId": "pen_3d7a0f2c9b5e"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No fix run with this id exists in the organisation. |
#Cancel a fix run
POST /api/orgs/{org}/automation-runs/{id}/cancel
Stops a queued or running fix run. A queued run is cancelled at once; a running one stops at its next step. The run is charged in automation credits for the work it did before it stopped, never more than its per-run cap; nothing more is taken. A run that had not started is not charged. Takes no body.
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 of the fix run, such as run_7c1e4a9b2d6f. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/automation-runs/run_7c1e4a9b2d6f/cancel"
Answer (200, application/json)
A AutomationRun object.
{
"id": "run_7c1e4a9b2d6f",
"orgId": "org_1d4c7b9a2e5f",
"automationId": "aut_9a3f5c1e7b2d",
"findingId": "fnd_8f3a2c9d1b4e",
"findingTitle": "SQL injection in order lookup",
"repoFullName": "acme/shop",
"status": "completed",
"outcome": "fixed",
"detail": "The second input still reproduced the flaw after three attempts.",
"prUrl": "https://github.com/acme/shop/pull/131",
"verified": true,
"prDraft": true,
"creditsUsed": 0,
"startedBy": "dana@acme.example",
"createdAt": "2026-11-16T09:10:00.000Z",
"finishedAt": "2026-11-16T09:30:00.000Z",
"kind": "finding",
"findingIds": [
"fnd_8f3a2c9d1b4e"
],
"report": {
"kind": "finding",
"places": [
{
"findingId": "fnd_8f3a2c9d1b4e",
"title": "SQL injection in order lookup",
"place": "src/orders.js:42",
"result": "verified",
"detail": "Reproduced before the fix; no longer reproduces after it.",
"proofBefore": {
"command": "node probe.js",
"exitCode": 0,
"summary": "Three rows were returned for a single order id."
}
}
],
"checks": [
{
"name": "probe",
"status": "passed",
"detail": "The probe no longer reproduces on the patched code.",
"place": "src/orders.js:42"
}
],
"attempts": [
{
"attempt": 1,
"verified": true,
"reason": "The second input still reproduced the flaw.",
"proposed": true,
"files": [
"src/orders.js"
]
}
],
"tests": {
"command": "npm test",
"result": "passed",
"detail": "48 tests passed."
},
"notVerified": [
"The project has no tests for the orders module."
],
"refused": [
"The patch removes the endpoint instead of fixing it."
],
"dependencies": [
{
"ecosystem": "npm",
"name": "lodash",
"from": "4.17.20",
"to": "4.17.21",
"manifest": "package.json",
"action": "upgrade",
"fixes": [
"GHSA-35jh-r3h4-6jhm"
],
"malicious": false,
"note": "No fixed version has been published yet."
}
],
"verifiedAt": "4e8a1c3b5d7f9a0b2c4d6e8f0a1b3c5d7e9f1a2b",
"notProven": {
"reason": "Nullgap AI declined to write a probe for this finding",
"review": "accepted",
"independentReview": true
}
},
"suggestion": {
"prNumber": 128,
"path": "src/orders.js",
"line": 42,
"native": true
},
"fallbackRunIds": [
"run_1f8b3d6a0c5e"
],
"pentestId": "pen_3d7a0f2c9b5e"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No fix run with this id exists in the organisation. |
| 409 | not_running | The fix run is neither queued nor running. |
#Objects
The objects the operations above take and return.
#AutomationRun
One fix run: an attempt to write a fix, verify it, and deliver it as a pull request or a suggested change. What became of the pull request afterwards is not part of the answer.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id of the fix run. |
orgId | string | yes | The organisation it belongs to. |
automationId | string or null | yes | The automation that started it. null when a person or an API key started it. |
findingId | string | yes | The finding the run was started from. An empty string on a fix for a pentest’s dependency advisories, which are not findings (see pentestId). |
findingTitle | string | yes | The title of that finding, or the package and advisory for an advisory fix. |
repoFullName | string | yes | The repository. |
status | string | yes | Where the run stands. One of: queued, running, completed, failed, skipped, cancelled. |
outcome | string or null | yes | How it ended. fixed: a verified fix was delivered. unverified: the flaw could not be reproduced, so a fix was proposed as a draft pull request without proof, checked by tests and an independent review only; it is not a verified fix. no_fix_needed: the code turned out not to need one. false_positive: the attempt showed the finding is not real. failed: no verified fix could be made. null until the run has ended. |
detail | string or null | yes | Why no fix was made, or why the run failed. |
prUrl | string or null | yes | The pull request the run opened. null when it opened none. |
verified | boolean | no | True only when the outcome is fixed: the fix was proven by reproducing the flaw before it and not after it. False for every other outcome, unverified included. Absent on runs that ended before the field existed. |
prDraft | boolean | no | Set on a fix that was not proven: true when its pull request was opened as a draft, false when the code host or repository has no drafts and an ordinary pull request titled "[Not proven] ..." was opened instead. |
creditsUsed | number | yes | The automation credits the run used. A dependency fix uses none. |
startedBy | string | yes | Who started it: an email address, api-key:<name>, or automation:<name>. |
createdAt | string | yes | When it was started. |
finishedAt | string or null | yes | When it ended. null while it is queued or running. |
kind | string | no | What the run fixes. finding: one finding. class: the same flaw in several places, fixed with one change. dependency: the advisories on one package, cleared by one manifest and lockfile change. Absent on older runs, which fix one finding. |
findingIds | array of string | no | Every finding the run covers, findingId first. Empty for an advisory fix. Absent on older runs. |
report | FixReport or null | no | |
suggestion | object or null | no | Set when the fix was posted as a suggested change on the pull request under review instead of as a pull request of its own. |
suggestion.prNumber | integer | yes | The pull request the suggestion was posted on. |
suggestion.path | string | yes | The file. |
suggestion.line | integer | yes | The line. |
suggestion.native | boolean | yes | True when it was posted as the code host’s own one-click suggested change, false when as a comment carrying the change. |
fallbackRunIds | array of string | no | When a combined fix could not be verified: the separate runs started in its place, one per finding. |
pentestId | string or null | no | Set on a fix for a pentest’s dependency advisories: the pentest. |
#FixScope
What a fix started from one finding would cover.
| Field | Type | Always present | Description |
|---|---|---|---|
kind | string | yes | What a fix would cover. finding: one finding. class: the same flaw in several places, fixed with one change. dependency: the advisories on one package, cleared by one manifest and lockfile change. |
findings | array of object | yes | The findings one fix would cover. The first is the finding asked about. |
findings[].id | string | yes | The finding id. |
findings[].title | string | yes | Its title. |
findings[].severity | string | yes | Its severity. One of: critical, high, medium, low, info. |
findings[].place | string | yes | file:line, or package@version for a dependency. Empty when the finding has no location. |
max | integer | yes | The most places one combined fix covers. |
#Automation
A standing rule that starts a fix run when a matching finding is first reported.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The id of the automation. |
orgId | string | yes | The organisation it belongs to. |
name | string | yes | Its name, up to 80 characters. |
enabled | boolean | yes | Whether it runs. A new automation is off until switched on. |
trigger | object | yes | Which new findings start a fix run. |
trigger.event | string | yes | What sets it off. Always a new finding. |
trigger.severities | array of string | yes | The severities it acts on. |
trigger.repoIds | array of string | yes | The repositories it acts on. Empty means every repository. |
environment | object | yes | The limits its runs work within. |
environment.branches | array of string | yes | The branches a fix may be written against. Empty means any branch. A run for another branch fails. |
environment.maxCreditsPerRun | number or null | yes | The most automation credits one run may use. null for no cap of its own. |
action | string | yes | What it does. Always a fix run. |
allowUnverifiedFixes | boolean | no | Whether a run of this automation may open a draft pull request for a fix that was not proven by reproducing the flaw. False, or absent on an automation saved before the field existed: such a run ends as failed instead. |
notifier | object | yes | Who is told how a run ended. |
notifier.slack | boolean | yes | Whether to post the result to the connected Slack channel. |
notifier.emails | array of string | yes | Who is sent the result by email. |
createdAt | string | yes | When it was created. |
updatedAt | string | yes | When it was last changed. |
#FixReport
Everything a fix run checked. A check that is not_run was not made; it is never counted as passed.
| Field | Type | Always present | Description |
|---|---|---|---|
kind | string | yes | What the run fixes. finding: one finding. class: the same flaw in several places, fixed with one change. dependency: the advisories on one package, cleared by one manifest and lockfile change. |
places | array of FixPlace | yes | Every place the run looked at. |
checks | array of FixCheck | yes | Every check that was made, or could not be made. |
attempts | array of PatchAttempt | yes | Every try at the patch, oldest first. Empty for a dependency fix, which is computed and not written. |
tests | object | yes | The project’s own tests. |
tests.command | string or null | yes | The project’s test command. null when the project has none. |
tests.result | string | yes | What running it showed. One of: passed, failed, not_run. |
tests.detail | string | yes | One sentence about the result. |
notVerified | array of string | yes | What this run could not check. Empty when everything that exists was checked. |
refused | array of string | yes | Why the patch was refused, when it was. Empty otherwise. |
dependencies | array of DependencyChange | no | For a dependency fix: each package changed. |
verifiedAt | string | no | The commit the fix was written and verified against. |
notProven | object | no | Present only when the fix was written without reproducing the flaw. The run is then a proposal, never a verified fix, whatever its other checks say. |
notProven.reason | string | yes | Why the flaw was not reproduced. |
notProven.review | string | yes | What the review of the change said. not_run: it gave no usable verdict, or an earlier check stopped the run. |
notProven.independentReview | boolean | yes | True when the review was done by a different Nullgap AI model from the one that wrote the change. |
#FixPlace
One place a fix run looked at. A run for a single finding has one.
| Field | Type | Always present | Description |
|---|---|---|---|
findingId | string | yes | The finding at this place. |
title | string | yes | Its title. |
place | string | yes | file:line, or package@version for a dependency. |
result | string | yes | verified: reproduced before the fix, and the probe, a second input and the control all pass after it. covered: changed by the same fix but not checked by reproduction here (detail says why). left_out: a probe ran here and the code behaved safely, so the fix does not include this place. |
detail | string | yes | What was seen at this place. |
proofBefore | object | no | The reproduction before the fix. Absent when nothing reproduced. |
proofBefore.command | string | yes | The command that reproduced the flaw before the fix. |
proofBefore.exitCode | integer or null | yes | What it exited with. |
proofBefore.summary | string | yes | What it showed. |
#FixCheck
One named check a fix went through.
| Field | Type | Always present | Description |
|---|---|---|---|
name | string | yes | Which check. applies: the patch applies to a fresh checkout. scope: the patch widens no risk and stays on files related to the finding. probe: the probe that reproduced the flaw no longer does. variant: a second input for the same flaw no longer reproduces either. control: ordinary use still works. tests: the project’s own tests pass. For a fix proposed without reproducing the flaw (outcome unverified), the three probe runs are not_run and two more checks are made: build (the changed files still parse) and review (an independent review of the change accepted that it closes the flaw without changing other behaviour). For a dependency fix, in place of the three probe runs: lockfile (the lockfile was regenerated from the edited manifest in the sandbox, with install scripts off) and resolved (the affected version is no longer in the manifest or the lockfile). |
status | string | yes | not_run is never a pass: the check could not be made, and detail says why. |
detail | string | yes | One plain sentence: what was seen, or why the check could not run. |
place | string | no | For a fix that covers several places: the one this check belongs to, as file:line. |
#PatchAttempt
One try at writing a fix. A run makes a bounded number of them, each told why the previous one failed.
| Field | Type | Always present | Description |
|---|---|---|---|
attempt | integer | yes | Which try this was, counted from 1. |
verified | boolean | yes | Whether this attempt passed every check. |
reason | string | no | Why this attempt was not accepted. Absent when it was. |
proposed | boolean | no | Only on a fix written without reproducing the flaw: this attempt passed every check that needs no probe and was accepted as a proposal. verified is still false. |
files | array of string | yes | The files this attempt changed. |
#DependencyChange
One dependency a fix changes.
| Field | Type | Always present | Description |
|---|---|---|---|
ecosystem | string | yes | The package registry. |
name | string | yes | The package. |
from | string | yes | The version before. |
to | string or null | yes | The version after. null when the package is removed. |
manifest | string | yes | The manifest that was changed. |
action | string | yes | upgrade: a newer range in the manifest. override: a pin for a package that comes in through another. pin: an exact known-good version. remove: taken out. skipped: not changed, see note. |
fixes | array of string | yes | The advisories this change clears. |
malicious | boolean | yes | True when the package was flagged as malicious. |
note | string | no | Anything to know about this change, such as why it was skipped. |
Nullgap documentation