API reference
Custom checks
Checks you write for your own code, run in every review and pentest.
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 custom checks | GET /api/orgs/{org}/custom-checks | read |
| Add a custom check | POST /api/orgs/{org}/custom-checks | admin |
| Change a custom check | PATCH /api/orgs/{org}/custom-checks/{id} | admin |
| Remove a custom check | DELETE /api/orgs/{org}/custom-checks/{id} | admin |
#List custom checks
GET /api/orgs/{org}/custom-checks
Returns the organisation's custom checks, enabled or not, together with the limits they are held to. The answer is an object, not a page.
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/custom-checks"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
checks | array of CustomCheck | yes | The checks, in the order they were added. |
limits | CustomCheckLimits | yes |
{
"checks": [
{
"id": "cc_9d4e1f7a2b60",
"name": "Tenant id taken from the request",
"brief": "Flag any database query in a request handler that filters by a tenant id read from the request body or query string instead of from the signed-in session.",
"notFinding": "Admin tools under /internal, which are allowed to name any tenant.",
"filePatterns": [
"services/api/**"
],
"match": "tenant_?[iI]d",
"severityGuidance": "High when the query writes, medium when it only reads.",
"enabled": true,
"createdAt": "2026-11-16T09:30:00.000Z",
"updatedAt": "2026-11-16T09:30:00.000Z"
}
],
"limits": {
"maxChecks": 20,
"nameChars": 80,
"briefChars": 1500,
"notFindingChars": 800,
"severityChars": 400,
"maxFilePatterns": 10,
"patternChars": 200,
"filesPerRun": 8
}
}
#Add a custom check
POST /api/orgs/{org}/custom-checks
Adds a check written for the organisation's own code. An enabled check runs in every pull request review and pentest of the organisation's repositories from then on, next to the built-in checks. Text is tidied before it is stored: control characters are removed and surrounding space is trimmed. An organisation can have 20 checks.
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 |
|---|---|---|---|
name | string | yes | Shown on the findings this check produces. One line, up to 80 characters, unique in the organisation whatever the letter case. |
brief | string | yes | What to look for, in plain words: 20 to 1500 characters. |
notFinding | string | no | What does not count as a finding. Up to 800 characters. Default empty. |
filePatterns | array of string | no | The files the check runs on. Up to 10 patterns; duplicates are dropped. Default empty: any file a run looks at. |
match | string or null | no | A regular expression a file must contain for the check to run on it, up to 200 characters. Null or an empty string for no such condition. Refused: backreferences, lookahead and lookbehind, a repeated group that itself contains a repeat or alternatives, a counted repeat above 100, and more than 8 open-ended repeats. |
severityGuidance | string | no | How to choose a severity, in plain words. Up to 400 characters. Default empty. |
enabled | boolean | no | Whether the check runs. Default true. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Tenant id taken from the request","brief":"Flag any database query in a request handler that filters by a tenant id read from the request body or query string instead of from the signed-in session.","notFinding":"Admin tools under /internal, which are allowed to name any tenant.","filePatterns":["services/api/**"],"match":"tenant_?[iI]d","severityGuidance":"High when the query writes, medium when it only reads.","enabled":true}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/custom-checks"
Answer (200, application/json)
A CustomCheck object.
{
"id": "cc_9d4e1f7a2b60",
"name": "Tenant id taken from the request",
"brief": "Flag any database query in a request handler that filters by a tenant id read from the request body or query string instead of from the signed-in session.",
"notFinding": "Admin tools under /internal, which are allowed to name any tenant.",
"filePatterns": [
"services/api/**"
],
"match": "tenant_?[iI]d",
"severityGuidance": "High when the query writes, medium when it only reads.",
"enabled": true,
"createdAt": "2026-11-16T09:30:00.000Z",
"updatedAt": "2026-11-16T09:30:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | limit_reached | The organisation already has 20 custom checks. Remove one first. |
| 400 | invalid_custom_check | A field is missing, too long or of the wrong kind, a file pattern is not valid, or match is a pattern that is refused. The message says which. |
| 400 | duplicate_name | Another custom check of the organisation already has that name. |
#Change a custom check
PATCH /api/orgs/{org}/custom-checks/{id}
Changes any fields of a custom check; fields left out keep their value. The result is validated as a whole, exactly as when adding a check. Send enabled: false to switch a check off without losing it.
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 |
|---|---|---|---|
name | string | no | Shown on the findings this check produces. One line, up to 80 characters, unique in the organisation whatever the letter case. |
brief | string | no | What to look for, in plain words: 20 to 1500 characters. |
notFinding | string | no | What does not count as a finding. Up to 800 characters. Default empty. |
filePatterns | array of string | no | The files the check runs on. Up to 10 patterns; duplicates are dropped. Default empty: any file a run looks at. |
match | string or null | no | A regular expression a file must contain for the check to run on it, up to 200 characters. Null or an empty string for no such condition. Refused: backreferences, lookahead and lookbehind, a repeated group that itself contains a repeat or alternatives, a counted repeat above 100, and more than 8 open-ended repeats. |
severityGuidance | string | no | How to choose a severity, in plain words. Up to 400 characters. Default empty. |
enabled | boolean | no | Whether the check runs. Default true. |
Example request
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Tenant id taken from the request","brief":"Flag any database query in a request handler that filters by a tenant id read from the request body or query string instead of from the signed-in session.","notFinding":"Admin tools under /internal, which are allowed to name any tenant.","filePatterns":["services/api/**"],"match":"tenant_?[iI]d","severityGuidance":"High when the query writes, medium when it only reads.","enabled":true}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/custom-checks/ID"
Answer (200, application/json)
A CustomCheck object.
{
"id": "cc_9d4e1f7a2b60",
"name": "Tenant id taken from the request",
"brief": "Flag any database query in a request handler that filters by a tenant id read from the request body or query string instead of from the signed-in session.",
"notFinding": "Admin tools under /internal, which are allowed to name any tenant.",
"filePatterns": [
"services/api/**"
],
"match": "tenant_?[iI]d",
"severityGuidance": "High when the query writes, medium when it only reads.",
"enabled": true,
"createdAt": "2026-11-16T09:30:00.000Z",
"updatedAt": "2026-11-16T09:30:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No custom check of this organisation has that id. |
| 400 | invalid_custom_check | A field is missing, too long or of the wrong kind, a file pattern is not valid, or match is a pattern that is refused. The message says which. |
| 400 | duplicate_name | Another custom check of the organisation already has that name. |
#Remove a custom check
DELETE /api/orgs/{org}/custom-checks/{id}
Removes a custom check. Findings it already produced stay.
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/custom-checks/ID"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
ok | boolean | yes | Always true. |
{
"ok": true
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No custom check of this organisation has that id. |
#Objects
The objects the operations above take and return.
#CustomCheck
A check an organisation writes for its own code. Enabled checks run in every review and pentest of its repositories.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The check id. |
name | string | yes | Shown on the findings this check produces. One line. |
brief | string | yes | What to look for, in plain words. |
notFinding | string | yes | What does not count as a finding. May be empty. |
filePatterns | array of string | yes | The files the check runs on, as glob patterns. Empty means any file a run looks at. |
match | string or null | yes | A regular expression a file must contain for the check to run on it. Null means no such condition. |
severityGuidance | string | yes | How to choose a severity, in plain words. May be empty. |
enabled | boolean | yes | False while the check is switched off. Only enabled checks run. |
createdAt | string | yes | When it was created. |
updatedAt | string | yes | When it was last changed. |
#CustomCheckLimits
The limits custom checks are held to.
| Field | Type | Always present | Description |
|---|---|---|---|
maxChecks | integer | yes | Checks an organisation can have. |
nameChars | integer | yes | Longest name, in characters. |
briefChars | integer | yes | Longest brief, in characters. |
notFindingChars | integer | yes | Longest notFinding, in characters. |
severityChars | integer | yes | Longest severityGuidance, in characters. |
maxFilePatterns | integer | yes | Most entries in filePatterns. |
patternChars | integer | yes | Longest single file pattern, and longest match, in characters. |
filesPerRun | integer | yes | Files one check is run on in a single pentest, the most exposed first. |
Nullgap documentation