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.
| Operation | Method and path | Who may call it |
|---|---|---|
| List background jobs | GET /api/orgs/{org}/jobs | admin |
| Retry a background job | POST /api/orgs/{org}/jobs/{id}/retry | admin |
#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
| 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. |
status | string | no | Only 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)
| Field | Type | Always present | Description |
|---|---|---|---|
items | array of JobInfo | yes | The matching jobs, at most limit of them. |
total | integer | yes | How 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
| Status | Code | When |
|---|---|---|
| 400 | bad_request | status 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | There is no job with that id in this organisation. |
| 409 | not_retryable | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The job's id. |
kind | string | yes | What the job does: a pull request review, a pentest, a fix run (remediation), or building an application's threat model (context). |
refId | string | yes | The review, pentest, fix run or application the job belongs to. |
status | string | yes | Where the job stands. dead means it gave up after the allowed attempts; an admin can start it again. |
attempts | integer | yes | How many attempts have been started. |
error | string or null | yes | Why it failed, in words safe to show. Null when it did not fail. |
createdAt | string | yes | When the job was queued. |
startedAt | string or null | yes | When the latest attempt started. Null when none has. |
finishedAt | string or null | yes | When it finished. Null while it has not. |
nextAttemptAt | string or null | yes | When a queued retry will run. Null when none is waiting. |
Nullgap documentation