API reference
Slack assistant
Set up the Slack assistant and link Slack users to Nullgap accounts.
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 |
|---|---|---|
| Get the Slack assistant | GET /api/orgs/{org}/slack-assistant | read |
| Start the Slack set-up | POST /api/orgs/{org}/slack-assistant | console only (owner) |
| Remove the Slack assistant | DELETE /api/orgs/{org}/slack-assistant | console only (owner) |
| Save the Slack signing secret | PUT /api/orgs/{org}/slack-assistant/signing-secret | console only (owner) |
| Save the Slack bot token | PUT /api/orgs/{org}/slack-assistant/bot-token | console only (owner) |
| Remove the Slack bot token | DELETE /api/orgs/{org}/slack-assistant/bot-token | console only (owner) |
| Look up a Slack link request | GET /api/orgs/{org}/slack-assistant/link/{token} | console only |
| Confirm a Slack link | POST /api/orgs/{org}/slack-assistant/link/{token} | console only |
#Get the Slack assistant
GET /api/orgs/{org}/slack-assistant
Answers whether the Slack assistant is set up and connected, and how many people have linked their Slack user. The request addresses and the app manifest are included only for an owner signed in to the console; an API key never receives them.
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/slack-assistant"
Answer (200, application/json)
A SlackAssistant object.
{
"created": true,
"connected": true,
"connectedAt": "2026-10-12T10:00:00.000Z",
"rotatedAt": "2026-11-02T10:00:00.000Z",
"linkedUsers": 4,
"commandUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/command",
"interactiveUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/interactive",
"manifest": "{\n \"display_information\": { \"name\": \"Nullgap\" }\n}",
"eventsUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/events",
"hasBotToken": true,
"eventsSeenAt": "2026-11-18T09:12:00.000Z",
"agentAvailable": true
}
#Start the Slack set-up
POST /api/orgs/{org}/slack-assistant
Creates the organisation's Slack assistant, which fixes the addresses Slack will send requests to, and answers them with the manifest to create the Slack app from. Calling it again when the assistant exists changes nothing and answers the current state. Requests from Slack are accepted only after the signing secret has been saved.
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. |
Answer (200, application/json)
A SlackAssistant object.
{
"created": true,
"connected": true,
"connectedAt": "2026-10-12T10:00:00.000Z",
"rotatedAt": "2026-11-02T10:00:00.000Z",
"linkedUsers": 4,
"commandUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/command",
"interactiveUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/interactive",
"manifest": "{\n \"display_information\": { \"name\": \"Nullgap\" }\n}",
"eventsUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/events",
"hasBotToken": true,
"eventsSeenAt": "2026-11-18T09:12:00.000Z",
"agentAvailable": true
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Remove the Slack assistant
DELETE /api/orgs/{org}/slack-assistant
Deletes the Slack connection and every Slack identity linked through it. The old request addresses stop working; setting the assistant up again gives new ones. The answer is the state afterwards, with created false.
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. |
Answer (200, application/json)
A SlackAssistant object.
{
"created": true,
"connected": true,
"connectedAt": "2026-10-12T10:00:00.000Z",
"rotatedAt": "2026-11-02T10:00:00.000Z",
"linkedUsers": 4,
"commandUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/command",
"interactiveUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/interactive",
"manifest": "{\n \"display_information\": { \"name\": \"Nullgap\" }\n}",
"eventsUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/events",
"hasBotToken": true,
"eventsSeenAt": "2026-11-18T09:12:00.000Z",
"agentAvailable": true
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | The Slack assistant is not set up for this organisation. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Save the Slack signing secret
PUT /api/orgs/{org}/slack-assistant/signing-secret
Stores the signing secret of the Slack app, or replaces it after it was regenerated in Slack. The secret is stored encrypted and never returned.
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 |
|---|---|---|---|
signingSecret | string | yes | The signing secret from the Slack app's Basic Information page, under App Credentials. 16 to 128 letters and digits. |
Answer (200, application/json)
A SlackAssistant object.
{
"created": true,
"connected": true,
"connectedAt": "2026-10-12T10:00:00.000Z",
"rotatedAt": "2026-11-02T10:00:00.000Z",
"linkedUsers": 4,
"commandUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/command",
"interactiveUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/interactive",
"manifest": "{\n \"display_information\": { \"name\": \"Nullgap\" }\n}",
"eventsUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/events",
"hasBotToken": true,
"eventsSeenAt": "2026-11-18T09:12:00.000Z",
"agentAvailable": true
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | The Slack set-up has not been started for this organisation. |
| 400 | bad_request | signingSecret is missing, too short or long, or has characters other than letters and digits. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Save the Slack bot token
PUT /api/orgs/{org}/slack-assistant/bot-token
Stores the bot token of the Slack app, or replaces it, so the assistant answers mentions and direct messages with Nullgap AI and posts updates about runs started from Slack. Slack is asked which workspace the token belongs to; events are then accepted from that workspace only. The token is stored encrypted and never returned: answers say only hasBotToken.
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 |
|---|---|---|---|
botToken | string | yes | The Bot User OAuth Token from the Slack app's OAuth & Permissions page. It starts with xoxb-. |
Answer (200, application/json)
A SlackAssistant object.
{
"created": true,
"connected": true,
"connectedAt": "2026-10-12T10:00:00.000Z",
"rotatedAt": "2026-11-02T10:00:00.000Z",
"linkedUsers": 4,
"commandUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/command",
"interactiveUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/interactive",
"manifest": "{\n \"display_information\": { \"name\": \"Nullgap\" }\n}",
"eventsUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/events",
"hasBotToken": true,
"eventsSeenAt": "2026-11-18T09:12:00.000Z",
"agentAvailable": true
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | The Slack set-up has not been started for this organisation. |
| 400 | bad_request | botToken is missing or is not a bot token, or Slack did not accept it (the app is not installed, or the token was revoked). |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Remove the Slack bot token
DELETE /api/orgs/{org}/slack-assistant/bot-token
Deletes the stored bot token. Mentions and direct messages are no longer answered and no updates are posted; the /nullgap command keeps working.
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. |
Answer (200, application/json)
A SlackAssistant object.
{
"created": true,
"connected": true,
"connectedAt": "2026-10-12T10:00:00.000Z",
"rotatedAt": "2026-11-02T10:00:00.000Z",
"linkedUsers": 4,
"commandUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/command",
"interactiveUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/interactive",
"manifest": "{\n \"display_information\": { \"name\": \"Nullgap\" }\n}",
"eventsUrl": "https://app.nullgap.example/webhooks/slack/slk_0a9c4e7b12d5/events",
"hasBotToken": true,
"eventsSeenAt": "2026-11-18T09:12:00.000Z",
"agentAvailable": true
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 404 | not_found | No bot token is saved. |
| 403 | step_up_required | Your account has multi-factor sign-in and this session has not passed a second-factor check in the last 15 minutes. Confirm with your authenticator and try again. |
#Look up a Slack link request
GET /api/orgs/{org}/slack-assistant/link/{token}
Answers which Slack user asked to be linked, so the signed-in member can check it is them before confirming. The token comes from the link that /nullgap link gives in Slack. This needs a person signed in to the console: an API key is refused.
Who may call it: A signed-in person in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
token | string | yes | The token from the link Slack gave. |
Answer (200, application/json)
A SlackLinkRequest object.
{
"slackUserId": "U04ABCD12EF",
"slackUserName": "dana",
"slackTeam": "acme",
"expiresAt": "2026-11-16T09:45:00.000Z"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The call was made with an API key. |
| 404 | not_found | The link is wrong, was already used, or has expired. The answer is the same for all three. |
#Confirm a Slack link
POST /api/orgs/{org}/slack-assistant/link/{token}
Links the Slack user behind the token to the signed-in member: from then on, what that Slack user asks the assistant is answered as this member. A link works once. Linking a Slack user that was already linked replaces the earlier link.
Who may call it: A signed-in person in the console. No API key may call it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation slug. |
token | string | yes | The token from the link Slack gave. |
Answer (200, application/json)
| Field | Type | Always present | Description |
|---|---|---|---|
linked | boolean | yes | Always true. |
slackUserName | string | yes | The Slack user name that was linked. Empty when Slack did not send one. |
{
"linked": true,
"slackUserName": "dana"
}
Errors specific to this call
| Status | Code | When |
|---|---|---|
| 403 | forbidden | The call was made with an API key. |
| 404 | not_found | The link is wrong, was already used, or has expired. |
#Objects
The objects the operations above take and return.
#SlackAssistant
The state of the organisation's Slack assistant. The signing secret and the bot token are never returned.
| Field | Type | Always present | Description |
|---|---|---|---|
created | boolean | yes | True once an owner has started the set-up. |
connected | boolean | yes | True once a signing secret is stored: requests from Slack are accepted. |
needsReconnect | boolean | no | Present, and true, only when the stored signing secret can no longer be opened. Save it again. |
connectedAt | string or null | yes | When the signing secret was first saved. Null before that. |
rotatedAt | string or null | yes | When the signing secret was last replaced. Null when it never was. |
linkedUsers | integer | yes | How many Slack users have linked their Nullgap account. |
commandUrl | string | no | Where Slack sends slash commands. Returned only to an owner signed in to the console, once the set-up has started. |
interactiveUrl | string | no | Where Slack sends button presses. Returned only to an owner signed in to the console, once the set-up has started. |
manifest | string | no | The Slack app to create, as JSON text that Slack's "from a manifest" screen accepts. Returned only to an owner signed in to the console, once the set-up has started. |
eventsUrl | string | no | Where Slack sends events (mentions of the app and direct messages to it). Returned only to an owner signed in to the console, once the set-up has started. |
hasBotToken | boolean | no | True once a bot token is stored: mentions and direct messages are answered. The token itself is never returned. |
botTokenNeedsReconnect | boolean | no | Present, and true, only when the stored bot token can no longer be opened. Save it again. |
eventsSeenAt | string or null | no | When Slack last reached the events address with a verified request. Null when it never has. |
agentAvailable | boolean | no | False when Nullgap AI is not available on this server: mentions are then answered with the list of commands. |
#SlackLinkRequest
What to show a member before they link a Slack user to their Nullgap account.
| Field | Type | Always present | Description |
|---|---|---|---|
slackUserId | string | yes | The Slack user who asked to be linked. |
slackUserName | string | yes | Their Slack user name. Empty when Slack did not send one. |
slackTeam | string | yes | The Slack workspace they asked from. Empty when Slack did not send one. |
expiresAt | string | yes | When the link stops working. |
Nullgap documentation