API reference
Organisation
The organisation, its settings, its overview figures, and the signed-in person.
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 |
|---|---|---|
| Get the current session | GET /api/session | none |
| Create an organisation | POST /api/orgs | console session |
| Update your profile | PATCH /api/me | console session |
| Get the organisation | GET /api/orgs/{org} | read |
| Rename the organisation | PATCH /api/orgs/{org} | admin |
| Get the live-testing scope list | GET /api/orgs/{org}/scope-hosts | read |
| Get the settings | GET /api/orgs/{org}/settings | read |
| Change the settings | PATCH /api/orgs/{org}/settings | admin |
| Get the security overview | GET /api/orgs/{org}/overview | read |
| List set-up steps | GET /api/orgs/{org}/onboarding | read |
#Get the current session
GET /api/session
Answers who is signed in and which organisations they can open. It reads the console session cookie, so an API key gets 401 unauthenticated here: a key belongs to one organisation and has no person behind it.
Who may call it: None. No key is needed.
Example request
curl -s \
"$NULLGAP_URL/api/session"
Answer (200, application/json)
A Session object.
{
"user": {
"id": "usr_4c1d9a7be203",
"email": "dana@acme.example",
"name": "Dana Okafor",
"githubLogin": "dana-okafor",
"createdAt": "2026-09-01T08:15:00.000Z"
},
"orgs": [
{
"slug": "acme",
"name": "Acme",
"role": "owner"
}
],
"mfa": {
"enrolled": true,
"verifiedAt": "2026-11-16T09:12:00.000Z"
},
"method": "passkey",
"workspaceCreation": "open"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 401 | mfa_pending | The sign-in is waiting for its second factor. Finish the multi-factor check first. |
#Create an organisation
POST /api/orgs
Creates an organisation with default settings and makes the signed-in person its owner. The slug is derived from the name; a number is added when the slug is taken or reserved. Accepting the services agreement here starts the trial at once; without it the plan stays none until the trial is started from the billing routes.
Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The organisation's name. 1 to 80 characters. |
acceptTerms | boolean | no | Send true to accept the services agreement and start the trial now. |
Answer (200, application/json)
A Org object.
{
"id": "org_3f9a1c2b7d4e",
"slug": "acme",
"name": "Acme",
"plan": "trial",
"trialEndsAt": "2026-11-30T09:30:00.000Z",
"settings": {
"postChecks": true,
"postComments": true,
"postSystemComments": true,
"failCheckAt": "high",
"commentStyle": "standard",
"filters": [
{
"kind": "branch",
"mode": "exclude",
"value": "dependabot/*"
}
],
"sla": {
"critical": {
"days": 7,
"target": 95
},
"high": {
"days": 30,
"target": 90
},
"medium": {
"days": 90,
"target": 80
},
"low": {
"days": 180,
"target": 70
}
},
"minSecurityScore": 80,
"requireMfa": false,
"overage": false,
"unverifiedFixes": true,
"dataProtection": {
"framework": "gdpr",
"retentionDays": 365,
"privacyContactEmail": "privacy@acme.example",
"breachContactEmail": "security@acme.example"
},
"supplyChain": {
"blockedPackages": [
"event-stream@3.3.6"
],
"allowedPackages": [
"@acme/*"
],
"minAgeDays": 7,
"blockInstallScripts": true,
"installScriptAllowlist": [
"esbuild"
],
"allowedRegistries": [
"npm.acme.example"
]
},
"customChecks": [
{
"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"
}
]
},
"createdAt": "2026-09-01T08:20:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | sso_session | The session signed in through single sign-on, which may not create organisations. |
| 403 | workspace_creation_closed | This deployment sets new workspaces up by invitation only (workspaceCreation is invite-only in GET /api/session). Ask your Nullgap contact, or ask a colleague to invite you to your company's workspace. |
#Update your profile
PATCH /api/me
Changes the signed-in person's own name or linked code-host login. The login is what matches pull request authors to this person's seat. A session that signed in through single sign-on cannot change the account and gets 403 sso_session.
Who may call it: A signed-in person in the console. This is about your own account, so no API key may call it.
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | Your display name. 1 to 100 characters. |
githubLogin | string or null | no | Your code-host login. At most 60 characters; letters, digits and single dashes. Null or an empty string removes the link. |
Answer (200, application/json)
A User object.
{
"id": "usr_4c1d9a7be203",
"email": "dana@acme.example",
"name": "Dana Okafor",
"githubLogin": "dana-okafor",
"createdAt": "2026-09-01T08:15:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | githubLogin is not a valid login, or name is empty or too long. |
| 403 | sso_session | The session signed in through single sign-on, which may not change the account itself. |
#Get the organisation
GET /api/orgs/{org}
Answers the organisation with its plan and settings.
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"
Answer (200, application/json)
A Org object.
{
"id": "org_3f9a1c2b7d4e",
"slug": "acme",
"name": "Acme",
"plan": "trial",
"trialEndsAt": "2026-11-30T09:30:00.000Z",
"settings": {
"postChecks": true,
"postComments": true,
"postSystemComments": true,
"failCheckAt": "high",
"commentStyle": "standard",
"filters": [
{
"kind": "branch",
"mode": "exclude",
"value": "dependabot/*"
}
],
"sla": {
"critical": {
"days": 7,
"target": 95
},
"high": {
"days": 30,
"target": 90
},
"medium": {
"days": 90,
"target": 80
},
"low": {
"days": 180,
"target": 70
}
},
"minSecurityScore": 80,
"requireMfa": false,
"overage": false,
"unverifiedFixes": true,
"dataProtection": {
"framework": "gdpr",
"retentionDays": 365,
"privacyContactEmail": "privacy@acme.example",
"breachContactEmail": "security@acme.example"
},
"supplyChain": {
"blockedPackages": [
"event-stream@3.3.6"
],
"allowedPackages": [
"@acme/*"
],
"minAgeDays": 7,
"blockInstallScripts": true,
"installScriptAllowlist": [
"esbuild"
],
"allowedRegistries": [
"npm.acme.example"
]
},
"customChecks": [
{
"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"
}
]
},
"createdAt": "2026-09-01T08:20:00.000Z"
}
#Rename the organisation
PATCH /api/orgs/{org}
Changes the name, the slug, or both. Changing the slug changes every API path and console address of the organisation at once: the old slug stops working.
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 | no | The new display name. 1 to 80 characters. |
slug | string | no | The new slug. At most 40 characters: lower-case letters, digits and dashes, not starting or ending with a dash. Upper-case letters are lowered. A few names the console uses itself are reserved. |
Example request
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Acme","slug":"acme"}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG"
Answer (200, application/json)
A Org object.
{
"id": "org_3f9a1c2b7d4e",
"slug": "acme",
"name": "Acme",
"plan": "trial",
"trialEndsAt": "2026-11-30T09:30:00.000Z",
"settings": {
"postChecks": true,
"postComments": true,
"postSystemComments": true,
"failCheckAt": "high",
"commentStyle": "standard",
"filters": [
{
"kind": "branch",
"mode": "exclude",
"value": "dependabot/*"
}
],
"sla": {
"critical": {
"days": 7,
"target": 95
},
"high": {
"days": 30,
"target": 90
},
"medium": {
"days": 90,
"target": 80
},
"low": {
"days": 180,
"target": 70
}
},
"minSecurityScore": 80,
"requireMfa": false,
"overage": false,
"unverifiedFixes": true,
"dataProtection": {
"framework": "gdpr",
"retentionDays": 365,
"privacyContactEmail": "privacy@acme.example",
"breachContactEmail": "security@acme.example"
},
"supplyChain": {
"blockedPackages": [
"event-stream@3.3.6"
],
"allowedPackages": [
"@acme/*"
],
"minAgeDays": 7,
"blockInstallScripts": true,
"installScriptAllowlist": [
"esbuild"
],
"allowedRegistries": [
"npm.acme.example"
]
},
"customChecks": [
{
"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"
}
]
},
"createdAt": "2026-09-01T08:20:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | The slug has characters other than lower-case letters, digits and dashes, or is a reserved name. |
| 409 | slug_taken | Another organisation already uses that slug. |
#Get the live-testing scope list
GET /api/orgs/{org}/scope-hosts
Returns the hosts this organisation may point live testing at. A pentest with a live-testing address is refused with out_of_scope unless the address is covered by an entry here. An entry is a host name; one that starts with *. covers every subdomain but not the name itself; one that ends with a port covers that port only (an address without a port is on 443 for https and 80 for http), and one without a port covers the host on any port. Any member can read the list. An admin changes it by sending scopeHosts to PATCH /api/orgs/{org}/settings.
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/scope-hosts"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
hosts | array of string | yes | The entries, in the order they were saved. Empty until an admin adds one: live testing is then not possible. |
{
"hosts": [
"*.staging.acme.example:8443"
]
}
#Get the settings
GET /api/orgs/{org}/settings
Answers the organisation's settings. supplyChain is always present here, with empty rules for an organisation that never set any.
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/settings"
Answer (200, application/json)
A OrgSettings object.
{
"postChecks": true,
"postComments": true,
"postSystemComments": true,
"failCheckAt": "high",
"commentStyle": "standard",
"filters": [
{
"kind": "branch",
"mode": "exclude",
"value": "dependabot/*"
}
],
"sla": {
"critical": {
"days": 7,
"target": 95
},
"high": {
"days": 30,
"target": 90
},
"medium": {
"days": 90,
"target": 80
},
"low": {
"days": 180,
"target": 70
}
},
"minSecurityScore": 80,
"requireMfa": false,
"overage": false,
"unverifiedFixes": true,
"dataProtection": {
"framework": "gdpr",
"retentionDays": 365,
"privacyContactEmail": "privacy@acme.example",
"breachContactEmail": "security@acme.example"
},
"supplyChain": {
"blockedPackages": [
"event-stream@3.3.6"
],
"allowedPackages": [
"@acme/*"
],
"minAgeDays": 7,
"blockInstallScripts": true,
"installScriptAllowlist": [
"esbuild"
],
"allowedRegistries": [
"npm.acme.example"
]
},
"customChecks": [
{
"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"
}
]
}
#Change the settings
PATCH /api/orgs/{org}/settings
Changes the settings that are sent and leaves the rest as they are. Lists (filters, the package lists, allowedRegistries, scopeHosts) are replaced whole; the objects sla, dataProtection and supplyChain are merged field by field. The whole request is refused if any field is invalid: nothing is saved. An API key with the admin scope may change everything except requireMfa: changing that value needs a person signed in to the console, with a recent second-factor check when their account has one. Sending dataProtection applies the retention period immediately. Custom checks are not changed here; use the custom-checks routes.
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 |
|---|---|---|---|
postChecks | boolean | no | Show progress and results as a check on the commit. |
postComments | boolean | no | Post the summary and the inline finding comments on the pull request. |
postSystemComments | boolean | no | Post notices about skipped reviews, limits and configuration problems on the pull request. |
requireMfa | boolean | no | Require multi-factor sign-in for every member. Changing this value in either direction needs a person signed in to the console, and is refused for an API key. To switch it on, your own account must already have multi-factor sign-in. |
overage | boolean | no | Allow pull request reviews beyond the included number, billed per review. |
unverifiedFixes | boolean | no | Allow a fix to be proposed when a finding cannot be reproduced, as a draft pull request marked "[Not proven]". False: only fixes proven by reproduction are opened. A change is written to the audit log as settings.unverified_fixes. |
failCheckAt | string | no | Fail the check when a finding is at or above this severity. off never fails it. |
commentStyle | string | no | How much detail pull request comments carry. One of: concise, standard, detailed. |
filters | array of ReviewFilter | no | Which pull requests are reviewed. Replaces the whole list. At most 100 filters. |
sla | object | no | Resolution windows by severity. Severities left out keep their values. |
sla.critical | object | no | The window for critical findings. Send both values. |
sla.critical.days | number | yes | Days allowed to resolve a critical finding, 1 to 3650. Rounded to a whole number. |
sla.critical.target | number | yes | The share of findings that should meet it, 0 to 100. Rounded to a whole number. |
sla.high | object | no | The window for high findings. Send both values. |
sla.high.days | number | yes | Days allowed to resolve a high finding, 1 to 3650. Rounded to a whole number. |
sla.high.target | number | yes | The share of findings that should meet it, 0 to 100. Rounded to a whole number. |
sla.medium | object | no | The window for medium findings. Send both values. |
sla.medium.days | number | yes | Days allowed to resolve a medium finding, 1 to 3650. Rounded to a whole number. |
sla.medium.target | number | yes | The share of findings that should meet it, 0 to 100. Rounded to a whole number. |
sla.low | object | no | The window for low findings. Send both values. |
sla.low.days | number | yes | Days allowed to resolve a low finding, 1 to 3650. Rounded to a whole number. |
sla.low.target | number | yes | The share of findings that should meet it, 0 to 100. Rounded to a whole number. |
minSecurityScore | number or null | no | The security score the organisation aims to stay above, 0 to 100, rounded to a whole number. Null removes the minimum. |
dataProtection | object | no | Data protection settings. Fields left out keep their values. Sending this object applies the retention period at once: anything already older than it is deleted before the call returns. |
dataProtection.framework | string | no | The law or standard to align data handling with, or none. Selecting one while no retention period is set, and without sending retentionDays, sets the period to 365 days. |
dataProtection.retentionDays | integer or null | no | Delete reviews, pentests, their logs and reports, and resolved findings older than this many days: a whole number from 7 to 3650. Null keeps them until deleted by hand. |
dataProtection.privacyContactEmail | string or null | no | Who privacy questions go to at the organisation. At most 254 characters. Null or an empty string clears it. |
dataProtection.breachContactEmail | string or null | no | Who Nullgap notifies about a security incident. At most 254 characters. Null or an empty string clears it. |
supplyChain | object | no | Package rules. Fields left out keep their values. |
supplyChain.blockedPackages | array of string | no | Packages that must not be used. Replaces the whole list. At most 500 entries; duplicates are dropped. |
supplyChain.allowedPackages | array of string | no | Packages exempt from the other rules and not raised as suspicious. Replaces the whole list. At most 500 entries; duplicates are dropped. |
supplyChain.installScriptAllowlist | array of string | no | Packages that may run a script at install time even when blockInstallScripts is on. Replaces the whole list. At most 500 entries; duplicates are dropped. |
supplyChain.blockInstallScripts | boolean | no | Block packages that run a script at install time, unless listed in installScriptAllowlist. |
supplyChain.minAgeDays | integer or null | no | Block versions published fewer than this many days ago: a whole number from 1 to 365. Null (or 0) removes the minimum. |
supplyChain.allowedRegistries | array of string | no | Registry hosts packages may come from besides the public registries. Replaces the whole list. At most 50 entries. Empty means any. |
scopeHosts | array of string | no | The hosts this organisation may point live testing at. Replaces the whole list. At most 100 entries, stored in lower case. Private, loopback and internal names are refused. The settings answer does not carry this list: read it with GET /api/orgs/{org}/scope-hosts. |
Example request
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"postChecks":true,"postComments":true,"postSystemComments":true,"requireMfa":false,"overage":false,"unverifiedFixes":true,"failCheckAt":"high","commentStyle":"standard","filters":[{"kind":"branch","mode":"exclude","value":"dependabot/*"}],"sla":{"critical":{"days":30,"target":90},"high":{"days":30,"target":90},"medium":{"days":30,"target":90},"low":{"days":30,"target":90}},"minSecurityScore":80,"dataProtection":{"framework":"gdpr","retentionDays":365,"privacyContactEmail":"privacy@acme.example","breachContactEmail":"security@acme.example"},"supplyChain":{"blockedPackages":["event-stream@3.3.6"],"allowedPackages":["@acme/*"],"installScriptAllowlist":["esbuild"],"blockInstallScripts":true,"minAgeDays":7,"allowedRegistries":["npm.acme.example"]},"scopeHosts":["staging.shop.acme.example"]}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/settings"
Answer (200, application/json)
A OrgSettings object.
{
"postChecks": true,
"postComments": true,
"postSystemComments": true,
"failCheckAt": "high",
"commentStyle": "standard",
"filters": [
{
"kind": "branch",
"mode": "exclude",
"value": "dependabot/*"
}
],
"sla": {
"critical": {
"days": 7,
"target": 95
},
"high": {
"days": 30,
"target": 90
},
"medium": {
"days": 90,
"target": 80
},
"low": {
"days": 180,
"target": 70
}
},
"minSecurityScore": 80,
"requireMfa": false,
"overage": false,
"unverifiedFixes": true,
"dataProtection": {
"framework": "gdpr",
"retentionDays": 365,
"privacyContactEmail": "privacy@acme.example",
"breachContactEmail": "security@acme.example"
},
"supplyChain": {
"blockedPackages": [
"event-stream@3.3.6"
],
"allowedPackages": [
"@acme/*"
],
"minAgeDays": 7,
"blockInstallScripts": true,
"installScriptAllowlist": [
"esbuild"
],
"allowedRegistries": [
"npm.acme.example"
]
},
"customChecks": [
{
"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 | bad_request | A field has the wrong type, is out of range, or (for package rules, registries and hosts) is not in the accepted form. The message names the field. |
| 400 | enrol_first | requireMfa is being switched on by someone whose own account has no multi-factor sign-in yet. |
| 403 | forbidden | An API key tried to change requireMfa. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Get the security overview
GET /api/orgs/{org}/overview
Answers the figures behind the console dashboard: open findings, the security score, how quickly findings are resolved, and review and pentest activity over a period ending now.
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. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
days | integer | no | How many days the period covers, 1 to 365. Default 30. Values outside the range are brought into it. |
Example request
curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/overview"
Answer (200, application/json)
A Overview object.
{
"periodDays": 30,
"reviews": 61,
"pentests": 1,
"criticalFindings": 1,
"activeRepositories": 4,
"openBySeverity": {
"critical": 1,
"high": 3,
"medium": 7,
"low": 4,
"info": 2
},
"fixed": 12,
"medianDaysToFix": 3.5,
"securityScore": 74,
"slaCompliance": {
"critical": 86,
"high": 86,
"medium": 86,
"low": 86
},
"resolution": {
"critical": {
"mttrDays": 4.2,
"medianDays": 3.5,
"fixed": 6,
"open": 2,
"overdue": 1,
"slaDays": 30,
"targetPercent": 90,
"compliancePercent": 86
},
"high": {
"mttrDays": 4.2,
"medianDays": 3.5,
"fixed": 6,
"open": 2,
"overdue": 1,
"slaDays": 30,
"targetPercent": 90,
"compliancePercent": 86
},
"medium": {
"mttrDays": 4.2,
"medianDays": 3.5,
"fixed": 6,
"open": 2,
"overdue": 1,
"slaDays": 30,
"targetPercent": 90,
"compliancePercent": 86
},
"low": {
"mttrDays": 4.2,
"medianDays": 3.5,
"fixed": 6,
"open": 2,
"overdue": 1,
"slaDays": 30,
"targetPercent": 90,
"compliancePercent": 86
}
},
"trend": [
{
"weekStart": "2026-11-09",
"opened": 5,
"fixed": 4
}
],
"prHealth": {
"reviewed": 61,
"withFindings": 9,
"findingsOpened": 14,
"findingsFixed": 10
},
"findingsAllTime": 48,
"volume": [
{
"date": "2026-11-16",
"reviews": 3,
"pentests": 0
}
],
"recentActivity": [
{
"id": "aud_7b2e90c41f6a",
"at": "2026-11-16T09:30:00.000Z",
"actor": "dana@acme.example",
"action": "member.role",
"target": "sam@acme.example",
"detail": "admin",
"seq": 128,
"hash": "9f2c4e7a1b3d5f60718293a4b5c6d7e8f90a1b2c3d4e5f60718293a4b5c6d7e8"
}
]
}
#List set-up steps
GET /api/orgs/{org}/onboarding
Answers the nine set-up steps in order, each with whether it is done. The link-account step is about the signed-in person, so it always reads as not done when called with an API key.
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/onboarding"
Answer (200, application/json)
The set-up steps, in the order the console shows them.
An array of OnboardingStep.
[
{
"id": "connect-repositories",
"group": "review",
"title": "Connect your repositories",
"done": true,
"href": "/acme/integrations"
}
]
#Objects
The objects the operations above take and return.
#Session
The signed-in person and the organisations they can open.
| Field | Type | Always present | Description |
|---|---|---|---|
user | User | yes | |
orgs | array of object | yes | The organisations this person belongs to. A single sign-on session lists only the organisation that issued it. |
orgs[].slug | string | yes | The organisation's slug, as used in API paths. |
orgs[].name | string | yes | The organisation's display name. |
orgs[].role | string | yes | This person's role in the organisation. One of: owner, admin, member. |
mfa | object | yes | The multi-factor state of this session. |
mfa.enrolled | boolean | yes | True when the account has multi-factor sign-in set up. |
mfa.verifiedAt | string or null | yes | When this session last passed a second-factor check. Null when it has not. |
method | string | yes | How this session signed in: github, single sign-on (sso), an e-mail link (link), a passkey, or dev on a development server. |
platformAdmin | boolean | no | Present, and true, only for the people who operate the service. |
workspaceCreation | string | yes | Whether a signed-in person may create a workspace with POST /api/orgs (open), or new workspaces are set up for invited clients only (invite-only); then join one through an invitation. |
#Org
An organisation: the workspace that repositories, findings and people belong to.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The organisation's id. |
slug | string | yes | The short name used in API paths and console addresses. |
name | string | yes | The display name. |
plan | string | yes | The organisation's plan. none means no trial has been started yet. |
trialEndsAt | string or null | yes | When the trial ends. Null when no trial was started. |
settings | OrgSettings | yes | |
createdAt | string | yes | When the organisation was created. |
suspended | boolean | no | Present, and true, only while Nullgap has suspended the workspace: reads keep working, nothing new runs and nothing can be changed. |
#User
A person with a Nullgap account.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The person's id. |
email | string | yes | Their e-mail address, in lower case. It identifies the account. |
name | string | yes | Their display name. |
githubLogin | string | no | Their linked code-host login, used to match pull request authors to seats. Absent when none is linked. |
createdAt | string | yes | When the account was created. |
#OrgSettings
How Nullgap behaves for an organisation.
| Field | Type | Always present | Description |
|---|---|---|---|
postChecks | boolean | yes | Show progress and results as a check on the commit. |
postComments | boolean | yes | Post the summary and the inline finding comments on the pull request. |
postSystemComments | boolean | yes | Post notices about skipped reviews, limits and configuration problems on the pull request. |
failCheckAt | string | yes | The check fails when a finding is at or above this severity. off never fails it. |
commentStyle | string | yes | How much detail pull request comments carry. One of: concise, standard, detailed. |
filters | array of ReviewFilter | yes | Rules that decide which pull requests are reviewed. Empty means every pull request. |
sla | object | yes | The resolution window and target for each severity. |
sla.critical | object | yes | The window and target for one severity. |
sla.critical.days | integer | yes | Days allowed to resolve a finding of this severity, counted from when it was first seen. |
sla.critical.target | integer | yes | The share of findings, 0 to 100, that should be resolved within that many days. |
sla.high | object | yes | The window and target for one severity. |
sla.high.days | integer | yes | Days allowed to resolve a finding of this severity, counted from when it was first seen. |
sla.high.target | integer | yes | The share of findings, 0 to 100, that should be resolved within that many days. |
sla.medium | object | yes | The window and target for one severity. |
sla.medium.days | integer | yes | Days allowed to resolve a finding of this severity, counted from when it was first seen. |
sla.medium.target | integer | yes | The share of findings, 0 to 100, that should be resolved within that many days. |
sla.low | object | yes | The window and target for one severity. |
sla.low.days | integer | yes | Days allowed to resolve a finding of this severity, counted from when it was first seen. |
sla.low.target | integer | yes | The share of findings, 0 to 100, that should be resolved within that many days. |
minSecurityScore | integer or null | yes | The security score, 0 to 100, the organisation aims to stay above. Null when no minimum is set. |
requireMfa | boolean | yes | True when every member must have multi-factor sign-in. |
overage | boolean | yes | True to allow pull request reviews beyond the included number, billed per review. |
unverifiedFixes | boolean | no | Whether a fix may be proposed when a finding cannot be reproduced: a draft pull request marked "[Not proven]", never counted as a verified fix. True unless an admin switched it off. Always present in the answers of the settings routes; it can be absent inside an Org saved before the switch existed, which reads as true. |
dataProtection | DataProtectionSettings | yes | |
supplyChain | SupplyChainPolicy | no | The package rules. Always present in the answers of the settings routes. It can be absent inside an Org created before the rules existed: read that as no rules. |
customChecks | array of CustomCheck | no | The organisation's own checks, when it has saved any. Managed through the custom-checks routes, not through the settings routes. |
#ReviewFilter
A rule that decides which pull requests are reviewed.
| Field | Type | Always present | Description |
|---|---|---|---|
kind | string | yes | What the filter looks at: a pull request label, its author, its branch, or a keyword. One of: label, author, branch, keyword. |
mode | string | yes | include: only matching pull requests are reviewed. exclude: matching pull requests are skipped. |
value | string | yes | The label, login, branch or keyword to match. At most 200 characters. |
#Overview
The organisation's security posture at a glance.
| Field | Type | Always present | Description |
|---|---|---|---|
periodDays | integer | yes | The number of days the figures cover, as asked for. |
reviews | integer | yes | Pull request reviews completed in the period. |
pentests | integer | yes | Pentests started in the period, leaving out cancelled and failed ones. |
criticalFindings | integer | yes | Critical findings that are open now. |
activeRepositories | integer | yes | Repositories with pull request reviews switched on. |
openBySeverity | object | yes | Open findings now, by severity. |
openBySeverity.critical | integer | yes | Open critical findings. |
openBySeverity.high | integer | yes | Open high findings. |
openBySeverity.medium | integer | yes | Open medium findings. |
openBySeverity.low | integer | yes | Open low findings. |
openBySeverity.info | integer | yes | Open informational findings. |
fixed | integer | yes | Findings fixed in the period. |
medianDaysToFix | number or null | yes | Median days from first seen to fixed, for findings fixed in the period. Null when none were. |
securityScore | integer or null | yes | The security score, 0 to 100, higher is better. It falls with open findings, weighted by severity, and with findings past their resolution window. Null until a review or pentest has completed. |
slaCompliance | object | yes | How well resolution windows are being met, by severity, in the period: findings fixed in the period, and open findings whose window ran out in the period (counted as missed). |
slaCompliance.critical | integer or null | yes | Share of critical findings resolved within their window, 0 to 100. Null when there is nothing to measure. |
slaCompliance.high | integer or null | yes | Share of high findings resolved within their window, 0 to 100. Null when there is nothing to measure. |
slaCompliance.medium | integer or null | yes | Share of medium findings resolved within their window, 0 to 100. Null when there is nothing to measure. |
slaCompliance.low | integer or null | yes | Share of low findings resolved within their window, 0 to 100. Null when there is nothing to measure. |
resolution | object | yes | How findings are being resolved, by severity. Times are in days from first seen to resolved. |
resolution.critical | object | yes | How critical findings are being resolved. |
resolution.critical.mttrDays | number or null | yes | Mean days from first seen to resolved, for findings fixed in the period. Null when none were. |
resolution.critical.medianDays | number or null | yes | Median days from first seen to resolved, for findings fixed in the period. Null when none were. |
resolution.critical.fixed | integer | yes | Findings of this severity fixed in the period. |
resolution.critical.open | integer | yes | Findings of this severity that are open now. |
resolution.critical.overdue | integer | yes | Open findings that have been open for longer than the resolution window. |
resolution.critical.slaDays | integer | yes | The organisation's resolution window for this severity, in days. |
resolution.critical.targetPercent | integer | yes | The organisation's target for this severity, 0 to 100. |
resolution.critical.compliancePercent | integer or null | yes | Share resolved within the window, 0 to 100, over the period: findings fixed in the period, with open findings whose window ran out in the period counted against it. Null when there is nothing to measure. |
resolution.high | object | yes | How high findings are being resolved. |
resolution.high.mttrDays | number or null | yes | Mean days from first seen to resolved, for findings fixed in the period. Null when none were. |
resolution.high.medianDays | number or null | yes | Median days from first seen to resolved, for findings fixed in the period. Null when none were. |
resolution.high.fixed | integer | yes | Findings of this severity fixed in the period. |
resolution.high.open | integer | yes | Findings of this severity that are open now. |
resolution.high.overdue | integer | yes | Open findings that have been open for longer than the resolution window. |
resolution.high.slaDays | integer | yes | The organisation's resolution window for this severity, in days. |
resolution.high.targetPercent | integer | yes | The organisation's target for this severity, 0 to 100. |
resolution.high.compliancePercent | integer or null | yes | Share resolved within the window, 0 to 100, over the period: findings fixed in the period, with open findings whose window ran out in the period counted against it. Null when there is nothing to measure. |
resolution.medium | object | yes | How medium findings are being resolved. |
resolution.medium.mttrDays | number or null | yes | Mean days from first seen to resolved, for findings fixed in the period. Null when none were. |
resolution.medium.medianDays | number or null | yes | Median days from first seen to resolved, for findings fixed in the period. Null when none were. |
resolution.medium.fixed | integer | yes | Findings of this severity fixed in the period. |
resolution.medium.open | integer | yes | Findings of this severity that are open now. |
resolution.medium.overdue | integer | yes | Open findings that have been open for longer than the resolution window. |
resolution.medium.slaDays | integer | yes | The organisation's resolution window for this severity, in days. |
resolution.medium.targetPercent | integer | yes | The organisation's target for this severity, 0 to 100. |
resolution.medium.compliancePercent | integer or null | yes | Share resolved within the window, 0 to 100, over the period: findings fixed in the period, with open findings whose window ran out in the period counted against it. Null when there is nothing to measure. |
resolution.low | object | yes | How low findings are being resolved. |
resolution.low.mttrDays | number or null | yes | Mean days from first seen to resolved, for findings fixed in the period. Null when none were. |
resolution.low.medianDays | number or null | yes | Median days from first seen to resolved, for findings fixed in the period. Null when none were. |
resolution.low.fixed | integer | yes | Findings of this severity fixed in the period. |
resolution.low.open | integer | yes | Findings of this severity that are open now. |
resolution.low.overdue | integer | yes | Open findings that have been open for longer than the resolution window. |
resolution.low.slaDays | integer | yes | The organisation's resolution window for this severity, in days. |
resolution.low.targetPercent | integer | yes | The organisation's target for this severity, 0 to 100. |
resolution.low.compliancePercent | integer or null | yes | Share resolved within the window, 0 to 100, over the period: findings fixed in the period, with open findings whose window ran out in the period counted against it. Null when there is nothing to measure. |
trend | array of object | yes | Findings first seen and fixed per week across the period, oldest first. Weeks end today, so the last one is the current week so far. |
trend[].weekStart | string | yes | The first day of the week, as YYYY-MM-DD. |
trend[].opened | integer | yes | Findings first seen in that week. |
trend[].fixed | integer | yes | Findings fixed in that week. |
prHealth | object | yes | Pull request reviews in the period and what became of their findings. |
prHealth.reviewed | integer | yes | Pull request reviews completed in the period. |
prHealth.withFindings | integer | yes | How many of those reported at least one finding. |
prHealth.findingsOpened | integer | yes | Findings from reviews first seen in the period. |
prHealth.findingsFixed | integer | yes | How many of those findings have been fixed. |
findingsAllTime | integer | yes | Findings ever raised in the organisation, in any state (open, fixed or decided). Zero means nothing has been found yet. |
volume | array of object | yes | Reviews and pentests per day across the period, oldest first. |
volume[].date | string | yes | The day, as YYYY-MM-DD, in UTC. |
volume[].reviews | integer | yes | Reviews created that day, leaving out skipped ones. |
volume[].pentests | integer | yes | Pentests created that day. |
recentActivity | array of AuditEvent | yes | The ten most recent audit events. |
#OnboardingStep
One step of getting an organisation set up.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | Which step this is. One of: connect-repositories, start-trial, enable-repository, turn-on-reviews, link-account, assign-seat, invite-teammate, add-payment-method, run-first-pentest. |
group | string | yes | The part of the product the step sets up: pull request reviews or pentests. One of: review, pentest. |
title | string | yes | The step in a few words. |
done | boolean | yes | True when the step is complete. |
href | string | yes | The console path where the step is completed. |
#DataProtectionSettings
How long data is kept and who is contacted about it.
| Field | Type | Always present | Description |
|---|---|---|---|
framework | string | yes | The law or standard the organisation has asked Nullgap to align its data handling with, or none. GET /api/trust lists them with their names. |
retentionDays | integer or null | yes | Reviews, pentests, their logs and reports, and resolved findings older than this many days are deleted automatically. Null keeps them until they are deleted by hand. |
privacyContactEmail | string or null | yes | Who privacy questions and requests from data subjects go to at the organisation. Null when not set. |
breachContactEmail | string or null | yes | Who Nullgap notifies about a security incident that affects the organisation's data. Null when not set. |
#SupplyChainPolicy
The organisation's rules about which packages may be used. They are applied by the package check and by the pull request check.
| Field | Type | Always present | Description |
|---|---|---|---|
blockedPackages | array of string | yes | Packages that must not be used. Each entry is a name, name@version, ecosystem:name, or a prefix ending in * such as @acme/*. |
allowedPackages | array of string | yes | Packages exempt from the rules below and not raised as suspicious. Being listed here never clears a malicious verdict. |
minAgeDays | integer or null | yes | Versions published fewer than this many days ago are blocked. Null means no minimum. |
blockInstallScripts | boolean | yes | True to block packages that run a script at install time, unless they are listed in installScriptAllowlist. |
installScriptAllowlist | array of string | yes | Packages that may run a script at install time even when blockInstallScripts is on. |
allowedRegistries | array of string | yes | Registry hosts packages may come from besides the public registries. Empty means any. |
#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. |
#AuditEvent
One entry in the organisation's audit log.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The event's id. |
at | string | yes | When it happened. |
actor | string | yes | Who did it: an e-mail address, api-key:<name> for an API key, or nullgap for the service itself. |
action | string | yes | What happened, as a dotted name. The part before the dot groups related actions. |
target | string or null | yes | What it was done to, when there is one. |
detail | string or null | yes | More about the change, when there is more to say. |
seq | integer | no | The event's position in the organisation's tamper-evident chain, starting at 1. Absent on events recorded before chaining existed. |
hash | string | no | A hash of this event and the one before it. Absent on events recorded before chaining existed. |
Nullgap documentation