Integrations HTTP API
Use the server URL of your own deployment. Worker examples require a currently valid bearer token; provider callbacks use native signatures. REPLACE_WITH_RETURNED_ID values refer to IDs obtained through setup or prior operations. Headless setup supplies the credentials and entities.
Read configured Slack channels and Agent access
Section titled “Read configured Slack channels and Agent access”GET /api/v1/connections/{id}/channels
Read configured Slack channels and Agent access. One policy applies to the channel across recipient destinations.
Authorization: Authorized connection managers only.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Result and recovery
Section titled “Result and recovery”Array of ProviderChannel records with address, display name, restricted flag, allowed Agent and Agent role targets, and version.
Unauthorized callers are denied. Existing channel configuration does not prove provider delivery.
Response media type: application/json. Array result.
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/connections/${id}/channels" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Save versioned Slack channel settings and an optional Agent allowlist
Section titled “Save versioned Slack channel settings and an optional Agent allowlist”POST /api/v1/connections/{id}/channels
Save versioned Slack channel settings and an optional Agent allowlist. This narrows contact permission and does not grant conversation membership.
Authorization: Authorized connection managers only. Targets must be existing Agents or Agent roles in this workspace.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Content-Type: application/json.
Result and recovery
Section titled “Result and recovery”The saved ProviderChannel with its new version. Restricted channels with an empty allowed list block every Agent. People remain subject to their own contact and decision permissions.
Stale versions conflict. Use version 0 for a new channel. Restrictions apply to future dispatches, queued sends, replies and fallbacks; sends already in flight cannot be recalled.
Response media type: application/json. ProviderChannel
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/connections/${id}/channels" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"address":"REPLACE_WITH_ADDRESS","name":"Builder 7","restricted":false,"allowed":[{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"}],"version":1}'List one page of joined, non-archived Slack channels
Section titled “List one page of joined, non-archived Slack channels”GET /api/v1/connections/{id}/slack-channels
List one page of joined, non-archived Slack channels. Pass next_cursor as the cursor query parameter to continue even after an empty page.
Authorization: Authorized connection managers only, with a configured Slack bot.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
cursor |
query (optional) | Opaque continuation token, scoped to the same actor, workspace and query; expires after 24 hours. |
Result and recovery
Section titled “Result and recovery”Object containing channels and optional next_cursor. The engine requests one bounded provider page and keeps bot credentials server-side.
Missing Slack scopes require updating the manifest and reinstalling the app. Invite the bot to each desired channel. Rate limits require waiting; this lookup never joins channels or changes the provider.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| channels | array of ProviderChannel | One bounded page of Slack channels the configured bot has joined. Follow next_cursor even if this filtered page is empty. |
| next_cursor | string | Opaque next-page cursor. Continue even when the current items array is empty. |
HTTP usage
Section titled “HTTP usage”Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/connections/${id}/slack-channels" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"