Nullgap.dev Docs

API reference

Code hosts and repositories

Connect code hosts, list repositories, add a public repository or upload an archive.

Paths are relative to the address of your Nullgap console. Authentication, errors, paging and rate limits are the same for every call and are described in the API overview.

OperationMethod and pathWho may call it
List connectionsGET /api/orgs/{org}/connectionsread
Get the GitHub install linkGET /api/orgs/{org}/connections/github/installadmin
Begin verifying a GitHub installationPOST /api/orgs/{org}/connections/github/verifyconsole only (admin)
Link a GitHub installationPOST /api/orgs/{org}/connections/github/claimadmin
Remove a connectionDELETE /api/orgs/{org}/connections/{id}admin
Sync repositoriesPOST /api/orgs/{org}/repositories/syncadmin
List repositoriesGET /api/orgs/{org}/repositoriesread
Switch reviews on or offPATCH /api/orgs/{org}/repositories/{id}admin
Remove a repositoryDELETE /api/orgs/{org}/repositories/{id}admin
Add a public repositoryPOST /api/orgs/{org}/repositories/publicadmin
Upload a source archivePOST /api/orgs/{org}/repositories/archiveadmin
Connect GitLabPOST /api/orgs/{org}/connections/gitlabconsole only (owner)
Rotate a webhook secretPOST /api/orgs/{org}/connections/{id}/webhook-secretconsole only (owner)
Connect GitHub Enterprise ServerPOST /api/orgs/{org}/connections/github-enterpriseconsole only (owner)
Connect BitbucketPOST /api/orgs/{org}/connections/bitbucketconsole only (owner)
Connect Azure DevOpsPOST /api/orgs/{org}/connections/azure-devopsconsole only (owner)
List open pull requestsGET /api/orgs/{org}/repositories/{id}/pull-requestsread

#List connections

GET /api/orgs/{org}/connections

Returns the code-host accounts the organisation is connected to, as a plain list. Repositories added by address and uploaded archives have no connection to manage and are not represented here.

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/connections"

Answer (200, application/json)

The connections.

An array of Connection.

[
  {
    "id": "conn_d5a2f80e6b39",
    "orgId": "org_5b1e7a90c3d2",
    "provider": "github",
    "externalId": "48211937",
    "accountLogin": "acme",
    "createdAt": "2026-11-16T09:30:00.000Z",
    "baseUrl": "https://git.acme.example"
  }
]

#Get the GitHub install link

GET /api/orgs/{org}/connections/github/install

Returns the address on GitHub where the Nullgap GitHub App is installed on an account. Send a person's browser there. An installation serves the organisation only once it is linked to it.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/connections/github/install"

Answer (200, application/json)

FieldTypeAlways presentDescription
urlstringyesThe GitHub page that installs the app.
{
  "url": "https://github.com/apps/nullgap/installations/new?state=acme"
}

Errors specific to this call

StatusCodeWhen
400not_configuredThis server has no GitHub App set up.

#Begin verifying a GitHub installation

POST /api/orgs/{org}/connections/github/verify

Begins proving, through GitHub, that the signed-in person administers a GitHub App installation. It answers with a GitHub address to send the browser to and sets a short-lived cookie; when the person comes back from GitHub, the installation is linked to the organisation if GitHub confirms they administer it. The round trip must be finished within ten minutes, in the same browser. This is a console flow and cannot be completed with an API key.

Who may call it: A signed-in admin or owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
installationIdstringyesThe number of the installation, as GitHub shows it in the installation's address. Digits only, up to 20.

Answer (200, application/json)

FieldTypeAlways presentDescription
urlstringyesThe GitHub page to send the browser to.
{
  "url": "https://github.com/login/oauth/authorize?client_id=Iv1.0a1b2c3d4e5f6a7b&state=Zk3vQ9"
}

Errors specific to this call

StatusCodeWhen
400not_configuredThis server cannot ask GitHub who administers an installation.

#Link a GitHub installation

POST /api/orgs/{org}/connections/github/claim

Links a GitHub App installation to the organisation by its number and reads its repositories. Only an installation GitHub has told Nullgap about can be linked. Where the server can ask GitHub who administers an installation, a number alone is not accepted: the call succeeds only for a person who signed in with GitHub as the account the app is installed on (a login typed into the profile does not count); everyone else, API keys included, gets verification_required and uses the verify flow. Where the server cannot ask GitHub, the installation must be less than an hour old or belong to the GitHub account the caller signed in with. Calling it for an installation already linked to this organisation only reads its repositories again.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
installationIdstring or integeryesThe number of the installation, as GitHub shows it in the installation's address. Digits only.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"installationId":"48211937"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/connections/github/claim"

Answer (200, application/json)

A Connection object.

{
  "id": "conn_d5a2f80e6b39",
  "orgId": "org_5b1e7a90c3d2",
  "provider": "github",
  "externalId": "48211937",
  "accountLogin": "acme",
  "createdAt": "2026-11-16T09:30:00.000Z",
  "baseUrl": "https://git.acme.example"
}

Errors specific to this call

StatusCodeWhen
404unknown_installationNullgap has not heard of an installation with that number, or it is linked to another organisation; the answer does not say which. Install the GitHub App first.
403verification_requiredThe server can ask GitHub who administers the installation and the caller has not been confirmed as its administrator. Use the verify flow in the console.
403forbiddenThe installation was made more than an hour ago and does not belong to the GitHub account the caller signed in with. Reinstall the app and link it within the hour.

#Remove a connection

DELETE /api/orgs/{org}/connections/{id}

Disconnects a code-host account. Its repositories are removed from Nullgap and its stored credentials are deleted. Nothing is changed on the code host: uninstall the app or delete the webhook and access token there yourself. Findings, reviews and pentests already recorded are kept.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/connections/ID"

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundNo connection of this organisation has that id.

#Sync repositories

POST /api/orgs/{org}/repositories/sync

Reads the repository list of every connection again from its code host and returns all of the organisation's repositories as a plain list. Repositories that are new start with pull request reviews switched on; ones that are gone from the code host are removed; a repository's reviewEnabled choice is kept. Takes no body.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/sync"

Answer (200, application/json)

Every repository of the organisation after the sync.

An array of Repository.

[
  {
    "id": "repo_a41c09be77d3",
    "orgId": "org_5b1e7a90c3d2",
    "connectionId": "conn_d5a2f80e6b39",
    "provider": "github",
    "externalId": "731045882",
    "fullName": "acme/shop",
    "defaultBranch": "main",
    "private": true,
    "reviewEnabled": true,
    "createdAt": "2026-11-16T09:30:00.000Z"
  }
]

Errors specific to this call

StatusCodeWhen
400not_configuredA connection is to a code host this server is no longer set up for.
400connection_unreadableThe stored credentials of a connection could not be read. Connect that code host again.

#List repositories

GET /api/orgs/{org}/repositories

Returns every repository of the organisation as a plain list, sorted by fullName: those of connected code hosts, those added by address and uploaded archives. The list is not paged.

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/repositories"

Answer (200, application/json)

The repositories, by name.

An array of Repository.

[
  {
    "id": "repo_a41c09be77d3",
    "orgId": "org_5b1e7a90c3d2",
    "connectionId": "conn_d5a2f80e6b39",
    "provider": "github",
    "externalId": "731045882",
    "fullName": "acme/shop",
    "defaultBranch": "main",
    "private": true,
    "reviewEnabled": true,
    "createdAt": "2026-11-16T09:30:00.000Z"
  }
]

#Switch reviews on or off

PATCH /api/orgs/{org}/repositories/{id}

Switches pull request reviews on or off for one repository. This is the only thing about a repository that can be changed. A review asked for by hand is still done while reviews are off.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Request body (application/json)

FieldTypeRequiredDescription
reviewEnabledbooleanyesTrue to review this repository's pull requests, false to stop.

Example request

curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reviewEnabled":true}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/ID"

Answer (200, application/json)

A Repository object.

{
  "id": "repo_a41c09be77d3",
  "orgId": "org_5b1e7a90c3d2",
  "connectionId": "conn_d5a2f80e6b39",
  "provider": "github",
  "externalId": "731045882",
  "fullName": "acme/shop",
  "defaultBranch": "main",
  "private": true,
  "reviewEnabled": true,
  "createdAt": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
404not_foundNo repository of this organisation has that id.
400read_only_repositoryReviews were switched on for a repository added by address or uploaded as an archive. It has no pull requests to review.

#Remove a repository

DELETE /api/orgs/{org}/repositories/{id}

Removes a repository that was added by address or uploaded as an archive, together with its pentest schedules and, for an upload, the stored file. A repository of a connected code host cannot be removed here: change what the connection can see on the code host, or remove the connection. Findings and pentests already recorded are kept.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Example request

curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/ID"

Answer (200, application/json)

An empty object.

{}

Errors specific to this call

StatusCodeWhen
404not_foundNo repository of this organisation has that id.
400connected_repositoryThe repository comes from a connected code host.

#Add a public repository

POST /api/orgs/{org}/repositories/public

Adds a public repository by its address, without connecting a code host. The repository is read-only: it can be pentested, but there are no pull request reviews and no fix pull requests. Adding an address the organisation already has returns the existing repository. An organisation can add up to 50 repositories this way.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
urlstringyesThe address of the public repository. Up to 500 characters.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://github.com/acme/shop"}' \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/public"

Answer (200, application/json)

A Repository object.

{
  "id": "repo_a41c09be77d3",
  "orgId": "org_5b1e7a90c3d2",
  "connectionId": "conn_d5a2f80e6b39",
  "provider": "github",
  "externalId": "731045882",
  "fullName": "acme/shop",
  "defaultBranch": "main",
  "private": true,
  "reviewEnabled": true,
  "createdAt": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
400not_configuredAdding a repository by address is not available on this server.
400bad_repositoryThe address is not one of a repository that can be read: it is malformed, private, or does not exist. The message says which.
409too_manyThe organisation already has 50 repositories added by address.

#Upload a source archive

POST /api/orgs/{org}/repositories/archive

Uploads code that is not on a code host. The request body is the archive itself, not JSON: a .zip or a gzip-compressed tar (.tar.gz), up to 200 MB. The format is recognised from the file's contents, not from its name or Content-Type. The archive is unpacked once on arrival to check it, and refused with bad_archive when it is damaged, cut short, empty, or neither format; when a zip is password-protected, split into parts, or uses a compression method other than deflate; or when it unpacks to more than 1 GB in all, holds a single file over 256 MB, or has more than 100,000 entries. Only regular files and folders are kept: symbolic links, device files, a .git folder, absolute paths and paths that point outside the archive are left out. It answers with a read-only repository named upload/{name} whose id is the repoId to pentest and whose branch is always upload. An organisation can keep up to 20 uploaded archives.

Who may call it: An API key with the admin scope.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Query parameters

NameTypeRequiredDescription
namestringnoHow the upload is shown. Up to 80 characters: letters, digits, spaces, dots, dashes and underscores, starting with a letter or digit. A trailing .zip, .tar.gz or .tgz is dropped and spaces become dashes. Default upload.

Request body (application/octet-stream)

The bytes of the .zip or .tar.gz file.

Example request

curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @code.zip \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/archive"

Answer (200, application/json)

A Repository object.

{
  "id": "repo_a41c09be77d3",
  "orgId": "org_5b1e7a90c3d2",
  "connectionId": "conn_d5a2f80e6b39",
  "provider": "github",
  "externalId": "731045882",
  "fullName": "acme/shop",
  "defaultBranch": "main",
  "private": true,
  "reviewEnabled": true,
  "createdAt": "2026-11-16T09:30:00.000Z"
}

Errors specific to this call

StatusCodeWhen
400not_configuredUploading an archive is not available on this server.
400bad_requestname contains characters that are not allowed or is too long, or the upload is empty.
409too_manyThe organisation already keeps 20 uploaded archives. Remove one first.
413too_largeThe archive is larger than 200 MB.
400bad_archiveThe archive could not be unpacked or is over a limit. The message says why.

#Connect GitLab

POST /api/orgs/{org}/connections/gitlab

Connects a GitLab group with an access token you create there. The token is tried against GitLab before anything is stored; the top-level group of the path is what gets connected, and its repositories are read. The answer carries a webhook address and a secret to register on the group (merge request, comment and project events). The secret is shown this once. Connecting the same group again replaces the stored token and makes a new webhook secret, which must then be updated in GitLab.

Who may call it: A signed-in owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
groupPathstringyesThe path of the group (or user namespace), such as acme or acme/platform. 1 to 255 characters.
tokenstringyesA group access token or service-account token with the api scope and at least the Developer role on the group. 16 to 400 characters, no spaces. Stored encrypted and never returned.
baseUrlstringnoThe address of a GitLab you run yourself: https, publicly reachable, no credentials, query or fragment. Up to 300 characters. Default https://gitlab.com.

Answer (200, application/json)

A ConnectionWithWebhook object.

{
  "connection": {
    "id": "conn_d5a2f80e6b39",
    "orgId": "org_5b1e7a90c3d2",
    "provider": "github",
    "externalId": "48211937",
    "accountLogin": "acme",
    "createdAt": "2026-11-16T09:30:00.000Z",
    "baseUrl": "https://git.acme.example"
  },
  "webhookUrl": "https://app.nullgap.dev/webhooks/gitlab/conn_d5a2f80e6b39",
  "webhookSecret": "k3Vq9ZxT1mB7pL0sHd2NwY6rEa4UjC8f"
}

Errors specific to this call

StatusCodeWhen
403step_up_requiredYour account has a second factor and it was last checked more than 15 minutes ago on this session. Confirm with your authenticator code and try again.
400not_configuredThis server is not set up for GitLab connections.
400private_addressbaseUrl points at a private or loopback address.
400gitlab_rejectedGitLab did not accept the token for that group, or could not be reached.

#Rotate a webhook secret

POST /api/orgs/{org}/connections/{id}/webhook-secret

Makes a new webhook secret for a GitLab, Bitbucket, Azure DevOps or GitHub Enterprise Server connection and returns it once. The old secret stops working at once, so events from the code host are refused until the new secret is entered there. The webhook address does not change. Takes no body.

Who may call it: A signed-in owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe id.

Answer (200, application/json)

FieldTypeAlways presentDescription
webhookUrlstringyesThe webhook address of this connection. Unchanged by the rotation.
webhookSecretstringyesThe new secret to enter on the code host. Shown this once only.
{
  "webhookUrl": "https://app.nullgap.dev/webhooks/gitlab/conn_d5a2f80e6b39",
  "webhookSecret": "k3Vq9ZxT1mB7pL0sHd2NwY6rEa4UjC8f"
}

Errors specific to this call

StatusCodeWhen
403step_up_requiredYour account has a second factor and it was last checked more than 15 minutes ago on this session. Confirm with your authenticator code and try again.
404not_foundNo connection of this organisation has that id.
400bad_requestThe connection has no webhook secret of its own: it is a GitHub App installation.
400connection_unreadableThe stored credentials of the connection could not be read. Connect the code host again.

#Connect GitHub Enterprise Server

POST /api/orgs/{org}/connections/github-enterprise

Connects an organisation on a GitHub Enterprise Server you run, through a GitHub App you create and install there. The App's id and private key are tried against the server, and the App must already be installed on the organisation named, before anything is stored. The answer carries a webhook address and a secret to enter on the App. The secret is shown this once. Connecting the same organisation again replaces the stored key and makes a new webhook secret.

Who may call it: A signed-in owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
baseUrlstringyesThe address of the server: https, publicly reachable, not github.com, no credentials, query or fragment. 8 to 300 characters.
appIdstringyesThe App ID shown on the GitHub App's page, as a string of digits. Up to 20.
appSlugstringyesThe name in the GitHub App's address: letters, digits and dashes. Up to 100 characters.
organizationstringyesThe organisation or user the App is installed on. Up to 100 characters.
privateKeystringyesThe whole .pem file GitHub gave you for the App, 200 to 10,000 characters. Stored encrypted and never returned.

Answer (200, application/json)

A ConnectionWithWebhook object.

{
  "connection": {
    "id": "conn_d5a2f80e6b39",
    "orgId": "org_5b1e7a90c3d2",
    "provider": "github",
    "externalId": "48211937",
    "accountLogin": "acme",
    "createdAt": "2026-11-16T09:30:00.000Z",
    "baseUrl": "https://git.acme.example"
  },
  "webhookUrl": "https://app.nullgap.dev/webhooks/gitlab/conn_d5a2f80e6b39",
  "webhookSecret": "k3Vq9ZxT1mB7pL0sHd2NwY6rEa4UjC8f"
}

Errors specific to this call

StatusCodeWhen
403step_up_requiredYour account has a second factor and it was last checked more than 15 minutes ago on this session. Confirm with your authenticator code and try again.
400not_configuredThis server is not set up for GitHub Enterprise Server connections.
400private_addressbaseUrl points at a private or loopback address.
400code_host_rejectedThe server did not accept the App ID and private key, or could not be reached.
400not_installedThe key works, but the App is not installed on the organisation named.
409already_connectedThat account is already connected to another organisation.

#Connect Bitbucket

POST /api/orgs/{org}/connections/bitbucket

Connects a Bitbucket Cloud workspace with a workspace access token. The token is tried against Bitbucket before anything is stored, and the workspace's repositories are read. The answer carries a webhook address and a secret to register on the workspace. The secret is shown this once. Connecting the same workspace again replaces the stored token and makes a new webhook secret.

Who may call it: A signed-in owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
workspacestringyesThe workspace ID: letters, digits, _, . and -. Up to 100 characters.
tokenstringyesA workspace access token with read and write on repositories and pull requests. 16 to 600 characters, no spaces. Stored encrypted and never returned.

Answer (200, application/json)

A ConnectionWithWebhook object.

{
  "connection": {
    "id": "conn_d5a2f80e6b39",
    "orgId": "org_5b1e7a90c3d2",
    "provider": "github",
    "externalId": "48211937",
    "accountLogin": "acme",
    "createdAt": "2026-11-16T09:30:00.000Z",
    "baseUrl": "https://git.acme.example"
  },
  "webhookUrl": "https://app.nullgap.dev/webhooks/gitlab/conn_d5a2f80e6b39",
  "webhookSecret": "k3Vq9ZxT1mB7pL0sHd2NwY6rEa4UjC8f"
}

Errors specific to this call

StatusCodeWhen
403step_up_requiredYour account has a second factor and it was last checked more than 15 minutes ago on this session. Confirm with your authenticator code and try again.
400not_configuredThis server is not set up for Bitbucket connections.
400code_host_rejectedBitbucket did not accept the token for that workspace, or could not be reached.
409already_connectedThat account is already connected to another organisation.

#Connect Azure DevOps

POST /api/orgs/{org}/connections/azure-devops

Connects an Azure DevOps organisation with an access token. The token is tried against Azure DevOps before anything is stored, and the organisation's repositories are read. The answer carries a webhook address and a secret to register as service hooks. The secret is shown this once. Connecting the same organisation again replaces the stored token and makes a new webhook secret.

Who may call it: A signed-in owner in the console. No API key may call it.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
organizationstringyesThe Azure DevOps organisation name: letters, digits and dashes, 1 to 50 characters, not starting or ending with a dash. Note the spelling of the field name.
tokenstringyesAn access token with Code (read and write), Code (status) and Pull request threads (read and write). 16 to 600 characters, no spaces. Stored encrypted and never returned.

Answer (200, application/json)

A ConnectionWithWebhook object.

{
  "connection": {
    "id": "conn_d5a2f80e6b39",
    "orgId": "org_5b1e7a90c3d2",
    "provider": "github",
    "externalId": "48211937",
    "accountLogin": "acme",
    "createdAt": "2026-11-16T09:30:00.000Z",
    "baseUrl": "https://git.acme.example"
  },
  "webhookUrl": "https://app.nullgap.dev/webhooks/gitlab/conn_d5a2f80e6b39",
  "webhookSecret": "k3Vq9ZxT1mB7pL0sHd2NwY6rEa4UjC8f"
}

Errors specific to this call

StatusCodeWhen
403step_up_requiredYour account has a second factor and it was last checked more than 15 minutes ago on this session. Confirm with your authenticator code and try again.
400not_configuredThis server is not set up for Azure DevOps connections.
400code_host_rejectedAzure DevOps did not accept the token for that organisation, or could not be reached.
409already_connectedThat account is already connected to another organisation.

#List open pull requests

GET /api/orgs/{org}/repositories/{id}/pull-requests

Returns up to 30 open pull requests of one repository, read from the code host at the time of the call, so that one can be picked for a review instead of typing its number. When the host cannot list them the answer is supported: false with an empty list, not an error.

Who may call it: An API key with the read scope or higher.

Path parameters

NameTypeRequiredDescription
orgstringyesThe organisation slug.
idstringyesThe repository id.

Example request

curl -s -H "Authorization: Bearer $NULLGAP_API_KEY" \
  "$NULLGAP_URL/api/orgs/$NULLGAP_ORG/repositories/ID/pull-requests"

Answer (200, application/json)

A OpenPullRequests object.

{
  "supported": true,
  "items": [
    {
      "number": 128,
      "title": "Add partner webhooks",
      "author": "dana-okafor",
      "draft": false,
      "url": "https://github.com/acme/shop/pull/128"
    }
  ]
}

Errors specific to this call

StatusCodeWhen
404not_foundNo repository of this organisation has that id.
502code_host_unavailableThe code host did not answer or refused the request. Try again, or use the pull request number directly.

#Objects

The objects the operations above take and return.

#Connection

One account on a code host that Nullgap is connected to. Stored credentials are never returned.

FieldTypeAlways presentDescription
idstringyesThe connection id.
orgIdstringyesThe organisation it belongs to.
providerstringyesThe code host. One of: github, github-enterprise, gitlab, bitbucket, azure-devops.
externalIdstringyesThe code host's own id for the connected account: for GitHub, the installation id.
accountLoginstringyesThe connected organisation, group or workspace on the code host.
createdAtstringyesWhen it was connected.
baseUrlstringnoThe address of a code host you run yourself (GitLab self-managed, GitHub Enterprise Server). Absent for the hosted services.

#Repository

A repository Nullgap can read.

FieldTypeAlways presentDescription
idstringyesThe repository id. Use it as repoId elsewhere.
orgIdstringyesThe organisation it belongs to.
connectionIdstringyesThe connection it came through.
providerstringyesWhere the code is. public (added by its address) and archive (uploaded) are read-only: pentests work, reviews and fix pull requests do not.
externalIdstringyesThe code host's own id for the repository. For public it is the address, for archive the upload id.
fullNamestringyesThe repository as owner/name. An uploaded archive is upload/{name}.
defaultBranchstringyesThe default branch. For an uploaded archive it is always upload.
privatebooleanyesTrue when the repository is not public on its code host.
reviewEnabledbooleanyesTrue when pull requests in this repository are reviewed.
createdAtstringyesWhen Nullgap first saw the repository.

#ConnectionWithWebhook

A new or updated connection, with what to register on the code host.

FieldTypeAlways presentDescription
connectionConnectionyes
webhookUrlstringyesRegister this address as a webhook on the code host, so Nullgap hears about pull requests and comments.
webhookSecretstringyesThe secret to give the code host for that webhook. Shown this once only.

#OpenPullRequests

The open pull requests of one repository.

FieldTypeAlways presentDescription
supportedbooleanyesFalse when the code host cannot list pull requests (a repository added by address or uploaded, or a host without that ability): ask for the number instead.
itemsarray of objectyesUp to 30 open pull requests.
items[].numberintegeryesThe pull request number.
items[].titlestringyesIts title.
items[].authorstringyesWho opened it, as the code host names them.
items[].draftbooleanyesWhether it is a draft.
items[].urlstringyesIts address on the code host.

Nullgap documentation