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.
| Operation | Method and path | Who may call it |
|---|---|---|
| List schedules | GET /api/orgs/{org}/pentest-schedules | read |
| Create a schedule | POST /api/orgs/{org}/pentest-schedules | admin |
| Change a schedule | PATCH /api/orgs/{org}/pentest-schedules/{id} | admin |
| Delete a schedule | DELETE /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
| 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/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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
repoId | string | yes | The repository, by its id. |
cadence | string | yes | How often it runs. custom needs cron. |
time | string | no | The time of day, as HH:MM on a 24-hour clock. Default 02:00. Not used with custom. |
timezone | string | no | The IANA time zone the time is read in. Daylight-saving changes are followed. Default UTC. |
daysOfWeek | array of integer | no | For weekly: the days it runs on. Default Monday. |
dayOfMonth | integer | no | For 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. |
cron | string | no | For 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. |
maxPriceUsd | number or null | no | A 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. |
ref | string | no | The branch or tag to test. It is resolved again at every run. Up to 200 characters. Default: the repository's default branch. |
paths | array of string | no | The 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. |
context | string | no | Notes handed to every run. Up to 20,000 characters. |
applicationId | string | no | An 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No repository of this organisation has the repoId sent, or applicationId is not an application of that repository. |
| 400 | bad_request | A 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. |
| 409 | too_many | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
cadence | string | no | How often it runs. custom needs cron. |
time | string | no | The time of day, as HH:MM on a 24-hour clock. Default 02:00. Not used with custom. |
timezone | string | no | The IANA time zone the time is read in. Daylight-saving changes are followed. Default UTC. |
daysOfWeek | array of integer | no | For weekly: the days it runs on. Default Monday. |
dayOfMonth | integer | no | For 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. |
cron | string | no | For 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. |
maxPriceUsd | number or null | no | A 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. |
ref | string | no | The branch or tag to test from the next run on. Up to 200 characters. Default: the repository's default branch. |
paths | array of string | no | The 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. |
context | string | no | Notes handed to every run from the next one on. Up to 20,000 characters; an empty string removes them. |
enabled | boolean | no | Switch 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No schedule of this organisation has that id. |
| 400 | bad_request | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The schedule id. |
repoId | string | yes | The repository it tests. |
repoFullName | string | yes | The repository as owner/name. |
ref | string | yes | The branch or tag to test. It is resolved again at every run. |
paths | array of string | yes | The folders in scope. Empty means the whole repository. |
applicationId | string or null | yes | The application whose threat model and rules each run uses. |
context | string | yes | Notes handed to every run. Empty when none were given. |
cadence | string | yes | How often it runs. custom: by the expression in cron. |
cron | string | no | The 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. |
timezone | string | no | The IANA time zone cron is read in. Absent when cron is. |
maxPriceUsd | number or null | no | A price ceiling for one run: a run priced above it is not started, and lastError says so. Null means no ceiling. |
enabled | boolean | yes | False while the schedule is switched off. |
nextRunAt | string | yes | When it runs next. |
lastRunAt | string or null | yes | When it last ran or last tried to. Null before the first slot. |
lastPentestId | string or null | yes | The pentest its last successful start created. |
lastError | string or null | yes | Why the last run could not start. Cleared by a run that starts. |
createdBy | string | yes | Who created it. |
createdAt | string | yes | When it was created. |
Nullgap documentation