Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
Start a fix runPOST /api/orgs/{org}/findings/{id}/remediatewrite
Fix dependency advisoriesPOST /api/orgs/{org}/pentests/{id}/advisories/fixwrite
Preview a fixGET /api/orgs/{org}/findings/{id}/fix-scoperead
List automationsGET /api/orgs/{org}/automationsread
Create an automationPOST /api/orgs/{org}/automationsadmin
Update an automationPATCH /api/orgs/{org}/automations/{id}admin
Delete an automationDELETE /api/orgs/{org}/automations/{id}admin
List fix runsGET /api/orgs/{org}/automation-runsread
Get a fix runGET /api/orgs/{org}/automation-runs/{id}read
Cancel a fix runPOST /api/orgs/{org}/automation-runs/{id}/canceladmin

#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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the finding, such as fnd_8f3a2c9d1b4e.

Request body (application/json)

FieldTypeRequiredDescription
scopestringnofinding (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.
asstringnoSend pull_request to always open a pull request, even where a suggested change on the reviewed lines would do.
confirmDecidedbooleannoRequired, 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

StatusCodeWhen
400bad_requestscope or as is not one of its allowed values.
402no_creditsThe organisation has no automation credits left and the fix is not a dependency fix.
404not_foundNo finding with this id exists in the organisation.
409fork_prThe finding came from a pull request opened from a fork. Nullgap does not open fix pull requests for forks.
409read_only_repositoryThe code was added by address or by upload, so there is no code host to open a pull request on.
409no_fix_classscope is class and no other open finding is the same flaw in this repository.
409finding_decidedThe finding is marked an accepted risk, a false positive or patched, and confirmDecided was not true.
409repository_removedThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the pentest, such as pen_3d7a0f2c9b5e.

Request body (application/json)

FieldTypeRequiredDescription
packagestringyesThe package name, exactly as the advisory gives it.
manifeststring or nullnoOnly 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

StatusCodeWhen
400bad_requestpackage is missing or longer than 214 characters, or manifest is not a string of up to 400 characters.
404not_foundThe pentest does not exist, its repository was removed, or it lists no advisory for that package (in that manifest, when one is given).
409read_only_repositoryThe 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

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

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

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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
namestringyesA name, up to 80 characters.
enabledbooleannoWhether the automation runs. Must be true or false.
triggerobjectnoWhich new findings start a fix run.
trigger.severitiesarray of stringnoThe severities to act on, up to 5. Left out, the automation acts on none.
trigger.repoIdsarray of stringnoThe repositories to act on, up to 500. Each must exist. Empty or left out means every repository.
environmentobjectnoThe limits its runs work within.
environment.branchesarray of stringnoThe branches a fix may be written against, up to 2. Empty or left out means any branch.
environment.maxCreditsPerRunnumber or nullnoThe most automation credits one run may use: a number above zero. null or left out for no cap of its own.
allowUnverifiedFixesbooleannoLet 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.
notifierobjectnoWho is told how a run ended.
notifier.slackbooleannoWhether to post the result to the connected Slack channel. Left out, it is false.
notifier.emailsarray of stringnoWho 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

StatusCodeWhen
400bad_requestname is missing, empty or longer than 80 characters, or another field does not have the form described.
404not_foundA 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id of the automation, such as aut_9a3f5c1e7b2d.

Request body (application/json)

FieldTypeRequiredDescription
namestringnoA new name, up to 80 characters.
enabledbooleannoWhether the automation runs. Must be true or false.
triggerobjectnoWhich new findings start a fix run.
trigger.severitiesarray of stringnoThe severities to act on, up to 5. Left out, the automation acts on none.
trigger.repoIdsarray of stringnoThe repositories to act on, up to 500. Each must exist. Empty or left out means every repository.
environmentobjectnoThe limits its runs work within.
environment.branchesarray of stringnoThe branches a fix may be written against, up to 2. Empty or left out means any branch.
environment.maxCreditsPerRunnumber or nullnoThe most automation credits one run may use: a number above zero. null or left out for no cap of its own.
allowUnverifiedFixesbooleannoLet 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.
notifierobjectnoWho is told how a run ended.
notifier.slackbooleannoWhether to post the result to the connected Slack channel. Left out, it is false.
notifier.emailsarray of stringnoWho 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

StatusCodeWhen
400bad_requestA field does not have the form described.
404not_foundThe 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

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

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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
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/automation-runs?limit=20"

Answer (200, application/json)

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

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

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

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

StatusCodeWhen
404not_foundNo fix run with this id exists in the organisation.
409not_runningThe 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.

FieldTypeAlways presentDescription
idstringyesThe id of the fix run.
orgIdstringyesThe organisation it belongs to.
automationIdstring or nullyesThe automation that started it. null when a person or an API key started it.
findingIdstringyesThe finding the run was started from. An empty string on a fix for a pentest’s dependency advisories, which are not findings (see pentestId).
findingTitlestringyesThe title of that finding, or the package and advisory for an advisory fix.
repoFullNamestringyesThe repository.
statusstringyesWhere the run stands. One of: queued, running, completed, failed, skipped, cancelled.
outcomestring or nullyesHow 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.
detailstring or nullyesWhy no fix was made, or why the run failed.
prUrlstring or nullyesThe pull request the run opened. null when it opened none.
verifiedbooleannoTrue 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.
prDraftbooleannoSet 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.
creditsUsednumberyesThe automation credits the run used. A dependency fix uses none.
startedBystringyesWho started it: an email address, api-key:<name>, or automation:<name>.
createdAtstringyesWhen it was started.
finishedAtstring or nullyesWhen it ended. null while it is queued or running.
kindstringnoWhat 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.
findingIdsarray of stringnoEvery finding the run covers, findingId first. Empty for an advisory fix. Absent on older runs.
reportFixReport or nullno
suggestionobject or nullnoSet 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.prNumberintegeryesThe pull request the suggestion was posted on.
suggestion.pathstringyesThe file.
suggestion.lineintegeryesThe line.
suggestion.nativebooleanyesTrue when it was posted as the code host’s own one-click suggested change, false when as a comment carrying the change.
fallbackRunIdsarray of stringnoWhen a combined fix could not be verified: the separate runs started in its place, one per finding.
pentestIdstring or nullnoSet on a fix for a pentest’s dependency advisories: the pentest.

#FixScope

What a fix started from one finding would cover.

FieldTypeAlways presentDescription
kindstringyesWhat 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.
findingsarray of objectyesThe findings one fix would cover. The first is the finding asked about.
findings[].idstringyesThe finding id.
findings[].titlestringyesIts title.
findings[].severitystringyesIts severity. One of: critical, high, medium, low, info.
findings[].placestringyesfile:line, or package@version for a dependency. Empty when the finding has no location.
maxintegeryesThe most places one combined fix covers.

#Automation

A standing rule that starts a fix run when a matching finding is first reported.

FieldTypeAlways presentDescription
idstringyesThe id of the automation.
orgIdstringyesThe organisation it belongs to.
namestringyesIts name, up to 80 characters.
enabledbooleanyesWhether it runs. A new automation is off until switched on.
triggerobjectyesWhich new findings start a fix run.
trigger.eventstringyesWhat sets it off. Always a new finding.
trigger.severitiesarray of stringyesThe severities it acts on.
trigger.repoIdsarray of stringyesThe repositories it acts on. Empty means every repository.
environmentobjectyesThe limits its runs work within.
environment.branchesarray of stringyesThe branches a fix may be written against. Empty means any branch. A run for another branch fails.
environment.maxCreditsPerRunnumber or nullyesThe most automation credits one run may use. null for no cap of its own.
actionstringyesWhat it does. Always a fix run.
allowUnverifiedFixesbooleannoWhether 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.
notifierobjectyesWho is told how a run ended.
notifier.slackbooleanyesWhether to post the result to the connected Slack channel.
notifier.emailsarray of stringyesWho is sent the result by email.
createdAtstringyesWhen it was created.
updatedAtstringyesWhen 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.

FieldTypeAlways presentDescription
kindstringyesWhat 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.
placesarray of FixPlaceyesEvery place the run looked at.
checksarray of FixCheckyesEvery check that was made, or could not be made.
attemptsarray of PatchAttemptyesEvery try at the patch, oldest first. Empty for a dependency fix, which is computed and not written.
testsobjectyesThe project’s own tests.
tests.commandstring or nullyesThe project’s test command. null when the project has none.
tests.resultstringyesWhat running it showed. One of: passed, failed, not_run.
tests.detailstringyesOne sentence about the result.
notVerifiedarray of stringyesWhat this run could not check. Empty when everything that exists was checked.
refusedarray of stringyesWhy the patch was refused, when it was. Empty otherwise.
dependenciesarray of DependencyChangenoFor a dependency fix: each package changed.
verifiedAtstringnoThe commit the fix was written and verified against.
notProvenobjectnoPresent 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.reasonstringyesWhy the flaw was not reproduced.
notProven.reviewstringyesWhat the review of the change said. not_run: it gave no usable verdict, or an earlier check stopped the run.
notProven.independentReviewbooleanyesTrue 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.

FieldTypeAlways presentDescription
findingIdstringyesThe finding at this place.
titlestringyesIts title.
placestringyesfile:line, or package@version for a dependency.
resultstringyesverified: 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.
detailstringyesWhat was seen at this place.
proofBeforeobjectnoThe reproduction before the fix. Absent when nothing reproduced.
proofBefore.commandstringyesThe command that reproduced the flaw before the fix.
proofBefore.exitCodeinteger or nullyesWhat it exited with.
proofBefore.summarystringyesWhat it showed.

#FixCheck

One named check a fix went through.

FieldTypeAlways presentDescription
namestringyesWhich 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).
statusstringyesnot_run is never a pass: the check could not be made, and detail says why.
detailstringyesOne plain sentence: what was seen, or why the check could not run.
placestringnoFor 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.

FieldTypeAlways presentDescription
attemptintegeryesWhich try this was, counted from 1.
verifiedbooleanyesWhether this attempt passed every check.
reasonstringnoWhy this attempt was not accepted. Absent when it was.
proposedbooleannoOnly 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.
filesarray of stringyesThe files this attempt changed.

#DependencyChange

One dependency a fix changes.

FieldTypeAlways presentDescription
ecosystemstringyesThe package registry.
namestringyesThe package.
fromstringyesThe version before.
tostring or nullyesThe version after. null when the package is removed.
manifeststringyesThe manifest that was changed.
actionstringyesupgrade: 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.
fixesarray of stringyesThe advisories this change clears.
maliciousbooleanyesTrue when the package was flagged as malicious.
notestringnoAnything to know about this change, such as why it was skipped.

Nullgap documentation