# Communication HTTP API

Inputs, results, permissions and errors for the communication 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="post-api-v1-capabilities"></a>

## Current operation eligibility, not an authorization token

`POST /api/v1/capabilities`

Current operation eligibility, not an authorization token. Every mutation rechecks current policy. Exact requests include audience, original Ask, reverse response and conditions.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `target` | `object` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `request_id` | `string` | Canonical durable request ID. This is not a worker delivery ID. |
| `connection_id` | `string` | Configured channel connection ID. |
| `descriptor` | [Action](https://beepgrid.com/docs/reference/models/#action) | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |

**`target` fields**

| Field | Type | Usage |
| --- | --- | --- |
| `target.kind` | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `target.id` | `string` | Stable identifier returned by the engine. Treat it as opaque. |

### Result and recovery

CapabilityResult: observed_at, operation-name booleans, and optional request_version/outcomes for a requested decision.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `observed_at` | `string` | Timestamp of this capability snapshot. |
| `operations` | `object` | Map of action names to currently allowed booleans. Actual mutation checks again. |
| `request_version` | `integer` | Request version observed during capability evaluation. |
| `outcomes` | array of `string` | Currently allowed typed decision outcomes. |


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

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

## Own effective access, including direct/group role provenance

`GET /api/v1/access`

Own effective access, including direct/group role provenance. Inspecting another subject requires identity visibility and explicit view access:<subject ID>, or an administrator credential.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.

| Parameter | Location | Usage |
| --- | --- | --- |
| `subject_id` | query (optional) | Identity or directory group receiving a policy-role assignment. |


### Result and recovery

AccessSnapshot: subject, authority basis, role assignments with provenance and observation time.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `subject` | `object` | Authorized subject projection of the access inspection. |
| `basis` | `string` | Recorded authorization basis for this access projection; not a transferable grant. |
| `roles` | array of `object` | Effective policy-role assignments with direct/group provenance. |
| `observed_at` | `string` | Timestamp of this capability snapshot. |

**`roles` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `roles[].role` | [Role](https://beepgrid.com/docs/reference/models/#role) | Policy role object to preview or inspect; separate from an agent_role directory group. |
| `roles[].subject_kind` | `string` | principal for an individual identity, or group for a directory group. |
| `roles[].subject_id` | `string` | Identity or directory group receiving a policy-role assignment. |


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

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

## Complete bounded keyset reads with current per-record authorization

`POST /api/v1/query`

Complete bounded keyset reads with current per-record authorization. Continue until next_cursor is absent, including empty pages. Cursors are encrypted and bound to scope, actor, filters and limit for 24 hours. Message history requires conversation_id and is chronological; other collections use stable ascending IDs. Unsupported filters are rejected.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `collection` (required) | `people \| agents \| services \| groups \| roles \| connections \| destinations \| credentials \| instances \| requests \| conversations \| messages \| answers \| executions \| deliveries \| delivery_attempts \| attachments \| overseer_plans` | One of the documented query collections. |
| `search` | `string` | Optional text search, at most 200 characters. |
| `filters` | `object` | Supported exact collection filters, not arbitrary SQL or JSON selectors. |
| `limit` | `integer` | Page size: default 50, minimum 1, maximum 200. minimum=1, maximum=200. |
| `cursor` | `string` | Opaque continuation token, scoped to the same actor, workspace and query; expires after 24 hours. |

### Result and recovery

QueryPage: collection-specific items, optional next_cursor and stable order. Continue while next_cursor exists, including empty visible pages.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `items` | array of `JSON value` | Authorized records returned by this page. |
| `next_cursor` | `string` | Opaque next-page cursor. Continue even when the current items array is empty. |
| `order` | `string` | Documented ordering for this collection. |


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

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

## Non-sending preview of 1 to 100 explicit individual/instance targets

`POST /api/v1/dispatch-preview`

Non-sending preview of 1 to 100 explicit individual/instance targets. Includes native, primary, copy and fallback permission/enablement observations. Token binds the authorized audience and route revisions for ten minutes. Hidden recipient identities and addresses remain private.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `targets` (required) | array of [Target](https://beepgrid.com/docs/reference/models/#target) | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `operation` (required) | `message \| ask` | Requested operation, with values defined by that endpoint. |
| `descriptor` | [Action](https://beepgrid.com/docs/reference/models/#action) | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |

### Result and recovery

Resolved recipient and route projection, a short-lived token and expiry; `sends` is false.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `recipients` | array of `object` | Recipients visible to this caller. |
| `count` | `integer` | Total eligible recipient count. |
| `hidden_recipients` | `integer` | Recipient count whose metadata is not disclosed. |
| `token` | `string` | Short-lived audience/route fingerprint for the matching write. |
| `expires_at` | `string` | Token expiry. format="date-time". |
| `sends` | `boolean` | Always false; preview does not dispatch. |

**`recipients` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `recipients[].target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `recipients[].name` | `string` | Visible recipient display name. |
| `recipients[].routes` | array of `object` | Permitted and rejected visible routes. |

**`recipients[].routes` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `recipients[].routes[].kind` | `string` | Connection/provider kind. |
| `recipients[].routes[].mode` | `string` | Destination routing mode. |
| `recipients[].routes[].enabled` | `boolean` | Connection enabled state. |
| `recipients[].routes[].permitted` | `boolean` | Current policy result. |
| `recipients[].routes[].reason` | `string` | Reason for the routing result. |


### 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/dispatch-preview" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"targets":[{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"}],"operation":"message"}'
```

<a id="post-api-v1-message-batches"></a>

## Atomic explicit recipient dispatch, deduplicated by logical identity

`POST /api/v1/message-batches`

Atomic explicit recipient dispatch, deduplicated by logical identity. Conflicting replica targets are rejected. Private conversations and per-target receipts; failure rolls back the entire batch. Optional preview token prevents changed routes/audience from silently proceeding.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.

| Parameter | Location | Usage |
| --- | --- | --- |
| `Idempotency-Key` | header (required) | Saved nonempty operation identity for a retryable creation write; keep body and key identical. |
| `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 |
| --- | --- | --- |
| `targets` (required) | array of [Target](https://beepgrid.com/docs/reference/models/#target) | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `body` (required) | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `preview_token` | `string` | Dispatch preview token. A stale audience or route requires a fresh preview. |
| `attachment_ids` | array of `string` | IDs of staged private drafts to claim in the initial operation; at most five. maxItems=5. |

### Result and recovery

Array of {target, result: SendResult}. Every target retains its own private history and canonical attribution.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

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

| Field | Type | Usage |
| --- | --- | --- |
| `[].target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `[].result` | [SendResult](https://beepgrid.com/docs/reference/models/#sendresult) | Executor-reported JSON result. It is not independent proof of an external effect. |


### 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/message-batches" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $BEEPGRID_OPERATION_KEY" \
  --data '{"targets":[{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"}],"body":"Hold the staging rollout until checkout jobs drain."}'
```

<a id="post-api-v1-request-batches"></a>

## Atomic private request per explicit target

`POST /api/v1/request-batches`

Atomic private request per explicit target. Each request has an independent response and execution lifecycle; no implicit shared approval or first-responder broadcast. The nested request must omit target and conversation_id.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.

| Parameter | Location | Usage |
| --- | --- | --- |
| `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 |
| --- | --- | --- |
| `targets` (required) | array of [Target](https://beepgrid.com/docs/reference/models/#target) | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `request` (required) | [AskInput](https://beepgrid.com/docs/reference/models/#askinput) | Nested requested-decision input or canonical request in a batch result. |
| `preview_token` | `string` | Dispatch preview token. A stale audience or route requires a fresh preview. |

### Result and recovery

Array of {target, request: Request}. Requests resolve independently after atomic batch creation.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

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

| Field | Type | Usage |
| --- | --- | --- |
| `[].target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `[].request` | [Request](https://beepgrid.com/docs/reference/models/#request) | Nested requested-decision input or canonical request in a batch result. |


### 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/request-batches" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $BEEPGRID_OPERATION_KEY" \
  --data '{"targets":[{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"}],"request":{"target":{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"},"body":"Hold the staging rollout until checkout jobs drain."}}'
```

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

## Authenticated scope, company, environment, deployment kind and schema version

`GET /api/v1/workspace`

Authenticated scope, company, environment, deployment kind and schema version. Managed composition supplies deployment metadata explicitly.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Result and recovery

Workspace metadata and current account-read capability.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `scope` | `string` | Selected workspace scope ID. |
| `company` | `string` | Workspace display name. |
| `environment` | `string` | Selected environment label. |
| `can_read_account` | `boolean` | Whether this caller may inspect the account projection. |


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

<a id="get-api-v1-workspace-account"></a>

## Person-only scoped account access requires view account:workspace or an administrator credential

`GET /api/v1/workspace/account`

Person-only scoped account access requires view account:workspace or an administrator credential. This entry point permits status inspection during service suspension with a still-valid credential and current account policy. Runtime-applied quotas/usage are separate from server-side managed requested/provisioning/entitlement state. No operator tokens enter the browser; managed read failures are 503, never zero usage.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Result and recovery

Current authorized account snapshot, applied limits and UTC-month usage. This OSS projection does not expose a managed payment provider.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `scope` | `string` | Selected workspace scope ID. |
| `company` | `string` | Workspace display name. |
| `environment` | `string` | Selected environment label. |
| `can_read_account` | `boolean` | Whether this caller may inspect the account projection. |
| `suspended` | `boolean` | Whether the workspace is suspended. |
| `recovery_hold` | `boolean` | Whether restore reconciliation holds outbound work. |
| `access_until` | `string` | Optional access cutoff. format="date-time". |
| `control_version` | `integer` | Applied control revision. |
| `budget` | `object` | Applied runtime budget, or null when none is configured. |
| `usage` | array of `object` | Recorded usage, not provider attempts or CPU/memory. |
| `metered` | `boolean` | Whether an applied budget is configured. |
| `source` | `string` | applied_runtime for the OSS store; a configured account bridge may supply its own source. |

**`budget` fields**

| Field | Type | Usage |
| --- | --- | --- |
| `budget.version` | `integer` | Applied budget revision. |
| `budget.messages` | `integer` | Monthly canonical recipient-message allowance; -1 means unlimited. |
| `budget.requests` | `integer` | Monthly requested-reply allowance; -1 means unlimited. |
| `budget.upload_bytes` | `integer` | Monthly accepted-upload byte allowance; -1 means unlimited. |

**`usage` fields**

Array result.

| Field | Type | Usage |
| --- | --- | --- |
| `usage[].period` | `string` | UTC month boundary. format="date-time". |
| `usage[].metric` | `string` | Counted usage category. |
| `usage[].units` | `integer` | Recorded canonical units. |


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

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

## Read the authenticated identity and credential scope

`GET /api/v1/me`

Read the authenticated identity and credential scope.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Result and recovery

`identity_type`, matching `person`/`agent`/`service`, `instance_id`, `admin`, `can_publish_answers`, `company` and `environment`. Only the matching identity-kind key is returned.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `identity_type` | `string` | person, agent or service. |
| `person` | [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) | Person identity projection; present only for a person caller. |
| `agent` | [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) | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `service` | [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) | Software service projection; present only for a service caller. |
| `instance_id` | `string` | Current exact runtime ID, or empty for a non-runtime credential. |
| `admin` | `boolean` | Whether the actual credential has administrator authority. |
| `can_publish_answers` | `boolean` | Current answer-publication capability. |
| `company` | `string` | Workspace display name. |
| `environment` | `string` | Environment label. |


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

<a id="post-api-v1-permissions-explain"></a>

## Explain the current decision for a subject, action and target

`POST /api/v1/permissions/explain`

Explain the current decision for a subject, action and target.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `subject_id` | `string` | Identity or directory group receiving a policy-role assignment. |
| `action` (required) | `string` | Optional exact bound-action descriptor for the advanced execution contract. |
| `target` (required) | `object` | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
| `connection_id` | `string` | Configured channel connection ID. |
| `action_name` | `string` | Optional action-name constraint; not required for ordinary approval communication. |
| `descriptor` | [Action](https://beepgrid.com/docs/reference/models/#action) | Optional exact Action descriptor used to evaluate conditional permission, not an executed action. |

**`target` fields**

| Field | Type | Usage |
| --- | --- | --- |
| `target.kind` (required) | `string` | Resource or operation kind. Use one of the listed values, not a display label. |
| `target.id` (required) | `string` | Stable identifier returned by the engine. Treat it as opaque. |

### Result and recovery

Allowed/denied projection and the applicable authorization basis.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. `object`. See the operation-specific result contract.


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

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

## Start an explicit shared chat with a durable first message

`POST /api/v1/conversations`

Start an explicit shared chat with a durable first message. Individual recipients only; all members must have current mutual view permission. Every later send checks current contact access. Idempotent; private broadcast contracts are unchanged.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.

| Parameter | Location | Usage |
| --- | --- | --- |
| `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 |
| --- | --- | --- |
| `targets` (required) | array of [Target](https://beepgrid.com/docs/reference/models/#target) | Explicit targets for a private batch or shared chat. These have different audience semantics. |
| `body` (required) | `string` | Message or request content, bounded to 32 KiB of UTF-8 bytes. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `approval` | `boolean` | Attach a typed approval request to the initial shared chat message. False by default. |
| `choices` | array of `string` | Optional exact answer strings. A chosen answer must match an offered value. |
| `mentions` | array of [Mention](https://beepgrid.com/docs/reference/models/#mention) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. maxItems=20. |
| `attachment_ids` | array of `string` | IDs of staged private drafts to claim in the initial operation; at most five. maxItems=5. |

### Result and recovery

SendResult containing the new shared conversation_id and canonical first messages.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

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


### 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/conversations" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $BEEPGRID_OPERATION_KEY" \
  --data '{"targets":[{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"}],"body":"Hold the staging rollout until checkout jobs drain."}'
```

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

## Read visible conversation summaries in recent-activity order

`GET /api/v1/conversations`

Read visible conversation summaries in recent-activity order.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Result and recovery

Conversation array. Use query for bounded complete pagination.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

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

[Conversation](https://beepgrid.com/docs/reference/models/#conversation)


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

<a id="post-api-v1-contact-permissions"></a>

## Atomically save and assign a dedicated contact-access policy

`POST /api/v1/contact-permissions`

Atomically save and assign a dedicated contact-access policy. Only view, message, ask and decide toward exact contacts. Existing delegation ceilings and observed-version checks apply. Inherited policies remain effective.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `subject` (required) | [Target](https://beepgrid.com/docs/reference/models/#target) | Authorized subject projection of the access inspection. |
| `rules` (required) | array of [Rule](https://beepgrid.com/docs/reference/models/#rule) | Directional permission rules granted by this policy role. |
| `version` (required) | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |

### Result and recovery

The saved Role containing the chosen directional contact rules. Chat membership is separate.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

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


### 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/contact-permissions" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"subject":{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"},"rules":[{"action":"view","target_kind":"REPLACE_WITH_TARGET_KIND","target_id":"REPLACE_WITH_RETURNED_ID"}],"version":1}'
```

<a id="post-api-v1-conversations-id-membership"></a>

## Versioned and idempotent shared-chat membership

`POST /api/v1/conversations/{id}/membership`

Versioned and idempotent shared-chat membership. Manager or admin can rename/add/remove; members can leave. New members see history from joining unless share_history is explicitly true. Current mutual View is required; membership grants no contact, decision or tool authority. Removing or leaving stops future read and delivery; already downloaded data cannot be recalled. A departing manager names an existing successor.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.

| 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 |
| --- | --- | --- |
| `operation` (required) | `rename \| add \| remove \| leave` | Requested operation, with values defined by that endpoint. |
| `version` (required) | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. minimum=1. |
| `title` | `string` | Optional short label. A normal message does not require a title. |
| `members` | array of `string` | Directory-group or chat member identity IDs. Membership never substitutes for contact authority. maxItems=100. |
| `share_history` | `boolean` | Explicitly disclose earlier history to additions. False by default. default=false. |
| `next_manager` | `string` | Existing participant to manage the chat when the current manager leaves. |

### Result and recovery

conversation_id and new version, with left=true when the caller leaves.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `conversation_id` | `string` | Canonical conversation ID. Use it to continue the same authorized history. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `left` | `boolean` | True when the membership operation removed the caller from the shared conversation. |


### 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/conversations/${id}/membership" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $BEEPGRID_OPERATION_KEY" \
  --data '{"operation":"rename","version":1}'
```

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

## Read a conversation's currently disclosed history

`GET /api/v1/conversations/{id}`

Read a conversation's currently disclosed history.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.

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


### Result and recovery

Conversation with participants, messages and shared membership metadata.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

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


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

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

## Durably store canonical messages and queue deliveries

`POST /api/v1/messages`

Durably store canonical messages and queue deliveries. Prefer: return=minimal returns a compact acceptance receipt; it is not delivery or execution confirmation. Replay the same input and idempotency key without Prefer to retrieve the full result without resending.

**Authorization:** Authenticated caller with view/message/ask authority for the resolved recipients or current conversation history.

| Parameter | Location | Usage |
| --- | --- | --- |
| `Idempotency-Key` | header (required) | Saved nonempty operation identity for a retryable creation write; keep body and key identical. |
| `Prefer` | header (optional) | Optional return=minimal; full SendResult remains the default. |


### Input

Content-Type: `application/json`.

[SendInput](https://beepgrid.com/docs/reference/models/#sendinput)

### Result and recovery

SendResult containing conversation_id and messages, or SendReceipt containing conversation_id and message_count when Prefer: return=minimal is requested.

Changed audience/preview, conflicting versions, hidden history or missing reverse contact rights reject the operation. Reuse the same saved key only for the same intended write.

Response media type: `application/json`. [SendResult](https://beepgrid.com/docs/reference/models/#sendresult) or [SendReceipt](https://beepgrid.com/docs/reference/models/#sendreceipt)


### 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/messages" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $BEEPGRID_OPERATION_KEY" \
  --data '{"target":{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"},"body":"Hold the staging rollout until checkout jobs drain."}'
```