Channels 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.
Supported providers and actual fields/capabilities only
Section titled “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
Section titled “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.
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/integrations/catalog" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Non-sending credential checks and correlated diagnostic transport evidence
Section titled “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
Section titled “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
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}/diagnostics" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Explicit durable test message to one configured destination only
Section titled “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. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
destination_id (required) |
string |
One configured delivery destination to receive this explicit connection test. |
Result and recovery
Section titled “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
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}/test" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $BEEPGRID_OPERATION_KEY" \ --data '{"destination_id":"REPLACE_WITH_RETURNED_ID"}'List visible provider connections
Section titled “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
Section titled “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.
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" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Create or version-update a channel connection
Section titled “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.
Content-Type: application/json.
Result and recovery
Section titled “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
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" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"name":"Builder 7","kind":"webhook"}'Read visible identity delivery destinations
Section titled “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
Section titled “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.
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/destinations" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Create or version-update a linked identity’s channel destination
Section titled “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.
Content-Type: application/json.
Result and recovery
Section titled “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
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/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"}'Remove a channel destination
Section titled “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. |
Content-Type: application/json.
object. See the operation-specific result contract.
Result and recovery
Section titled “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
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/destinations/${id}/remove" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{}'Read recipient channel defaults and ordered Agent/Agent role overrides
Section titled “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
Section titled “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
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/people/${id}/delivery-preferences" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Save versioned recipient channel preferences
Section titled “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. |
Content-Type: application/json.
Result and recovery
Section titled “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
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/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}}]}'Inspect eligible delivery routes without sending
Section titled “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.
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
target (required) |
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
Section titled “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 or Agent or 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
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/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"}'Authorized credential-free setup steps and generated BYO manifest
Section titled “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
Section titled “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
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}/setup" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"