# Channels HTTP API

Inputs, results, permissions and errors for the channels 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-integrations-catalog"></a>

## Supported providers and actual fields/capabilities only

`GET /api/v1/integrations/catalog`

Supported providers and actual fields/capabilities only. Native inbox is built in; no planned integration is installable.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.


### Result and recovery

Array of ProviderCapability records with required configuration fields, native reply/approval support and setup modes.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. Array result.

[ProviderCapability](https://beepgrid.com/docs/reference/models/#providercapability)


### 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/integrations/catalog" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

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

## Non-sending credential checks and correlated diagnostic transport evidence

`GET /api/v1/connections/{id}/diagnostics`

Non-sending credential checks and correlated diagnostic transport evidence. Configuration changes reset test evidence. Provider acceptance is distinct from attributed reply and independent live qualification.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Result and recovery

ConnectionDiagnostic with safe configuration, provider acceptance and attributed engine-observed test evidence. This read sends nothing.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. [ConnectionDiagnostic](https://beepgrid.com/docs/reference/models/#connectiondiagnostic)


### 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}/diagnostics" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

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

## Explicit durable test message to one configured destination only

`POST /api/v1/connections/{id}/test`

Explicit durable test message to one configured destination only. Requires installation/destination management and Message permission. Queue acceptance is not provider acceptance. Inspect delivery evidence afterwards.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |
| `Idempotency-Key` | header (required) | Saved nonempty operation identity for a retryable creation write; keep body and key identical. |


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `destination_id` (required) | `string` | One configured delivery destination to receive this explicit connection test. |

### Result and recovery

Queued test Delivery. Read diagnostics and obtain an attributed native reply separately; acceptance is not receipt.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. [Delivery](https://beepgrid.com/docs/reference/models/#delivery)


### 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}/test" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $BEEPGRID_OPERATION_KEY" \
  --data '{"destination_id":"REPLACE_WITH_RETURNED_ID"}'
```

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

## List visible provider connections

`GET /api/v1/connections`

List visible provider connections.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.


### Result and recovery

Safe Connection array; provider secrets are not returned.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. Array result.

[Connection](https://beepgrid.com/docs/reference/models/#connection)


### 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" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

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

## Create or version-update a channel connection

`POST /api/v1/connections`

Create or version-update a channel connection.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.


### Input

Content-Type: `application/json`.

[Connection](https://beepgrid.com/docs/reference/models/#connection)

### Result and recovery

Saved Connection with secret_configured, not the secret value.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. [Connection](https://beepgrid.com/docs/reference/models/#connection)


### 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" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"Builder 7","kind":"webhook"}'
```

<a id="get-api-v1-destinations"></a>

## Read visible identity delivery destinations

`GET /api/v1/destinations`

Read visible identity delivery destinations.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.


### Result and recovery

Destination array with connection, address, mode and priority.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. Array result.

[Destination](https://beepgrid.com/docs/reference/models/#destination)


### 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/destinations" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-destinations"></a>

## Create or version-update a linked identity's channel destination

`POST /api/v1/destinations`

Create or version-update a linked identity's channel destination.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.


### Input

Content-Type: `application/json`.

[Destination](https://beepgrid.com/docs/reference/models/#destination)

### Result and recovery

Saved Destination. A destination does not grant contact permission.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. [Destination](https://beepgrid.com/docs/reference/models/#destination)


### 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/destinations" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"connection_id":"REPLACE_WITH_RETURNED_ID","principal_id":"REPLACE_WITH_RETURNED_ID","address":"REPLACE_WITH_ADDRESS"}'
```

<a id="post-api-v1-destinations-id-remove"></a>

## Remove a channel destination

`POST /api/v1/destinations/{id}/remove`

Remove a channel destination.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

`object`. See the operation-specific result contract.

### Result and recovery

`{removed: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `removed` | `boolean` | True after the operation succeeds. |


### 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/destinations/${id}/remove" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{}'
```

<a id="get-api-v1-people-id-delivery-preferences"></a>

## Read recipient channel defaults and ordered Agent/Agent role overrides

`GET /api/v1/people/{id}/delivery-preferences`

Read recipient channel defaults and ordered Agent/Agent role overrides.

**Authorization:** Person self, administrator or an explicitly authorized identity manager. Preferences never grant contact or channel authority.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Result and recovery

DeliveryPreferences with its current version; null default retains legacy destination settings.

Forbidden for another Person without management authority; stale versions conflict. Invalid selectors, foreign destinations and invalid timer bounds fail validation.

Response media type: `application/json`. [DeliveryPreferences](https://beepgrid.com/docs/reference/models/#deliverypreferences)


### 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/people/${id}/delivery-preferences" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

<a id="post-api-v1-people-id-delivery-preferences"></a>

## Save versioned recipient channel preferences

`POST /api/v1/people/{id}/delivery-preferences`

Save versioned recipient channel preferences. Individual Agent overrides win, then the first matching Agent role, then default. Preferred channels fail over on definite failure and optionally on an unresolved question/approval timer after provider acceptance. All sends selected channels immediately. Empty destinations means workspace only. Saving cancels pending external sends from the previous configuration; in-flight effects cannot be recalled.

**Authorization:** Person self, administrator or an explicitly authorized identity manager. Preferences never grant contact or channel authority.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Input

Content-Type: `application/json`.

[DeliveryPreferences](https://beepgrid.com/docs/reference/models/#deliverypreferences)

### Result and recovery

Saved DeliveryPreferences with the incremented version.

Forbidden for another Person without management authority; stale versions conflict. Invalid selectors, foreign destinations and invalid timer bounds fail validation.

Response media type: `application/json`. [DeliveryPreferences](https://beepgrid.com/docs/reference/models/#deliverypreferences)


### 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/people/${id}/delivery-preferences" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"version":0,"default":"REPLACE_WITH_DEFAULT","overrides":[{"source":{"kind":"agent","id":"REPLACE_WITH_RETURNED_ID"},"policy":{"mode":"preferred","destinations":["value"],"followup_seconds":0}}]}'
```

<a id="post-api-v1-route-preview"></a>

## Inspect eligible delivery routes without sending

`POST /api/v1/route-preview`

Inspect eligible delivery routes without sending.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `target` (required) | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `action` (required) | `string` | Communication action to inspect, for example message or ask; not a bound business Action descriptor. |

### Result and recovery

`recipients`, total `count`, `hidden_recipients`, `mode=private_per_recipient` and `sends=false`. This preview has no dispatch token.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `recipients` | array of [Person](https://beepgrid.com/docs/reference/models/#person) or [Agent](https://beepgrid.com/docs/reference/models/#agent) or [Service](https://beepgrid.com/docs/reference/models/#service) | Visible resolved recipients. |
| `count` | `integer` | Total eligible recipients. |
| `hidden_recipients` | `integer` | Eligible recipients whose metadata is hidden. |
| `mode` | `string` | private_per_recipient. |
| `sends` | `boolean` | Always false. |


### 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/route-preview" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"target":{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"},"action":"REPLACE_WITH_ACTION"}'
```

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

## Authorized credential-free setup steps and generated BYO manifest

`GET /api/v1/connections/{id}/setup`

Authorized credential-free setup steps and generated BYO manifest. Never contacts providers or changes registrations.

**Authorization:** Authenticated identity with current connection/destination visibility or management authority. Sending a test also requires contact rights.

| Parameter | Location | Usage |
| --- | --- | --- |
| `id` | path (required) | Stable identifier returned by the engine. Treat it as opaque. |


### Result and recovery

ProviderSetup: safe callbacks, manifests/registration steps and current diagnostic evidence, without credentials.

Invalid provider fields, missing verified account or disallowed URL fail validation. A stale configuration version conflicts. Provider acceptance alone does not establish a reply.

Response media type: `application/json`. [ProviderSetup](https://beepgrid.com/docs/reference/models/#providersetup)


### 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}/setup" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```