Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
List integrationsGET /api/orgs/{org}/integrationsread
Connect an integrationPUT /api/orgs/{org}/integrations/{kind}admin
Disconnect an integrationDELETE /api/orgs/{org}/integrations/{kind}admin
Test an integrationPOST /api/orgs/{org}/integrations/{kind}/testadmin
Switch Jira status syncPATCH /api/orgs/{org}/integrations/jiraadmin
Replace the Jira webhook secretPOST /api/orgs/{org}/integrations/jira/webhook-secretadmin

#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

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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
kindstringyesWhich service: slack, jira or linear.

Request body (application/json)

FieldTypeRequiredDescription
configobject or object or objectyesThe credentials for the service. Which fields are needed depends on kind.
statusSyncbooleannoJira 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

StatusCodeWhen
400bad_requestkind 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.
400tracker_rejectedJira or Linear refused the credentials or could not find the project or team. The message says which.
400tracker_unreachableJira 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
kindstringyesWhich 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

StatusCodeWhen
400bad_requestkind 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
kindstringyesWhich 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.

FieldTypeAlways presentDescription
okbooleanyesTrue when the tracker accepted the saved credentials and the project or team can be seen.
messagestringyesWhat the tracker said, in words.
checkedAtstringyesWhen 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

StatusCodeWhen
400bad_requestkind is not jira or linear.
409not_connectedThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

FieldTypeRequiredDescription
statusSyncbooleanyesTrue 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

StatusCodeWhen
400not_connectedJira is not connected.
400bad_requeststatusSync 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

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

StatusCodeWhen
400not_connectedJira 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.

FieldTypeAlways presentDescription
kindstringyesWhich service this is. One of: slack, jira, linear.
connectedbooleanyesTrue when credentials are stored for it.
labelstring or nullyesA 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.
needsReconnectbooleanyesTrue when stored credentials exist but can no longer be opened. Connect it again.
statusSyncobjectnoJira only, and only when connected: keeping findings and their issues in step.
statusSync.enabledbooleanyesTrue 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.webhookUrlstring or nullyesThe address to register as a webhook in Jira. Null until a webhook secret has been generated.
settingsobjectnoOnly 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.

FieldTypeAlways presentDescription
kindstringyesWhich service this is. One of: slack, jira, linear.
connectedbooleanyesTrue when credentials are stored for it.
labelstring or nullyesA 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.
needsReconnectbooleanyesTrue when stored credentials exist but can no longer be opened. Connect it again.
statusSyncobjectnoJira only, and only when connected: keeping findings and their issues in step.
statusSync.enabledbooleanyesTrue 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.webhookUrlstring or nullyesThe address to register as a webhook in Jira. Null until a webhook secret has been generated.
settingsobjectnoOnly 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.
webhookSecretstringnoJira 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