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.
| Operation | Method and path | Who may call it |
|---|---|---|
| List connections | GET /api/orgs/{org}/connections | read |
| Get the GitHub install link | GET /api/orgs/{org}/connections/github/install | admin |
| Begin verifying a GitHub installation | POST /api/orgs/{org}/connections/github/verify | console only (admin) |
| Link a GitHub installation | POST /api/orgs/{org}/connections/github/claim | admin |
| Remove a connection | DELETE /api/orgs/{org}/connections/{id} | admin |
| Sync repositories | POST /api/orgs/{org}/repositories/sync | admin |
| List repositories | GET /api/orgs/{org}/repositories | read |
| Switch reviews on or off | PATCH /api/orgs/{org}/repositories/{id} | admin |
| Remove a repository | DELETE /api/orgs/{org}/repositories/{id} | admin |
| Add a public repository | POST /api/orgs/{org}/repositories/public | admin |
| Upload a source archive | POST /api/orgs/{org}/repositories/archive | admin |
| Connect GitLab | POST /api/orgs/{org}/connections/gitlab | console only (owner) |
| Rotate a webhook secret | POST /api/orgs/{org}/connections/{id}/webhook-secret | console only (owner) |
| Connect GitHub Enterprise Server | POST /api/orgs/{org}/connections/github-enterprise | console only (owner) |
| Connect Bitbucket | POST /api/orgs/{org}/connections/bitbucket | console only (owner) |
| Connect Azure DevOps | POST /api/orgs/{org}/connections/azure-devops | console only (owner) |
| List open pull requests | GET /api/orgs/{org}/repositories/{id}/pull-requests | read |
#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
| 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/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
| 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/connections/github/install"
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
url | string | yes | The GitHub page that installs the app. |
{
"url": "https://github.com/apps/nullgap/installations/new?state=acme"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | not_configured | This 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
installationId | string | yes | The number of the installation, as GitHub shows it in the installation's address. Digits only, up to 20. |
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
url | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | not_configured | This 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
installationId | string or integer | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | unknown_installation | Nullgap 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. |
| 403 | verification_required | The 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. |
| 403 | forbidden | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | not_configured | A connection is to a code host this server is no longer set up for. |
| 400 | connection_unreadable | The 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
| 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/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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
reviewEnabled | boolean | yes | True 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No repository of this organisation has that id. |
| 400 | read_only_repository | Reviews 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No repository of this organisation has that id. |
| 400 | connected_repository | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 400 | not_configured | Adding a repository by address is not available on this server. |
| 400 | bad_repository | The address is not one of a repository that can be read: it is malformed, private, or does not exist. The message says which. |
| 409 | too_many | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | no | How 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
| Status | Code | When |
|---|---|---|
| 400 | not_configured | Uploading an archive is not available on this server. |
| 400 | bad_request | name contains characters that are not allowed or is too long, or the upload is empty. |
| 409 | too_many | The organisation already keeps 20 uploaded archives. Remove one first. |
| 413 | too_large | The archive is larger than 200 MB. |
| 400 | bad_archive | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
groupPath | string | yes | The path of the group (or user namespace), such as acme or acme/platform. 1 to 255 characters. |
token | string | yes | A 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. |
baseUrl | string | no | The 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
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your 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. |
| 400 | not_configured | This server is not set up for GitLab connections. |
| 400 | private_address | baseUrl points at a private or loopback address. |
| 400 | gitlab_rejected | GitLab 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The id. |
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
webhookUrl | string | yes | The webhook address of this connection. Unchanged by the rotation. |
webhookSecret | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your 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. |
| 404 | not_found | No connection of this organisation has that id. |
| 400 | bad_request | The connection has no webhook secret of its own: it is a GitHub App installation. |
| 400 | connection_unreadable | The 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
baseUrl | string | yes | The address of the server: https, publicly reachable, not github.com, no credentials, query or fragment. 8 to 300 characters. |
appId | string | yes | The App ID shown on the GitHub App's page, as a string of digits. Up to 20. |
appSlug | string | yes | The name in the GitHub App's address: letters, digits and dashes. Up to 100 characters. |
organization | string | yes | The organisation or user the App is installed on. Up to 100 characters. |
privateKey | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your 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. |
| 400 | not_configured | This server is not set up for GitHub Enterprise Server connections. |
| 400 | private_address | baseUrl points at a private or loopback address. |
| 400 | code_host_rejected | The server did not accept the App ID and private key, or could not be reached. |
| 400 | not_installed | The key works, but the App is not installed on the organisation named. |
| 409 | already_connected | That 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
workspace | string | yes | The workspace ID: letters, digits, _, . and -. Up to 100 characters. |
token | string | yes | A 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
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your 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. |
| 400 | not_configured | This server is not set up for Bitbucket connections. |
| 400 | code_host_rejected | Bitbucket did not accept the token for that workspace, or could not be reached. |
| 409 | already_connected | That 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
organization | string | yes | The 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. |
token | string | yes | An 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
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your 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. |
| 400 | not_configured | This server is not set up for Azure DevOps connections. |
| 400 | code_host_rejected | Azure DevOps did not accept the token for that organisation, or could not be reached. |
| 409 | already_connected | That 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
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
id | string | yes | The 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
| Status | Code | When |
|---|---|---|
| 404 | not_found | No repository of this organisation has that id. |
| 502 | code_host_unavailable | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The connection id. |
orgId | string | yes | The organisation it belongs to. |
provider | string | yes | The code host. One of: github, github-enterprise, gitlab, bitbucket, azure-devops. |
externalId | string | yes | The code host's own id for the connected account: for GitHub, the installation id. |
accountLogin | string | yes | The connected organisation, group or workspace on the code host. |
createdAt | string | yes | When it was connected. |
baseUrl | string | no | The 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.
| Field | Type | Always present | Description |
|---|---|---|---|
id | string | yes | The repository id. Use it as repoId elsewhere. |
orgId | string | yes | The organisation it belongs to. |
connectionId | string | yes | The connection it came through. |
provider | string | yes | Where the code is. public (added by its address) and archive (uploaded) are read-only: pentests work, reviews and fix pull requests do not. |
externalId | string | yes | The code host's own id for the repository. For public it is the address, for archive the upload id. |
fullName | string | yes | The repository as owner/name. An uploaded archive is upload/{name}. |
defaultBranch | string | yes | The default branch. For an uploaded archive it is always upload. |
private | boolean | yes | True when the repository is not public on its code host. |
reviewEnabled | boolean | yes | True when pull requests in this repository are reviewed. |
createdAt | string | yes | When Nullgap first saw the repository. |
#ConnectionWithWebhook
A new or updated connection, with what to register on the code host.
| Field | Type | Always present | Description |
|---|---|---|---|
connection | Connection | yes | |
webhookUrl | string | yes | Register this address as a webhook on the code host, so Nullgap hears about pull requests and comments. |
webhookSecret | string | yes | The secret to give the code host for that webhook. Shown this once only. |
#OpenPullRequests
The open pull requests of one repository.
| Field | Type | Always present | Description |
|---|---|---|---|
supported | boolean | yes | False 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. |
items | array of object | yes | Up to 30 open pull requests. |
items[].number | integer | yes | The pull request number. |
items[].title | string | yes | Its title. |
items[].author | string | yes | Who opened it, as the code host names them. |
items[].draft | boolean | yes | Whether it is a draft. |
items[].url | string | yes | Its address on the code host. |
Nullgap documentation