Nullgap.dev Docs

API reference

Background jobs

See background jobs that failed and retry them.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
List background jobsGET /api/orgs/{org}/jobsadmin
Retry a background jobPOST /api/orgs/{org}/jobs/{id}/retryadmin

#List background jobs

GET /api/orgs/{org}/jobs

Answers the organisation's background jobs, newest first: the work behind reviews, pentests, fix runs and threat models. Use it to find work that failed or gave up.

Who may call it: An API key with the admin scope.

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.
statusstringnoOnly jobs in this state. One of: queued, running, completed, failed, cancelled, dead.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/jobs?limit=20"

Answer (200, application/json)

FieldTypeAlways presentDescription
itemsarray of JobInfoyesThe matching jobs, at most limit of them.
totalintegeryesHow many match in all, before limit and offset.
{
  "items": [
    {
      "id": "job_c40e7a19d3b6",
      "kind": "review",
      "refId": "rev_51ad8c0e7f23",
      "status": "dead",
      "attempts": 3,
      "error": "Nullgap AI did not return an answer",
      "createdAt": "2026-11-16T09:00:00.000Z",
      "startedAt": "2026-11-16T09:20:00.000Z",
      "finishedAt": "2026-11-16T09:24:00.000Z",
      "nextAttemptAt": "2026-11-16T09:40:00.000Z"
    }
  ],
  "total": 42
}

Errors specific to this call

StatusCodeWhen
400bad_requeststatus is not one of the listed states.

#Retry a background job

POST /api/orgs/{org}/jobs/{id}/retry

Puts a job that failed or gave up back in the queue, with its attempt count starting again. A pentest job cannot be started again this way, because a failed pentest was refunded: start a new pentest instead.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/jobs/ID/retry"

Answer (200, application/json)

A JobInfo object.

{
  "id": "job_c40e7a19d3b6",
  "kind": "review",
  "refId": "rev_51ad8c0e7f23",
  "status": "dead",
  "attempts": 3,
  "error": "Nullgap AI did not return an answer",
  "createdAt": "2026-11-16T09:00:00.000Z",
  "startedAt": "2026-11-16T09:20:00.000Z",
  "finishedAt": "2026-11-16T09:24:00.000Z",
  "nextAttemptAt": "2026-11-16T09:40:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundThere is no job with that id in this organisation.
409not_retryableThe job is not in the failed or dead state, or it is a pentest job.

#Objects

The objects the operations above take and return.

#JobInfo

A unit of background work, as admins see it.

FieldTypeAlways presentDescription
idstringyesThe job's id.
kindstringyesWhat the job does: a pull request review, a pentest, a fix run (remediation), or building an application's threat model (context).
refIdstringyesThe review, pentest, fix run or application the job belongs to.
statusstringyesWhere the job stands. dead means it gave up after the allowed attempts; an admin can start it again.
attemptsintegeryesHow many attempts have been started.
errorstring or nullyesWhy it failed, in words safe to show. Null when it did not fail.
createdAtstringyesWhen the job was queued.
startedAtstring or nullyesWhen the latest attempt started. Null when none has.
finishedAtstring or nullyesWhen it finished. Null while it has not.
nextAttemptAtstring or nullyesWhen a queued retry will run. Null when none is waiting.

Nullgap documentation