Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
Get the current sessionGET /api/sessionnone
Create an organisationPOST /api/orgsconsole session
Update your profilePATCH /api/meconsole session
Get the organisationGET /api/orgs/{org}read
Rename the organisationPATCH /api/orgs/{org}admin
Get the live-testing scope listGET /api/orgs/{org}/scope-hostsread
Get the settingsGET /api/orgs/{org}/settingsread
Change the settingsPATCH /api/orgs/{org}/settingsadmin
Get the security overviewGET /api/orgs/{org}/overviewread
List set-up stepsGET /api/orgs/{org}/onboardingread

#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

StatusCodeWhen
401mfa_pendingThe 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)

FieldTypeRequiredDescription
namestringyesThe organisation's name. 1 to 80 characters.
acceptTermsbooleannoSend 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

StatusCodeWhen
403sso_sessionThe session signed in through single sign-on, which may not create organisations.
403workspace_creation_closedThis 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)

FieldTypeRequiredDescription
namestringnoYour display name. 1 to 100 characters.
githubLoginstring or nullnoYour 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

StatusCodeWhen
400bad_requestgithubLogin is not a valid login, or name is empty or too long.
403sso_sessionThe 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

NameTypeRequiredDescription
orgstringyesThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
namestringnoThe new display name. 1 to 80 characters.
slugstringnoThe 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

StatusCodeWhen
400bad_requestThe slug has characters other than lower-case letters, digits and dashes, or is a reserved name.
409slug_takenAnother 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

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

Answer (200, application/json)

FieldTypeAlways presentDescription
hostsarray of stringyesThe 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

NameTypeRequiredDescription
orgstringyesThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
postChecksbooleannoShow progress and results as a check on the commit.
postCommentsbooleannoPost the summary and the inline finding comments on the pull request.
postSystemCommentsbooleannoPost notices about skipped reviews, limits and configuration problems on the pull request.
requireMfabooleannoRequire 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.
overagebooleannoAllow pull request reviews beyond the included number, billed per review.
unverifiedFixesbooleannoAllow 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.
failCheckAtstringnoFail the check when a finding is at or above this severity. off never fails it.
commentStylestringnoHow much detail pull request comments carry. One of: concise, standard, detailed.
filtersarray of ReviewFilternoWhich pull requests are reviewed. Replaces the whole list. At most 100 filters.
slaobjectnoResolution windows by severity. Severities left out keep their values.
sla.criticalobjectnoThe window for critical findings. Send both values.
sla.critical.daysnumberyesDays allowed to resolve a critical finding, 1 to 3650. Rounded to a whole number.
sla.critical.targetnumberyesThe share of findings that should meet it, 0 to 100. Rounded to a whole number.
sla.highobjectnoThe window for high findings. Send both values.
sla.high.daysnumberyesDays allowed to resolve a high finding, 1 to 3650. Rounded to a whole number.
sla.high.targetnumberyesThe share of findings that should meet it, 0 to 100. Rounded to a whole number.
sla.mediumobjectnoThe window for medium findings. Send both values.
sla.medium.daysnumberyesDays allowed to resolve a medium finding, 1 to 3650. Rounded to a whole number.
sla.medium.targetnumberyesThe share of findings that should meet it, 0 to 100. Rounded to a whole number.
sla.lowobjectnoThe window for low findings. Send both values.
sla.low.daysnumberyesDays allowed to resolve a low finding, 1 to 3650. Rounded to a whole number.
sla.low.targetnumberyesThe share of findings that should meet it, 0 to 100. Rounded to a whole number.
minSecurityScorenumber or nullnoThe security score the organisation aims to stay above, 0 to 100, rounded to a whole number. Null removes the minimum.
dataProtectionobjectnoData 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.frameworkstringnoThe 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.retentionDaysinteger or nullnoDelete 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.privacyContactEmailstring or nullnoWho privacy questions go to at the organisation. At most 254 characters. Null or an empty string clears it.
dataProtection.breachContactEmailstring or nullnoWho Nullgap notifies about a security incident. At most 254 characters. Null or an empty string clears it.
supplyChainobjectnoPackage rules. Fields left out keep their values.
supplyChain.blockedPackagesarray of stringnoPackages that must not be used. Replaces the whole list. At most 500 entries; duplicates are dropped.
supplyChain.allowedPackagesarray of stringnoPackages exempt from the other rules and not raised as suspicious. Replaces the whole list. At most 500 entries; duplicates are dropped.
supplyChain.installScriptAllowlistarray of stringnoPackages 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.blockInstallScriptsbooleannoBlock packages that run a script at install time, unless listed in installScriptAllowlist.
supplyChain.minAgeDaysinteger or nullnoBlock versions published fewer than this many days ago: a whole number from 1 to 365. Null (or 0) removes the minimum.
supplyChain.allowedRegistriesarray of stringnoRegistry hosts packages may come from besides the public registries. Replaces the whole list. At most 50 entries. Empty means any.
scopeHostsarray of stringnoThe 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

StatusCodeWhen
400bad_requestA 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.
400enrol_firstrequireMfa is being switched on by someone whose own account has no multi-factor sign-in yet.
403forbiddenAn API key tried to change requireMfa.
403step_up_requiredYour 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
daysintegernoHow 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

NameTypeRequiredDescription
orgstringyesThe 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.

FieldTypeAlways presentDescription
userUseryes
orgsarray of objectyesThe organisations this person belongs to. A single sign-on session lists only the organisation that issued it.
orgs[].slugstringyesThe organisation's slug, as used in API paths.
orgs[].namestringyesThe organisation's display name.
orgs[].rolestringyesThis person's role in the organisation. One of: owner, admin, member.
mfaobjectyesThe multi-factor state of this session.
mfa.enrolledbooleanyesTrue when the account has multi-factor sign-in set up.
mfa.verifiedAtstring or nullyesWhen this session last passed a second-factor check. Null when it has not.
methodstringyesHow this session signed in: github, single sign-on (sso), an e-mail link (link), a passkey, or dev on a development server.
platformAdminbooleannoPresent, and true, only for the people who operate the service.
workspaceCreationstringyesWhether 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.

FieldTypeAlways presentDescription
idstringyesThe organisation's id.
slugstringyesThe short name used in API paths and console addresses.
namestringyesThe display name.
planstringyesThe organisation's plan. none means no trial has been started yet.
trialEndsAtstring or nullyesWhen the trial ends. Null when no trial was started.
settingsOrgSettingsyes
createdAtstringyesWhen the organisation was created.
suspendedbooleannoPresent, 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.

FieldTypeAlways presentDescription
idstringyesThe person's id.
emailstringyesTheir e-mail address, in lower case. It identifies the account.
namestringyesTheir display name.
githubLoginstringnoTheir linked code-host login, used to match pull request authors to seats. Absent when none is linked.
createdAtstringyesWhen the account was created.

#OrgSettings

How Nullgap behaves for an organisation.

FieldTypeAlways presentDescription
postChecksbooleanyesShow progress and results as a check on the commit.
postCommentsbooleanyesPost the summary and the inline finding comments on the pull request.
postSystemCommentsbooleanyesPost notices about skipped reviews, limits and configuration problems on the pull request.
failCheckAtstringyesThe check fails when a finding is at or above this severity. off never fails it.
commentStylestringyesHow much detail pull request comments carry. One of: concise, standard, detailed.
filtersarray of ReviewFilteryesRules that decide which pull requests are reviewed. Empty means every pull request.
slaobjectyesThe resolution window and target for each severity.
sla.criticalobjectyesThe window and target for one severity.
sla.critical.daysintegeryesDays allowed to resolve a finding of this severity, counted from when it was first seen.
sla.critical.targetintegeryesThe share of findings, 0 to 100, that should be resolved within that many days.
sla.highobjectyesThe window and target for one severity.
sla.high.daysintegeryesDays allowed to resolve a finding of this severity, counted from when it was first seen.
sla.high.targetintegeryesThe share of findings, 0 to 100, that should be resolved within that many days.
sla.mediumobjectyesThe window and target for one severity.
sla.medium.daysintegeryesDays allowed to resolve a finding of this severity, counted from when it was first seen.
sla.medium.targetintegeryesThe share of findings, 0 to 100, that should be resolved within that many days.
sla.lowobjectyesThe window and target for one severity.
sla.low.daysintegeryesDays allowed to resolve a finding of this severity, counted from when it was first seen.
sla.low.targetintegeryesThe share of findings, 0 to 100, that should be resolved within that many days.
minSecurityScoreinteger or nullyesThe security score, 0 to 100, the organisation aims to stay above. Null when no minimum is set.
requireMfabooleanyesTrue when every member must have multi-factor sign-in.
overagebooleanyesTrue to allow pull request reviews beyond the included number, billed per review.
unverifiedFixesbooleannoWhether 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.
dataProtectionDataProtectionSettingsyes
supplyChainSupplyChainPolicynoThe 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.
customChecksarray of CustomChecknoThe 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.

FieldTypeAlways presentDescription
kindstringyesWhat the filter looks at: a pull request label, its author, its branch, or a keyword. One of: label, author, branch, keyword.
modestringyesinclude: only matching pull requests are reviewed. exclude: matching pull requests are skipped.
valuestringyesThe label, login, branch or keyword to match. At most 200 characters.

#Overview

The organisation's security posture at a glance.

FieldTypeAlways presentDescription
periodDaysintegeryesThe number of days the figures cover, as asked for.
reviewsintegeryesPull request reviews completed in the period.
pentestsintegeryesPentests started in the period, leaving out cancelled and failed ones.
criticalFindingsintegeryesCritical findings that are open now.
activeRepositoriesintegeryesRepositories with pull request reviews switched on.
openBySeverityobjectyesOpen findings now, by severity.
openBySeverity.criticalintegeryesOpen critical findings.
openBySeverity.highintegeryesOpen high findings.
openBySeverity.mediumintegeryesOpen medium findings.
openBySeverity.lowintegeryesOpen low findings.
openBySeverity.infointegeryesOpen informational findings.
fixedintegeryesFindings fixed in the period.
medianDaysToFixnumber or nullyesMedian days from first seen to fixed, for findings fixed in the period. Null when none were.
securityScoreinteger or nullyesThe 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.
slaComplianceobjectyesHow 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.criticalinteger or nullyesShare of critical findings resolved within their window, 0 to 100. Null when there is nothing to measure.
slaCompliance.highinteger or nullyesShare of high findings resolved within their window, 0 to 100. Null when there is nothing to measure.
slaCompliance.mediuminteger or nullyesShare of medium findings resolved within their window, 0 to 100. Null when there is nothing to measure.
slaCompliance.lowinteger or nullyesShare of low findings resolved within their window, 0 to 100. Null when there is nothing to measure.
resolutionobjectyesHow findings are being resolved, by severity. Times are in days from first seen to resolved.
resolution.criticalobjectyesHow critical findings are being resolved.
resolution.critical.mttrDaysnumber or nullyesMean days from first seen to resolved, for findings fixed in the period. Null when none were.
resolution.critical.medianDaysnumber or nullyesMedian days from first seen to resolved, for findings fixed in the period. Null when none were.
resolution.critical.fixedintegeryesFindings of this severity fixed in the period.
resolution.critical.openintegeryesFindings of this severity that are open now.
resolution.critical.overdueintegeryesOpen findings that have been open for longer than the resolution window.
resolution.critical.slaDaysintegeryesThe organisation's resolution window for this severity, in days.
resolution.critical.targetPercentintegeryesThe organisation's target for this severity, 0 to 100.
resolution.critical.compliancePercentinteger or nullyesShare 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.highobjectyesHow high findings are being resolved.
resolution.high.mttrDaysnumber or nullyesMean days from first seen to resolved, for findings fixed in the period. Null when none were.
resolution.high.medianDaysnumber or nullyesMedian days from first seen to resolved, for findings fixed in the period. Null when none were.
resolution.high.fixedintegeryesFindings of this severity fixed in the period.
resolution.high.openintegeryesFindings of this severity that are open now.
resolution.high.overdueintegeryesOpen findings that have been open for longer than the resolution window.
resolution.high.slaDaysintegeryesThe organisation's resolution window for this severity, in days.
resolution.high.targetPercentintegeryesThe organisation's target for this severity, 0 to 100.
resolution.high.compliancePercentinteger or nullyesShare 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.mediumobjectyesHow medium findings are being resolved.
resolution.medium.mttrDaysnumber or nullyesMean days from first seen to resolved, for findings fixed in the period. Null when none were.
resolution.medium.medianDaysnumber or nullyesMedian days from first seen to resolved, for findings fixed in the period. Null when none were.
resolution.medium.fixedintegeryesFindings of this severity fixed in the period.
resolution.medium.openintegeryesFindings of this severity that are open now.
resolution.medium.overdueintegeryesOpen findings that have been open for longer than the resolution window.
resolution.medium.slaDaysintegeryesThe organisation's resolution window for this severity, in days.
resolution.medium.targetPercentintegeryesThe organisation's target for this severity, 0 to 100.
resolution.medium.compliancePercentinteger or nullyesShare 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.lowobjectyesHow low findings are being resolved.
resolution.low.mttrDaysnumber or nullyesMean days from first seen to resolved, for findings fixed in the period. Null when none were.
resolution.low.medianDaysnumber or nullyesMedian days from first seen to resolved, for findings fixed in the period. Null when none were.
resolution.low.fixedintegeryesFindings of this severity fixed in the period.
resolution.low.openintegeryesFindings of this severity that are open now.
resolution.low.overdueintegeryesOpen findings that have been open for longer than the resolution window.
resolution.low.slaDaysintegeryesThe organisation's resolution window for this severity, in days.
resolution.low.targetPercentintegeryesThe organisation's target for this severity, 0 to 100.
resolution.low.compliancePercentinteger or nullyesShare 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.
trendarray of objectyesFindings 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[].weekStartstringyesThe first day of the week, as YYYY-MM-DD.
trend[].openedintegeryesFindings first seen in that week.
trend[].fixedintegeryesFindings fixed in that week.
prHealthobjectyesPull request reviews in the period and what became of their findings.
prHealth.reviewedintegeryesPull request reviews completed in the period.
prHealth.withFindingsintegeryesHow many of those reported at least one finding.
prHealth.findingsOpenedintegeryesFindings from reviews first seen in the period.
prHealth.findingsFixedintegeryesHow many of those findings have been fixed.
findingsAllTimeintegeryesFindings ever raised in the organisation, in any state (open, fixed or decided). Zero means nothing has been found yet.
volumearray of objectyesReviews and pentests per day across the period, oldest first.
volume[].datestringyesThe day, as YYYY-MM-DD, in UTC.
volume[].reviewsintegeryesReviews created that day, leaving out skipped ones.
volume[].pentestsintegeryesPentests created that day.
recentActivityarray of AuditEventyesThe ten most recent audit events.

#OnboardingStep

One step of getting an organisation set up.

FieldTypeAlways presentDescription
idstringyesWhich 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.
groupstringyesThe part of the product the step sets up: pull request reviews or pentests. One of: review, pentest.
titlestringyesThe step in a few words.
donebooleanyesTrue when the step is complete.
hrefstringyesThe console path where the step is completed.

#DataProtectionSettings

How long data is kept and who is contacted about it.

FieldTypeAlways presentDescription
frameworkstringyesThe law or standard the organisation has asked Nullgap to align its data handling with, or none. GET /api/trust lists them with their names.
retentionDaysinteger or nullyesReviews, 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.
privacyContactEmailstring or nullyesWho privacy questions and requests from data subjects go to at the organisation. Null when not set.
breachContactEmailstring or nullyesWho 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.

FieldTypeAlways presentDescription
blockedPackagesarray of stringyesPackages that must not be used. Each entry is a name, name@version, ecosystem:name, or a prefix ending in * such as @acme/*.
allowedPackagesarray of stringyesPackages exempt from the rules below and not raised as suspicious. Being listed here never clears a malicious verdict.
minAgeDaysinteger or nullyesVersions published fewer than this many days ago are blocked. Null means no minimum.
blockInstallScriptsbooleanyesTrue to block packages that run a script at install time, unless they are listed in installScriptAllowlist.
installScriptAllowlistarray of stringyesPackages that may run a script at install time even when blockInstallScripts is on.
allowedRegistriesarray of stringyesRegistry 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.

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.

#AuditEvent

One entry in the organisation's audit log.

FieldTypeAlways presentDescription
idstringyesThe event's id.
atstringyesWhen it happened.
actorstringyesWho did it: an e-mail address, api-key:<name> for an API key, or nullgap for the service itself.
actionstringyesWhat happened, as a dotted name. The part before the dot groups related actions.
targetstring or nullyesWhat it was done to, when there is one.
detailstring or nullyesMore about the change, when there is more to say.
seqintegernoThe event's position in the organisation's tamper-evident chain, starting at 1. Absent on events recorded before chaining existed.
hashstringnoA hash of this event and the one before it. Absent on events recorded before chaining existed.

Nullgap documentation