Nullgap.dev Docs

API reference

Pentest schedules

Run pentests on a timetable.

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 schedulesGET /api/orgs/{org}/pentest-schedulesread
Create a schedulePOST /api/orgs/{org}/pentest-schedulesadmin
Change a schedulePATCH /api/orgs/{org}/pentest-schedules/{id}admin
Delete a scheduleDELETE /api/orgs/{org}/pentest-schedules/{id}admin

#List schedules

GET /api/orgs/{org}/pentest-schedules

Returns every pentest schedule of the organisation as a plain list, newest first. The list is not paged: an organisation has at most 50 schedules.

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/pentest-schedules"

Answer (200, application/json)

The schedules.

An array of PentestSchedule.

[
  {
    "id": "sch_6e0b4d92a7c1",
    "repoId": "repo_a41c09be77d3",
    "repoFullName": "acme/shop",
    "ref": "main",
    "paths": [
      "services/api"
    ],
    "applicationId": "app_2d8f1c63a9e4",
    "context": "Weekly check of the payments service.",
    "cadence": "weekly",
    "cron": "0 2 * * 1",
    "timezone": "Europe/Berlin",
    "maxPriceUsd": null,
    "enabled": true,
    "nextRunAt": "2026-11-23T01:00:00.000Z",
    "lastRunAt": "2026-11-16T01:00:00.000Z",
    "lastPentestId": "pen_7c2e9a41b6d0",
    "lastError": null,
    "createdBy": "dana@acme.example",
    "createdAt": "2026-11-16T09:30:00.000Z"
  }
]

#Create a schedule

POST /api/orgs/{org}/pentest-schedules

Creates a schedule that starts a pentest of a repository at regular times. The first run is the next slot, never the moment of creation. Each run is priced and paid for like a pentest started by hand; a run is skipped while the previous one is still going, and a run that cannot start records the reason in lastError and waits for its next slot. Scheduled pentests work from the code alone: a schedule has no live-testing targets. A weekly, monthly or quarterly schedule sent with none of time, timezone, daysOfWeek, dayOfMonth and cron is kept as a plain interval, without cron and timezone. An organisation can have up to 50 schedules.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
repoIdstringyesThe repository, by its id.
cadencestringyesHow often it runs. custom needs cron.
timestringnoThe time of day, as HH:MM on a 24-hour clock. Default 02:00. Not used with custom.
timezonestringnoThe IANA time zone the time is read in. Daylight-saving changes are followed. Default UTC.
daysOfWeekarray of integernoFor weekly: the days it runs on. Default Monday.
dayOfMonthintegernoFor monthly and quarterly: the day it runs on, 1 to 28 so that it exists in every month. Default 1. A quarterly schedule runs in January, April, July and October.
cronstringnoFor custom: five fields (minute, hour, day of month, month, day of week). It must name exactly one minute and one hour, so it runs at most once a day. Up to 80 characters.
maxPriceUsdnumber or nullnoA price ceiling for one run, from 1 to 1,000,000, rounded to a whole number. A run priced above it is not started and the schedule records why. Null or an empty string means no ceiling.
refstringnoThe branch or tag to test. It is resolved again at every run. Up to 200 characters. Default: the repository's default branch.
pathsarray of stringnoThe folders in scope: up to 50, each relative to the repository root, none starting with / or containing ... Leave out or send an empty list for the whole repository.
contextstringnoNotes handed to every run. Up to 20,000 characters.
applicationIdstringnoAn application of this repository. Its threat model and rules are handed to the run.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"repoId":"repo_a41c09be77d3","cadence":"weekly","time":"02:00","timezone":"Europe/Berlin","daysOfWeek":[1],"dayOfMonth":1,"cron":"30 3 * * 1,4","maxPriceUsd":null,"ref":"main","paths":["services/api"],"context":"Weekly check of the payments service.","applicationId":"app_2d8f1c63a9e4"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentest-schedules"

Answer (200, application/json)

A PentestSchedule object.

{
  "id": "sch_6e0b4d92a7c1",
  "repoId": "repo_a41c09be77d3",
  "repoFullName": "acme/shop",
  "ref": "main",
  "paths": [
    "services/api"
  ],
  "applicationId": "app_2d8f1c63a9e4",
  "context": "Weekly check of the payments service.",
  "cadence": "weekly",
  "cron": "0 2 * * 1",
  "timezone": "Europe/Berlin",
  "maxPriceUsd": null,
  "enabled": true,
  "nextRunAt": "2026-11-23T01:00:00.000Z",
  "lastRunAt": "2026-11-16T01:00:00.000Z",
  "lastPentestId": "pen_7c2e9a41b6d0",
  "lastError": null,
  "createdBy": "dana@acme.example",
  "createdAt": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo repository of this organisation has the repoId sent, or applicationId is not an application of that repository.
400bad_requestA field is missing or not valid: an unknown cadence or time zone, a time that is not HH:MM, a day out of range, a custom schedule without cron, a cron that does not have five fields or names more than one minute or hour or never runs, a maxPriceUsd out of range, or a path that leaves the repository.
409too_manyThe organisation already has 50 schedules.

#Change a schedule

PATCH /api/orgs/{org}/pentest-schedules/{id}

Changes when a schedule runs, what it tests (ref, paths, context), its price ceiling, or whether it is switched on. The repository and application cannot be changed: delete the schedule and create another. Fields left out keep their value. The timing is replaced as a whole and only when cadence is sent: time, timezone, daysOfWeek, dayOfMonth and cron are read together with it and are ignored without it, so send the full timing again. Changing the timing moves nextRunAt to the next slot. A schedule switched back on after its slot has passed waits for the next one instead of running at once.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
cadencestringnoHow often it runs. custom needs cron.
timestringnoThe time of day, as HH:MM on a 24-hour clock. Default 02:00. Not used with custom.
timezonestringnoThe IANA time zone the time is read in. Daylight-saving changes are followed. Default UTC.
daysOfWeekarray of integernoFor weekly: the days it runs on. Default Monday.
dayOfMonthintegernoFor monthly and quarterly: the day it runs on, 1 to 28 so that it exists in every month. Default 1. A quarterly schedule runs in January, April, July and October.
cronstringnoFor custom: five fields (minute, hour, day of month, month, day of week). It must name exactly one minute and one hour, so it runs at most once a day. Up to 80 characters.
maxPriceUsdnumber or nullnoA price ceiling for one run, from 1 to 1,000,000, rounded to a whole number. A run priced above it is not started and the schedule records why. Null or an empty string means no ceiling.
refstringnoThe branch or tag to test from the next run on. Up to 200 characters. Default: the repository's default branch.
pathsarray of stringnoThe folders in scope: up to 50, each relative to the repository root, none starting with / or containing ... Leave out or send an empty list for the whole repository.
contextstringnoNotes handed to every run from the next one on. Up to 20,000 characters; an empty string removes them.
enabledbooleannoSwitch the schedule on or off.

Example request

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cadence":"weekly","time":"02:00","timezone":"Europe/Berlin","daysOfWeek":[1],"dayOfMonth":1,"cron":"30 3 * * 1,4","maxPriceUsd":null,"ref":"main","paths":["services/api"],"context":"Weekly check of the payments service.","enabled":false}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentest-schedules/ID"

Answer (200, application/json)

A PentestSchedule object.

{
  "id": "sch_6e0b4d92a7c1",
  "repoId": "repo_a41c09be77d3",
  "repoFullName": "acme/shop",
  "ref": "main",
  "paths": [
    "services/api"
  ],
  "applicationId": "app_2d8f1c63a9e4",
  "context": "Weekly check of the payments service.",
  "cadence": "weekly",
  "cron": "0 2 * * 1",
  "timezone": "Europe/Berlin",
  "maxPriceUsd": null,
  "enabled": true,
  "nextRunAt": "2026-11-23T01:00:00.000Z",
  "lastRunAt": "2026-11-16T01:00:00.000Z",
  "lastPentestId": "pen_7c2e9a41b6d0",
  "lastError": null,
  "createdBy": "dana@acme.example",
  "createdAt": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo schedule of this organisation has that id.
400bad_requestThe timing is not valid (as when creating a schedule), maxPriceUsd is out of range, a path leaves the repository, or enabled is not true or false.

#Delete a schedule

DELETE /api/orgs/{org}/pentest-schedules/{id}

Removes a schedule. Pentests it already started are kept.

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

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentest-schedules/ID"

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundNo schedule of this organisation has that id.

#Objects

The objects the operations above take and return.

#PentestSchedule

A pentest that starts by itself at regular times.

FieldTypeAlways presentDescription
idstringyesThe schedule id.
repoIdstringyesThe repository it tests.
repoFullNamestringyesThe repository as owner/name.
refstringyesThe branch or tag to test. It is resolved again at every run.
pathsarray of stringyesThe folders in scope. Empty means the whole repository.
applicationIdstring or nullyesThe application whose threat model and rules each run uses.
contextstringyesNotes handed to every run. Empty when none were given.
cadencestringyesHow often it runs. custom: by the expression in cron.
cronstringnoThe schedule as a five-field expression (minute, hour, day of month, month, day of week), read in timezone. Absent on a weekly, monthly or quarterly schedule created without a time of day: that one simply runs one period after its last slot.
timezonestringnoThe IANA time zone cron is read in. Absent when cron is.
maxPriceUsdnumber or nullnoA price ceiling for one run: a run priced above it is not started, and lastError says so. Null means no ceiling.
enabledbooleanyesFalse while the schedule is switched off.
nextRunAtstringyesWhen it runs next.
lastRunAtstring or nullyesWhen it last ran or last tried to. Null before the first slot.
lastPentestIdstring or nullyesThe pentest its last successful start created.
lastErrorstring or nullyesWhy the last run could not start. Cleared by a run that starts.
createdBystringyesWho created it.
createdAtstringyesWhen it was created.

Nullgap documentation