# Integrations HTTP API

Inputs, results, permissions and errors for the integrations endpoints.

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](https://beepgrid.com/docs/start/headless.md) supplies the credentials and entities.

<a id="get-api-v1-connections-id-channels"></a>

## 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

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.

[ProviderChannel](https://beepgrid.com/docs/reference/models/#providerchannel)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/connections/${id}/channels" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-connections-id-channels"></a>

## 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. |


### Input

Content-Type: `application/json`.

[ProviderChannel](https://beepgrid.com/docs/reference/models/#providerchannel)

### 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](https://beepgrid.com/docs/reference/models/#providerchannel)


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
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}'
```

<a id="get-api-v1-connections-id-slack-channels"></a>

## 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

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](https://beepgrid.com/docs/reference/models/#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

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/connections/${id}/slack-channels" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```