Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
Get the getting-started guideGET /api/orgs/{org}/onboarding/guideread
Skip a step, or take the skip backPOST /api/orgs/{org}/onboarding/skipconsole only
Record that the welcome page was readPOST /api/orgs/{org}/onboarding/welcomeconsole 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

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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
stepstringyesThe step. One of: welcome, secure-account, connect-code, choose-repositories, first-result, first-finding, bring-team.
skippedbooleanyesTrue 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

StatusCodeWhen
403forbiddenThe 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

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

StatusCodeWhen
403forbiddenThe 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.

FieldTypeAlways presentDescription
stepsarray of OnboardingGuideStepyesThe seven steps, in order: welcome, secure-account, connect-code, choose-repositories, first-result, first-finding, bring-team.
nextstring or nullyesThe step. One of: welcome, secure-account, connect-code, choose-repositories, first-result, first-finding, bring-team, null.
finishedbooleanyesTrue when no step is left to do.
canManagebooleanyesTrue when the person asking is an admin or owner, and so can do the admin-only steps.
factsobjectyesWhat the guide's pages need to know about the workspace.
facts.codeHostsobjectyesWhich ways of giving access to code this server offers.
facts.codeHosts.githubbooleanyesGitHub can be connected.
facts.codeHosts.githubVerifiedbooleanyesLinking a GitHub installation is confirmed through GitHub.
facts.codeHosts.githubEnterprisebooleanyesGitHub Enterprise Server can be connected.
facts.codeHosts.gitlabbooleanyesGitLab can be connected.
facts.codeHosts.bitbucketbooleanyesBitbucket Cloud can be connected.
facts.codeHosts.azureDevopsbooleanyesAzure DevOps can be connected.
facts.codeHosts.archiveUploadbooleanyesA source archive can be uploaded.
facts.connectionsintegeryesConnected code hosts, not counting repositories added by address or upload.
facts.repositoriesintegeryesRepositories in the workspace.
facts.reviewableintegeryesRepositories that have pull requests Nullgap can review.
facts.reviewEnabledintegeryesRepositories with pull request review switched on.
facts.readOnlyintegeryesRepositories added by address or uploaded: pentests only.
facts.planActivebooleanyesWhether the workspace has an active trial or plan. Reviews run only with one.
facts.reviewsobjectyesReviews this month against what the plan includes.
facts.reviews.usedintegeryesPull request reviews this month.
facts.reviews.includedinteger or nullyesHow many the plan includes. Null when the plan does not count them.
facts.penteststringyesWhether 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.firstReviewobject or nullyesThe first review that actually ran, or the newest when none has finished. Null when there is none.
facts.firstReview.idstringyesThe run id.
facts.firstReview.repoFullNamestringyesThe repository it ran on.
facts.firstReview.statusstringyesWhere it stands. One of: queued, running, completed, failed, skipped, cancelled.
facts.firstReview.findingsCountintegeryesHow many findings it raised.
facts.firstReview.createdAtstringyesWhen it was asked for.
facts.firstReview.finishedAtstring or nullyesWhen it ended.
facts.firstReview.prNumberintegernoThe pull request number. Reviews only.
facts.firstReview.skipReasonstring or nullnoWhy it was not reviewed. Reviews only.
facts.firstReview.phasestring or nullnoWhat it is doing now. Pentests only.
facts.firstPentestobject or nullyesThe first pentest, the same way. Null when there is none.
facts.firstPentest.idstringyesThe run id.
facts.firstPentest.repoFullNamestringyesThe repository it ran on.
facts.firstPentest.statusstringyesWhere it stands. One of: queued, running, completed, failed, skipped, cancelled.
facts.firstPentest.findingsCountintegeryesHow many findings it raised.
facts.firstPentest.createdAtstringyesWhen it was asked for.
facts.firstPentest.finishedAtstring or nullyesWhen it ended.
facts.firstPentest.prNumberintegernoThe pull request number. Reviews only.
facts.firstPentest.skipReasonstring or nullnoWhy it was not reviewed. Reviews only.
facts.firstPentest.phasestring or nullnoWhat it is doing now. Pentests only.
facts.findingsintegeryesFindings in the workspace.
facts.firstFindingIdstring or nullyesThe finding the "read your first finding" step opens.
facts.timingobjectyesHow long runs take on this server.
facts.timing.reviewobjectyesPull request reviews.
facts.timing.review.typicalMinutesinteger or nullyesHow long one usually takes on this server, from finished runs. Null when there are too few to say.
facts.timing.review.limitMinutesintegeryesA run is stopped when it reaches this.
facts.timing.pentestobjectyesPentests.
facts.timing.pentest.typicalMinutesinteger or nullyesHow long one usually takes on this server, from finished runs. Null when there are too few to say.
facts.timing.pentest.limitMinutesintegeryesA run is stopped when it reaches this.
facts.mailbooleanyesWhether 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.

FieldTypeAlways presentDescription
idstringyesThe step. One of: welcome, secure-account, connect-code, choose-repositories, first-result, first-finding, bring-team.
scopestringyesorganisation: one state shared by everyone. person: each member has their own (the welcome page, securing their account).
adminOnlybooleanyesTrue when only an admin or owner can do it. A member is told so instead of being offered the action.
optionalbooleanyesTrue when nothing else depends on it.
statusstringyesdone 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.
doneAtstring or nullyesWhen it became done.
skippedobject or nullyesWho chose to skip it and when. Cleared by itself once the step is really done.
skipped.atstringyesWhen.
skipped.bystringyesWho.
itemsarray of objectyesThe 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[].idstringyesThe item.
items[].donebooleanyesWhether it is done.
items[].doneAtstring or nullyesWhen it became done.

Nullgap documentation