API reference
Integrations
Slack notifications, Jira and Linear.
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 integrations | GET /api/orgs/{org}/integrations | read |
| Connect an integration | PUT /api/orgs/{org}/integrations/{kind} | admin |
| Disconnect an integration | DELETE /api/orgs/{org}/integrations/{kind} | admin |
| Test an integration | POST /api/orgs/{org}/integrations/{kind}/test | admin |
| Switch Jira status sync | PATCH /api/orgs/{org}/integrations/jira | admin |
| Replace the Jira webhook secret | POST /api/orgs/{org}/integrations/jira/webhook-secret | admin |
#List integrations
GET /api/orgs/{org}/integrations
Answers one entry for each of slack, jira and linear, in that order, connected or not. Credentials are never returned.
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/integrations"
Answer (200, application/json)
Always three entries: Slack, Jira and Linear.
An array of Integration.
[
{
"kind": "jira",
"connected": true,
"label": "SHOP",
"needsReconnect": false,
"statusSync": {
"enabled": true,
"webhookUrl": "https://app.nullgap.example/webhooks/jira/jhk_Zq8rT2nLx5vBc7Kd"
},
"settings": {
"baseUrl": "https://acme.atlassian.net",
"email": "security-bot@acme.example",
"projectKey": "SEC"
}
}
]
#Connect an integration
PUT /api/orgs/{org}/integrations/{kind}
Stores the credentials for a service, replacing any that were there. For Jira and Linear the credentials are checked with the service before anything is saved, so a wrong token or project is reported here and not on first use. Connecting Jira also sets up the address Jira reports status changes to: the first time, the answer carries its secret in webhookSecret, once. Saving new Jira credentials later keeps the existing secret, and the answer then has no webhookSecret.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
kind | string | yes | Which service: slack, jira or linear. |
Request body (application/json)
| Field | Type | Required | Description |
|---|---|---|---|
config | object or object or object | yes | The credentials for the service. Which fields are needed depends on kind. |
statusSync | boolean | no | Jira only: keep the state of a finding and the status of its issue in step. On for a new connection when left out; an existing connection keeps its value. |
Example request
curl -s -X PUT -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"config":{"baseUrl":"https://acme.atlassian.net","email":"security-bot@acme.example","apiToken":"your-jira-api-token","projectKey":"SHOP"},"statusSync":true}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/slack"
Answer (200, application/json)
A IntegrationWithSecret object.
{
"kind": "jira",
"connected": true,
"label": "SHOP",
"needsReconnect": false,
"statusSync": {
"enabled": true,
"webhookUrl": "https://app.nullgap.example/webhooks/jira/jhk_Zq8rT2nLx5vBc7Kd"
},
"settings": {
"baseUrl": "https://acme.atlassian.net",
"email": "security-bot@acme.example",
"projectKey": "SEC"
},
"webhookSecret": "pV3kQ9xT7nB2mL5wZr8YcH4sJdF6aGe1UoKi0PqRtXv"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | kind is not one of the three, config is missing, a required field of config is missing, the Slack address is not an incoming-webhook address, or the Jira address is not a public https address. |
| 400 | tracker_rejected | Jira or Linear refused the credentials or could not find the project or team. The message says which. |
| 400 | tracker_unreachable | Jira or Linear could not be reached to check the credentials. Try again. |
#Disconnect an integration
DELETE /api/orgs/{org}/integrations/{kind}
Deletes the stored credentials for a service. For Jira, the address it reported status changes to stops working. Disconnecting a service that was not connected also answers 200.
Who may call it: An API key with the admin scope.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
kind | string | yes | Which service: slack, jira or linear. |
Example request
curl -s -X DELETE -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/slack"
Answer (200, application/json)
An empty object.
{}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | kind is not one of the three. |
#Test an integration
POST /api/orgs/{org}/integrations/{kind}/test
Asks Jira or Linear, with the saved credentials, the same read-only questions that are asked before saving: whether the credentials are accepted, and whether the project or team can be seen. Nothing is created in the tracker and nothing is changed in Nullgap. A refusal by the tracker is not an error of this request: the answer is 200 with ok false and the reason in message. 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. |
kind | string | yes | Which tracker: jira or linear. |
Example request
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/jira/test"
Answer (200, application/json)
The result of the check.
| Field | Type | Always present | Description |
|---|---|---|---|
ok | boolean | yes | True when the tracker accepted the saved credentials and the project or team can be seen. |
message | string | yes | What the tracker said, in words. |
checkedAt | string | yes | When the check was made. |
{
"ok": true,
"message": "Jira accepted the saved credentials and the project SEC can be seen.",
"checkedAt": "2026-11-16T09:30:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | bad_request | kind is not jira or linear. |
| 409 | not_connected | The tracker is not connected. |
#Switch Jira status sync
PATCH /api/orgs/{org}/integrations/jira
Switches keeping findings and their Jira issues in step on or off. When off, issues are still filed, but later changes on either side are not carried across and events from Jira are ignored.
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 |
|---|---|---|---|
statusSync | boolean | yes | True to keep findings and issues in step, false to stop. |
Example request
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"statusSync":true}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/integrations/jira"
Answer (200, application/json)
A Integration object.
{
"kind": "jira",
"connected": true,
"label": "SHOP",
"needsReconnect": false,
"statusSync": {
"enabled": true,
"webhookUrl": "https://app.nullgap.example/webhooks/jira/jhk_Zq8rT2nLx5vBc7Kd"
},
"settings": {
"baseUrl": "https://acme.atlassian.net",
"email": "security-bot@acme.example",
"projectKey": "SEC"
}
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | not_connected | Jira is not connected. |
| 400 | bad_request | statusSync is missing or not true or false. |
#Replace the Jira webhook secret
POST /api/orgs/{org}/integrations/jira/webhook-secret
Generates a new secret for the address Jira reports status changes to, and answers it once. The address itself stays the same, so only the secret has to be changed in Jira. Events signed with the old secret are refused from then on.
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/integrations/jira/webhook-secret"
Answer (200, application/json)
A IntegrationWithSecret object.
{
"kind": "jira",
"connected": true,
"label": "SHOP",
"needsReconnect": false,
"statusSync": {
"enabled": true,
"webhookUrl": "https://app.nullgap.example/webhooks/jira/jhk_Zq8rT2nLx5vBc7Kd"
},
"settings": {
"baseUrl": "https://acme.atlassian.net",
"email": "security-bot@acme.example",
"projectKey": "SEC"
},
"webhookSecret": "pV3kQ9xT7nB2mL5wZr8YcH4sJdF6aGe1UoKi0PqRtXv"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 400 | not_connected | Jira is not connected. |
#Objects
The objects the operations above take and return.
#Integration
One of the services Nullgap can send findings to. Credentials are never returned.
| Field | Type | Always present | Description |
|---|---|---|---|
kind | string | yes | Which service this is. One of: slack, jira, linear. |
connected | boolean | yes | True when credentials are stored for it. |
label | string or null | yes | A name for what it is connected to, safe to display: the Slack channel, the Jira project key or the Linear team key. Null when not connected or not known. |
needsReconnect | boolean | yes | True when stored credentials exist but can no longer be opened. Connect it again. |
statusSync | object | no | Jira only, and only when connected: keeping findings and their issues in step. |
statusSync.enabled | boolean | yes | True when the state of a finding and the status of its issue are kept in step, both ways. When false, issues are filed and then left alone, and events from Jira are ignored. |
statusSync.webhookUrl | string or null | yes | The address to register as a webhook in Jira. Null until a webhook secret has been generated. |
settings | object | no | Only when connected: the saved values that are not secret, so that a replacement can start from them. Jira: baseUrl, email and projectKey; Linear: teamId; Slack: channel when one was given. Tokens, keys and webhook addresses are never included. |
#IntegrationWithSecret
An integration as answered by the requests that can generate the secret Jira signs its events with.
| Field | Type | Always present | Description |
|---|---|---|---|
kind | string | yes | Which service this is. One of: slack, jira, linear. |
connected | boolean | yes | True when credentials are stored for it. |
label | string or null | yes | A name for what it is connected to, safe to display: the Slack channel, the Jira project key or the Linear team key. Null when not connected or not known. |
needsReconnect | boolean | yes | True when stored credentials exist but can no longer be opened. Connect it again. |
statusSync | object | no | Jira only, and only when connected: keeping findings and their issues in step. |
statusSync.enabled | boolean | yes | True when the state of a finding and the status of its issue are kept in step, both ways. When false, issues are filed and then left alone, and events from Jira are ignored. |
statusSync.webhookUrl | string or null | yes | The address to register as a webhook in Jira. Null until a webhook secret has been generated. |
settings | object | no | Only when connected: the saved values that are not secret, so that a replacement can start from them. Jira: baseUrl, email and projectKey; Linear: teamId; Slack: channel when one was given. Tokens, keys and webhook addresses are never included. |
webhookSecret | string | no | Jira only: the secret to enter in Jira's webhook settings. Present only when this request generated a new one. Store it now: it cannot be read again. |
Nullgap documentation