Developers
API overview
What every call to the Nullgap REST API has in common: addresses, authentication, errors, paging, filtering, rate limits and what happens when you repeat a call.
The REST API gives programmatic access to what the console shows: findings, pull request reviews, pentests, fixes, repositories and settings. The console itself and the MCP server use the same API. This page covers what all calls share; the API reference lists every operation.
#Addresses
Every path starts at the address of your Nullgap console. Almost everything belongs to one organisation and lives under /api/orgs/<organisation slug>.
The samples in these docs use three environment variables:
| Variable | Value |
|---|---|
NULLGAP_URL | The address of your Nullgap console, with no trailing slash. |
NULLGAP_ORG | Your organisation's slug: the short name in the console's address after you sign in. |
NULLGAP_API_KEY | An API key. See API keys. |
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings?state=open&limit=20"
Requests and answers are JSON (Content-Type: application/json) unless an operation says otherwise. The exceptions are file downloads (finding exports, the audit log export, reports), the archive upload, and the SCIM endpoints. A JSON request body must be an object and can be at most 1 MB.
#Authentication
Send an API key as a bearer token in the Authorization header. Keys start with ng_, belong to one organisation, and carry one of three scopes:
| Scope | What it may call |
|---|---|
read | Every GET, plus the two POST calls that only compute an answer: the pentest estimate and the package check. |
write | Also the changes any member can make, such as triaging a finding or starting a fix. |
admin | Also the changes an admin can make, such as starting a pentest or changing settings. |
Each operation in the reference says which scope it needs. Some say "console only": those need a signed-in person and refuse every key. API keys has the full rules.
A key used against any organisation other than its own gets 404, the same answer as for an organisation that does not exist.
#Errors
Every failure has the same shape, with a matching HTTP status:
{
"error": {
"code": "insufficient_scope",
"message": "This API key is read-only",
"requestId": "req_Zk3vQp81LmNx"
}
}
codeis short and stable. Branch on it, not onmessage.messageis one sentence written for a person.requestIdidentifies the request. It is also sent on every answer, successful or not, as theX-Request-Idheader. Quote it when you ask for help.
These can come back from any call:
| Status | Code | When |
|---|---|---|
| 400 | bad_json | The body is not valid JSON, or is not a JSON object. |
| 400 | bad_request | A field is missing, of the wrong type or outside its limits. The message names the field. |
| 401 | unauthenticated | No key was sent. |
| 401 | invalid_api_key | The key is not known: mistyped, revoked, or replaced by a rotation. |
| 401 | expired_api_key | The key is past its expiry date. |
| 403 | insufficient_scope | The key is read-only and the call changes something, or the call needs admin and the key does not have it. |
| 403 | forbidden | The action needs a signed-in person, so no key may do it. |
| 403 | org_suspended | The workspace is suspended. Reads still work; anything that changes state is refused. |
| 404 | not_found | The path does not exist, the thing asked for does not exist, or the organisation is not the key's own. |
| 405 | method_not_allowed | The path exists, but not with this method. |
| 422 | checkout_failed | The code could not be fetched from the code host: gone, too large, wrong branch, or access withdrawn. |
| 429 | rate_limited | Too many requests in the current minute. |
| 500 | internal | Something went wrong on our side. The message is deliberately general; the detail is in our logs under the requestId. |
Operations add their own codes, listed with each one in the reference. A few calls report a failed check in a successful answer instead of an error: the live-testing sign-in check, the outbound webhook test and the audit log verification all answer 200 and say in the body whether the check passed. Read the body.
The SCIM endpoints are the one exception to the error shape: they answer in the SCIM error format, as identity providers expect. See SCIM provisioning.
#Paging
List operations that can grow without bound take two query parameters and answer with an envelope:
| Parameter | Meaning |
|---|---|
limit | How many to return, 1 to 200. Default 50. A value outside the range is brought into it rather than refused. |
offset | How many to skip from the start. Default 0. |
{
"items": [],
"total": 137
}
total is the number that match in all, so you have everything once offset + items.length reaches total. This fetches every open finding, 200 at a time:
offset=0
while :; do
page=$(curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/findings?state=open&limit=200&offset=$offset")
echo "$page" | jq -c '.items[]'
offset=$((offset + 200))
[ "$offset" -ge "$(echo "$page" | jq '.total')" ] && break
done
Paging is by position, not by cursor. If findings are added or change state while you page, an item can appear twice or be missed; for a consistent snapshot of findings use the export instead.
Not every list is paged. Lists that are short by nature, such as repositories, connections, members, schedules and API keys, answer with a plain JSON array and take no limit. The reference shows which form each operation uses.
#Filtering and sorting
Filters are query parameters, named on each operation. Giving several narrows the result: every one must match. The findings list, for example, takes state, severity, priority, source, repoId, a text search q, and sort.
Filters are checked to different degrees. Some refuse an unknown value with 400; others treat it as matching nothing and answer an empty list. The reference says which for each parameter. If a filtered list is unexpectedly empty, check the spelling of the values first.
#Rate limits
Requests are counted in fixed one-minute windows. The standard limits are:
| Counted for | Limit |
|---|---|
| Each API key | 600 requests a minute |
| Each client address | 3000 requests a minute, across all keys |
Over a limit the answer is 429 with the code rate_limited and a Retry-After header of 60 seconds, after which the limit has always reset. There are no headers that show how much of the limit is left. A client that polls should do so every few seconds at most; for anything event-driven, use outbound webhooks rather than polling.
A tool call through the hosted MCP endpoint counts as the MCP request plus each API call the tool makes.
#Repeating a call
Whether a repeated call is safe depends on the method:
GETchanges nothing and can always be repeated.PUT,PATCHandDELETEset a state. Sending the same one twice leaves things as the first left them, although a secondDELETEof something already gone usually answers404.POSTdoes its work again each time, unless the operation says otherwise. A secondPOSTto start a pentest starts a second pentest, unless both carry the same idempotency key (below).
So when a POST that starts something times out or the connection drops, do not send it again blindly. List first and see whether the first attempt went through:
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentests?limit=5"
Starting a pentest accepts an Idempotency-Key header: 8 to 128 letters, digits, dots, dashes, underscores or colons, one key per pentest you mean to start. For 24 hours a second call with the same key and the same fields answers with the pentest the first call started; nothing is started or charged twice. The same key with different fields is refused with 409 idempotency_key_reused, and a call that arrives while the first is still being handled gets 409 idempotency_in_progress. A start that fails leaves the key free. No other operation reads the header.
A few operations are safe to repeat by design, and their reference entries say so. Starting a fix for a finding that already has a fix run queued or running returns that run instead of starting another, and requesting a review of a commit that already has one returns the existing review.
#Dates, ids and fields you can ignore
- Dates are ISO 8601 strings in UTC, such as
2026-11-16T09:30:00.000Z. - Ids are opaque strings with a short prefix that says what they name, such as
fnd_for a finding orpen_for a pentest. Do not parse anything else out of them. - New fields can be added to answers at any time. Ignore fields you do not know.
- A few fields are kept only for compatibility and always hold zero. The reference marks them.
#The machine-readable description
GET /api/openapi.json returns the whole API as an OpenAPI 3.1 document: every path and method with its parameters, request body, answers and the scope it needs. It needs no key, and it is generated by the server you call, so it always describes that server.
curl -s "$NULLGAP_URL/api/openapi.json" | jq '.paths | keys | length'
The API reference in these docs is built from the same document.
Nullgap documentation