Nullgap.dev Docs

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.

OperationMethod and pathWho may call it
Get the Slack assistantGET /api/orgs/{org}/slack-assistantread
Start the Slack set-upPOST /api/orgs/{org}/slack-assistantconsole only (owner)
Remove the Slack assistantDELETE /api/orgs/{org}/slack-assistantconsole only (owner)
Save the Slack signing secretPUT /api/orgs/{org}/slack-assistant/signing-secretconsole only (owner)
Save the Slack bot tokenPUT /api/orgs/{org}/slack-assistant/bot-tokenconsole only (owner)
Remove the Slack bot tokenDELETE /api/orgs/{org}/slack-assistant/bot-tokenconsole only (owner)
Look up a Slack link requestGET /api/orgs/{org}/slack-assistant/link/{token}console only
Confirm a Slack linkPOST /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

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

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

StatusCodeWhen
403step_up_requiredYour 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

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

StatusCodeWhen
404not_foundThe Slack assistant is not set up for this organisation.
403step_up_requiredYour 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

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

StatusCodeWhen
404not_foundThe Slack set-up has not been started for this organisation.
400bad_requestsigningSecret is missing, too short or long, or has characters other than letters and digits.
403step_up_requiredYour 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.

Request body (application/json)

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

StatusCodeWhen
404not_foundThe Slack set-up has not been started for this organisation.
400bad_requestbotToken is missing or is not a bot token, or Slack did not accept it (the app is not installed, or the token was revoked).
403step_up_requiredYour 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

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

StatusCodeWhen
404not_foundNo bot token is saved.
403step_up_requiredYour 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.
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

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

StatusCodeWhen
403forbiddenThe call was made with an API key.
404not_foundThe 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

NameTypeRequiredDescription
orgstringyesThe organisation slug.
tokenstringyesThe token from the link Slack gave.

Answer (200, application/json)

FieldTypeAlways presentDescription
linkedbooleanyesAlways true.
slackUserNamestringyesThe Slack user name that was linked. Empty when Slack did not send one.
{
  "linked": true,
  "slackUserName": "dana"
}

Errors specific to this call

StatusCodeWhen
403forbiddenThe call was made with an API key.
404not_foundThe 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.

FieldTypeAlways presentDescription
createdbooleanyesTrue once an owner has started the set-up.
connectedbooleanyesTrue once a signing secret is stored: requests from Slack are accepted.
needsReconnectbooleannoPresent, and true, only when the stored signing secret can no longer be opened. Save it again.
connectedAtstring or nullyesWhen the signing secret was first saved. Null before that.
rotatedAtstring or nullyesWhen the signing secret was last replaced. Null when it never was.
linkedUsersintegeryesHow many Slack users have linked their Nullgap account.
commandUrlstringnoWhere Slack sends slash commands. Returned only to an owner signed in to the console, once the set-up has started.
interactiveUrlstringnoWhere Slack sends button presses. Returned only to an owner signed in to the console, once the set-up has started.
manifeststringnoThe 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.
eventsUrlstringnoWhere 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.
hasBotTokenbooleannoTrue once a bot token is stored: mentions and direct messages are answered. The token itself is never returned.
botTokenNeedsReconnectbooleannoPresent, and true, only when the stored bot token can no longer be opened. Save it again.
eventsSeenAtstring or nullnoWhen Slack last reached the events address with a verified request. Null when it never has.
agentAvailablebooleannoFalse 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.

FieldTypeAlways presentDescription
slackUserIdstringyesThe Slack user who asked to be linked.
slackUserNamestringyesTheir Slack user name. Empty when Slack did not send one.
slackTeamstringyesThe Slack workspace they asked from. Empty when Slack did not send one.
expiresAtstringyesWhen the link stops working.

Nullgap documentation