Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
List custom checksGET /api/orgs/{org}/custom-checksread
Add a custom checkPOST /api/orgs/{org}/custom-checksadmin
Change a custom checkPATCH /api/orgs/{org}/custom-checks/{id}admin
Remove a custom checkDELETE /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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/custom-checks"

Answer (200, application/json)

FieldTypeAlways presentDescription
checksarray of CustomCheckyesThe checks, in the order they were added.
limitsCustomCheckLimitsyes
{
  "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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
namestringyesShown on the findings this check produces. One line, up to 80 characters, unique in the organisation whatever the letter case.
briefstringyesWhat to look for, in plain words: 20 to 1500 characters.
notFindingstringnoWhat does not count as a finding. Up to 800 characters. Default empty.
filePatternsarray of stringnoThe files the check runs on. Up to 10 patterns; duplicates are dropped. Default empty: any file a run looks at.
matchstring or nullnoA 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.
severityGuidancestringnoHow to choose a severity, in plain words. Up to 400 characters. Default empty.
enabledbooleannoWhether 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

StatusCodeWhen
400limit_reachedThe organisation already has 20 custom checks. Remove one first.
400invalid_custom_checkA 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.
400duplicate_nameAnother 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
namestringnoShown on the findings this check produces. One line, up to 80 characters, unique in the organisation whatever the letter case.
briefstringnoWhat to look for, in plain words: 20 to 1500 characters.
notFindingstringnoWhat does not count as a finding. Up to 800 characters. Default empty.
filePatternsarray of stringnoThe files the check runs on. Up to 10 patterns; duplicates are dropped. Default empty: any file a run looks at.
matchstring or nullnoA 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.
severityGuidancestringnoHow to choose a severity, in plain words. Up to 400 characters. Default empty.
enabledbooleannoWhether 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

StatusCodeWhen
404not_foundNo custom check of this organisation has that id.
400invalid_custom_checkA 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.
400duplicate_nameAnother 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe 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)

FieldTypeAlways presentDescription
okbooleanyesAlways true.
{
  "ok": true
}

Errors specific to this call

StatusCodeWhen
404not_foundNo 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.

FieldTypeAlways presentDescription
idstringyesThe check id.
namestringyesShown on the findings this check produces. One line.
briefstringyesWhat to look for, in plain words.
notFindingstringyesWhat does not count as a finding. May be empty.
filePatternsarray of stringyesThe files the check runs on, as glob patterns. Empty means any file a run looks at.
matchstring or nullyesA regular expression a file must contain for the check to run on it. Null means no such condition.
severityGuidancestringyesHow to choose a severity, in plain words. May be empty.
enabledbooleanyesFalse while the check is switched off. Only enabled checks run.
createdAtstringyesWhen it was created.
updatedAtstringyesWhen it was last changed.

#CustomCheckLimits

The limits custom checks are held to.

FieldTypeAlways presentDescription
maxChecksintegeryesChecks an organisation can have.
nameCharsintegeryesLongest name, in characters.
briefCharsintegeryesLongest brief, in characters.
notFindingCharsintegeryesLongest notFinding, in characters.
severityCharsintegeryesLongest severityGuidance, in characters.
maxFilePatternsintegeryesMost entries in filePatterns.
patternCharsintegeryesLongest single file pattern, and longest match, in characters.
filesPerRunintegeryesFiles one check is run on in a single pentest, the most exposed first.

Nullgap documentation