API reference
Getting started
The guided first-run steps of a new organisation, as the console shows them.
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 getting-started guide | GET /api/orgs/{org}/onboarding/guide | read |
| Skip a step, or take the skip back | POST /api/orgs/{org}/onboarding/skip | console only |
| Record that the welcome page was read | POST /api/orgs/{org}/onboarding/welcome | console only |
#Get the getting-started guide
GET /api/orgs/{org}/onboarding/guide
Returns the seven steps a new organisation follows, each with whether it is done, to do or skipped for the caller, together with the facts the steps are judged by (connections, repositories, the first review and pentest, typical run times). Whether a step is done is worked out from what exists in the workspace each time this is called. Two steps belong to the person, not the organisation (welcome and secure-account), so with an API key they always read as not done.
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/guide"
Answer (200, application/json)
A OnboardingGuide object.
{
"steps": [
{
"id": "connect-code",
"scope": "organisation",
"adminOnly": true,
"optional": false,
"status": "todo",
"doneAt": "2026-11-16T09:30:00.000Z",
"skipped": {
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example"
},
"items": [
{
"id": "review",
"done": false,
"doneAt": "2026-11-16T09:30:00.000Z"
}
]
}
],
"next": "connect-code",
"finished": false,
"canManage": true,
"facts": {
"codeHosts": {
"github": true,
"githubVerified": true,
"githubEnterprise": true,
"gitlab": true,
"bitbucket": true,
"azureDevops": true,
"archiveUpload": true
},
"connections": 1,
"repositories": 12,
"reviewable": 11,
"reviewEnabled": 3,
"readOnly": 1,
"planActive": true,
"reviews": {
"used": 4,
"included": 200
},
"pentest": "included",
"firstReview": {
"id": "rev_2a6d9f1c4b7e",
"repoFullName": "acme/shop",
"status": "completed",
"findingsCount": 2,
"createdAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:41:00.000Z",
"prNumber": 128,
"skipReason": "draft",
"phase": "verifying"
},
"firstPentest": {
"id": "rev_2a6d9f1c4b7e",
"repoFullName": "acme/shop",
"status": "completed",
"findingsCount": 2,
"createdAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:41:00.000Z",
"prNumber": 128,
"skipReason": "draft",
"phase": "verifying"
},
"findings": 2,
"firstFindingId": "fnd_8f3a2c9d1b4e",
"timing": {
"review": {
"typicalMinutes": 6,
"limitMinutes": 30
},
"pentest": {
"typicalMinutes": 6,
"limitMinutes": 30
}
},
"mail": true
}
}
#Skip a step, or take the skip back
POST /api/orgs/{org}/onboarding/skip
Records that a step is being left for later, or removes that record. Skipping never marks a step done, and a skip is cleared by itself once the step really is done. A person skips their own steps (welcome, secure-account) for themselves; a step of the organisation is skipped for everyone, so only an admin or owner may. Answers with the guide as it now stands.
Who may call it: A signed-in person in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
step | string | yes | The step. One of: welcome, secure-account, connect-code, choose-repositories, first-result, first-finding, bring-team. |
skipped | boolean | yes | True to skip it, false to take the skip back. |
Answer (200, application/json)
A OnboardingGuide object.
{
"steps": [
{
"id": "connect-code",
"scope": "organisation",
"adminOnly": true,
"optional": false,
"status": "todo",
"doneAt": "2026-11-16T09:30:00.000Z",
"skipped": {
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example"
},
"items": [
{
"id": "review",
"done": false,
"doneAt": "2026-11-16T09:30:00.000Z"
}
]
}
],
"next": "connect-code",
"finished": false,
"canManage": true,
"facts": {
"codeHosts": {
"github": true,
"githubVerified": true,
"githubEnterprise": true,
"gitlab": true,
"bitbucket": true,
"azureDevops": true,
"archiveUpload": true
},
"connections": 1,
"repositories": 12,
"reviewable": 11,
"reviewEnabled": 3,
"readOnly": 1,
"planActive": true,
"reviews": {
"used": 4,
"included": 200
},
"pentest": "included",
"firstReview": {
"id": "rev_2a6d9f1c4b7e",
"repoFullName": "acme/shop",
"status": "completed",
"findingsCount": 2,
"createdAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:41:00.000Z",
"prNumber": 128,
"skipReason": "draft",
"phase": "verifying"
},
"firstPentest": {
"id": "rev_2a6d9f1c4b7e",
"repoFullName": "acme/shop",
"status": "completed",
"findingsCount": 2,
"createdAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:41:00.000Z",
"prNumber": 128,
"skipReason": "draft",
"phase": "verifying"
},
"findings": 2,
"firstFindingId": "fnd_8f3a2c9d1b4e",
"timing": {
"review": {
"typicalMinutes": 6,
"limitMinutes": 30
},
"pentest": {
"typicalMinutes": 6,
"limitMinutes": 30
}
},
"mail": true
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The call was made with an API key, or the step belongs to the organisation and you are not an admin or owner. |
#Record that the welcome page was read
POST /api/orgs/{org}/onboarding/welcome
Marks the welcome step done for the signed-in person. It is the one step with nothing in the workspace to judge it by, so the person says so. Calling it again changes nothing. Takes no body. Answers with the guide as it now stands.
Who may call it: A signed-in person in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Answer (200, application/json)
A OnboardingGuide object.
{
"steps": [
{
"id": "connect-code",
"scope": "organisation",
"adminOnly": true,
"optional": false,
"status": "todo",
"doneAt": "2026-11-16T09:30:00.000Z",
"skipped": {
"at": "2026-11-16T09:30:00.000Z",
"by": "dana@acme.example"
},
"items": [
{
"id": "review",
"done": false,
"doneAt": "2026-11-16T09:30:00.000Z"
}
]
}
],
"next": "connect-code",
"finished": false,
"canManage": true,
"facts": {
"codeHosts": {
"github": true,
"githubVerified": true,
"githubEnterprise": true,
"gitlab": true,
"bitbucket": true,
"azureDevops": true,
"archiveUpload": true
},
"connections": 1,
"repositories": 12,
"reviewable": 11,
"reviewEnabled": 3,
"readOnly": 1,
"planActive": true,
"reviews": {
"used": 4,
"included": 200
},
"pentest": "included",
"firstReview": {
"id": "rev_2a6d9f1c4b7e",
"repoFullName": "acme/shop",
"status": "completed",
"findingsCount": 2,
"createdAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:41:00.000Z",
"prNumber": 128,
"skipReason": "draft",
"phase": "verifying"
},
"firstPentest": {
"id": "rev_2a6d9f1c4b7e",
"repoFullName": "acme/shop",
"status": "completed",
"findingsCount": 2,
"createdAt": "2026-11-16T09:30:00.000Z",
"finishedAt": "2026-11-16T09:41:00.000Z",
"prNumber": 128,
"skipReason": "draft",
"phase": "verifying"
},
"findings": 2,
"firstFindingId": "fnd_8f3a2c9d1b4e",
"timing": {
"review": {
"typicalMinutes": 6,
"limitMinutes": 30
},
"pentest": {
"typicalMinutes": 6,
"limitMinutes": 30
}
},
"mail": true
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The call was made with an API key. This is something a signed-in person does. |
#Objects
The objects the operations above take and return.
#OnboardingGuide
The getting-started guide as it stands for the person asking. next is the first step that is neither done nor skipped, or null when nothing is left.
| Field | Type | Always present | Description |
|---|---|---|---|
steps | array of OnboardingGuideStep | yes | The seven steps, in order: welcome, secure-account, connect-code, choose-repositories, first-result, first-finding, bring-team. |
next | string or null | yes | The step. One of: welcome, secure-account, connect-code, choose-repositories, first-result, first-finding, bring-team, null. |
finished | boolean | yes | True when no step is left to do. |
canManage | boolean | yes | True when the person asking is an admin or owner, and so can do the admin-only steps. |
facts | object | yes | What the guide's pages need to know about the workspace. |
facts.codeHosts | object | yes | Which ways of giving access to code this server offers. |
facts.codeHosts.github | boolean | yes | GitHub can be connected. |
facts.codeHosts.githubVerified | boolean | yes | Linking a GitHub installation is confirmed through GitHub. |
facts.codeHosts.githubEnterprise | boolean | yes | GitHub Enterprise Server can be connected. |
facts.codeHosts.gitlab | boolean | yes | GitLab can be connected. |
facts.codeHosts.bitbucket | boolean | yes | Bitbucket Cloud can be connected. |
facts.codeHosts.azureDevops | boolean | yes | Azure DevOps can be connected. |
facts.codeHosts.archiveUpload | boolean | yes | A source archive can be uploaded. |
facts.connections | integer | yes | Connected code hosts, not counting repositories added by address or upload. |
facts.repositories | integer | yes | Repositories in the workspace. |
facts.reviewable | integer | yes | Repositories that have pull requests Nullgap can review. |
facts.reviewEnabled | integer | yes | Repositories with pull request review switched on. |
facts.readOnly | integer | yes | Repositories added by address or uploaded: pentests only. |
facts.planActive | boolean | yes | Whether the workspace has an active trial or plan. Reviews run only with one. |
facts.reviews | object | yes | Reviews this month against what the plan includes. |
facts.reviews.used | integer | yes | Pull request reviews this month. |
facts.reviews.included | integer or null | yes | How many the plan includes. Null when the plan does not count them. |
facts.pentest | string | yes | Whether a pentest is part of the plan or priced per run. The price is shown where a pentest is started. One of: included, priced. |
facts.firstReview | object or null | yes | The first review that actually ran, or the newest when none has finished. Null when there is none. |
facts.firstReview.id | string | yes | The run id. |
facts.firstReview.repoFullName | string | yes | The repository it ran on. |
facts.firstReview.status | string | yes | Where it stands. One of: queued, running, completed, failed, skipped, cancelled. |
facts.firstReview.findingsCount | integer | yes | How many findings it raised. |
facts.firstReview.createdAt | string | yes | When it was asked for. |
facts.firstReview.finishedAt | string or null | yes | When it ended. |
facts.firstReview.prNumber | integer | no | The pull request number. Reviews only. |
facts.firstReview.skipReason | string or null | no | Why it was not reviewed. Reviews only. |
facts.firstReview.phase | string or null | no | What it is doing now. Pentests only. |
facts.firstPentest | object or null | yes | The first pentest, the same way. Null when there is none. |
facts.firstPentest.id | string | yes | The run id. |
facts.firstPentest.repoFullName | string | yes | The repository it ran on. |
facts.firstPentest.status | string | yes | Where it stands. One of: queued, running, completed, failed, skipped, cancelled. |
facts.firstPentest.findingsCount | integer | yes | How many findings it raised. |
facts.firstPentest.createdAt | string | yes | When it was asked for. |
facts.firstPentest.finishedAt | string or null | yes | When it ended. |
facts.firstPentest.prNumber | integer | no | The pull request number. Reviews only. |
facts.firstPentest.skipReason | string or null | no | Why it was not reviewed. Reviews only. |
facts.firstPentest.phase | string or null | no | What it is doing now. Pentests only. |
facts.findings | integer | yes | Findings in the workspace. |
facts.firstFindingId | string or null | yes | The finding the "read your first finding" step opens. |
facts.timing | object | yes | How long runs take on this server. |
facts.timing.review | object | yes | Pull request reviews. |
facts.timing.review.typicalMinutes | integer or null | yes | How long one usually takes on this server, from finished runs. Null when there are too few to say. |
facts.timing.review.limitMinutes | integer | yes | A run is stopped when it reaches this. |
facts.timing.pentest | object | yes | Pentests. |
facts.timing.pentest.typicalMinutes | integer or null | yes | How long one usually takes on this server, from finished runs. Null when there are too few to say. |
facts.timing.pentest.limitMinutes | integer | yes | A run is stopped when it reaches this. |
facts.mail | boolean | yes | Whether this server sends e-mail (invitations, the message that a first result is ready). |
#OnboardingGuideStep
One step of the getting-started guide, for the person asking.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The step. One of: welcome, secure-account, connect-code, choose-repositories, first-result, first-finding, bring-team. |
scope | string | yes | organisation: one state shared by everyone. person: each member has their own (the welcome page, securing their account). |
adminOnly | boolean | yes | True when only an admin or owner can do it. A member is told so instead of being offered the action. |
optional | boolean | yes | True when nothing else depends on it. |
status | string | yes | done is always worked out from what exists in the workspace (a connection, a repository under review, a finished run); it cannot be set by a call. |
doneAt | string or null | yes | When it became done. |
skipped | object or null | yes | Who chose to skip it and when. Cleared by itself once the step is really done. |
skipped.at | string | yes | When. |
skipped.by | string | yes | Who. |
items | array of object | yes | The parts of a step that are done or not on their own, for a step with more than one way to finish it. Empty for most steps. |
items[].id | string | yes | The item. |
items[].done | boolean | yes | Whether it is done. |
items[].doneAt | string or null | yes | When it became done. |
Nullgap documentation