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

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

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 '{}'

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:, 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	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.

curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/access" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"

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.

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"}'

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

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"}'

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	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	Target kind and stable ID. Choose a new target or an existing conversation, not both.
[].result	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.

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."}'

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	Explicit targets for a private batch or shared chat. These have different audience semantics.
request (required)	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	Target kind and stable ID. Choose a new target or an existing conversation, not both.
[].request	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.

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."}}'

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.

curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/workspace" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"

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.

curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/workspace/account" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"

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 or Agent or Service | Person identity projection; present only for a person caller. | | agent | Person or Agent or Service | Stable agent external ID when enrolling; an Agent object in a Session response. | | service | Person or Agent or 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.

curl --fail-with-body --silent --show-error -X GET "$BEEPGRID_URL/api/v1/me" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"

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

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"}}'

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

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/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."}'

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

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

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	Authorized subject projection of the access inspection.
rules (required)	array of 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

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/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}'

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.

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

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

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

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

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 or SendReceipt

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/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."}'

---

Read this page as Markdown