Requests 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 authorized request, paged delivery evidence and execution reports
Section titled “Current authorized request, paged delivery evidence and execution reports”GET /api/v1/requests/{id}/trace
Current authorized request, paged delivery evidence and execution reports. Audience members see their own projection; requesters can inspect their outgoing deliveries. Provider acceptance never proves execution.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
delivery_cursor |
query (optional) | Opaque next-page cursor for request trace delivery evidence; empty starts the first page. |
Result and recovery
Section titled “Result and recovery”request plus independently paginated deliveries and executions, with an evidence explanation. Continue transport pages using the supplied cursor.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| request | Request | Nested requested-decision input or canonical request in a batch result. |
| deliveries | object | Paginated transport evidence; continue using its own next_cursor. |
| executions | object | Paginated authenticated executor reports, separate from transport delivery. |
| evidence | string | Explains transport versus executor-reported business evidence. |
deliveries fields
| Field | Type | Usage |
|---|---|---|
deliveries.items |
array of JSON value |
Authorized records returned by this page. |
deliveries.next_cursor |
string |
Opaque next-page cursor. Continue even when the current items array is empty. |
deliveries.order |
string |
Documented ordering for this collection. |
executions fields
| Field | Type | Usage |
|---|---|---|
executions.items |
array of JSON value |
Authorized records returned by this page. |
executions.next_cursor |
string |
Opaque next-page cursor. Continue even when the current items array is empty. |
executions.order |
string |
Documented ordering for this collection. |
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/requests/${id}/trace" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"List requests visible to the caller
Section titled “List requests visible to the caller”GET /api/v1/requests
List requests visible to the caller.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
Result and recovery
Section titled “Result and recovery”Request array. Use query to filter/page; visibility is not the same as being the requester.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
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/requests" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Open a question, approval or task with a saved final response
Section titled “Open a question, approval or task with a saved final response”POST /api/v1/requests
Open a question, approval or task with a saved final response.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
Idempotency-Key |
header (required) | Saved nonempty operation identity for a retryable creation write; keep body and key identical. |
Content-Type: application/json.
Result and recovery
Section titled “Result and recovery”Request with state=open and current version. Ordinary communication has no implicit deadline; bound action approvals default to seven days when expiry is omitted.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Request
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/requests" \ -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 a visible request and its current decision
Section titled “Read a visible request and its current decision”GET /api/v1/requests/{id}
Read a visible request and its current decision.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Result and recovery
Section titled “Result and recovery”Request with optional response. Terminal state must be inspected explicitly.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Request
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/requests/${id}" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Record an eligible typed final decision
Section titled “Record an eligible typed final decision”POST /api/v1/requests/{id}/responses
Record an eligible typed final decision.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| 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”Updated Request. Sending ordinary conversation text never records this decision.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Request
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/requests/${id}/responses" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"outcome":"answered","version":1}'Answer a question and publish authorized reusable information atomically
Section titled “Answer a question and publish authorized reusable information atomically”POST /api/v1/requests/{id}/answer-and-share
Answer a question and publish authorized reusable information atomically.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
outcome (required) |
answered |
Typed final result: answered; approved/denied; or completed/failed/rejected according to request kind. |
answer (required) |
JSON value |
JSON response value; for choices, the selected exact string. |
version (required) |
integer |
Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
audience (required) |
array of string |
Explicit identities allowed to reuse the published informational answer. |
Result and recovery
Section titled “Result and recovery”Resolved Request and published answer information. Only informational question answers can be reused.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Request
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/requests/${id}/answer-and-share" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"outcome":"answered","answer":"REPLACE_WITH_ANSWER","version":1,"audience":["value"]}'Atomically supersede your pending request and create its replacement
Section titled “Atomically supersede your pending request and create its replacement”POST /api/v1/requests/{id}/replace
Atomically supersede your pending request and create its replacement.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
version (required) |
integer |
Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
body (required) |
string |
Message or request content, bounded to 32 KiB of UTF-8 bytes. minLength=1, maxLength=32768. |
mentions |
array of Mention | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. maxItems=20. |
Result and recovery
Section titled “Result and recovery”Object with previous and replacement Request records. Continue using replacement.id.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| previous (required) | Request | Original request after supersession. |
| replacement (required) | Request | New pending request; future decisions use this ID. |
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/requests/${id}/replace" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"version":1,"body":"Hold the staging rollout until checkout jobs drain."}'Withdraw your own pending request at its current version
Section titled “Withdraw your own pending request at its current version”POST /api/v1/requests/{id}/cancel
Withdraw your own pending request at its current version.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
version (required) |
integer |
Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
Result and recovery
Section titled “Result and recovery”Request with state=cancelled. Does not undo an external effect.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Request
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/requests/${id}/cancel" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"version":1}'Mark your pending request as superseded
Section titled “Mark your pending request as superseded”POST /api/v1/requests/{id}/supersede
Mark your pending request as superseded.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
version (required) |
integer |
Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
Result and recovery
Section titled “Result and recovery”Request with state=superseded; this does not create a replacement. Use replace to create a revised request atomically.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Request
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/requests/${id}/supersede" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"version":1}'Redeem an exact bound approval for its declared executor/action
Section titled “Redeem an exact bound approval for its declared executor/action”POST /api/v1/requests/{id}/redeem
Redeem an exact bound approval for its declared executor/action.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| 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”Execution intent. The external resource owner still enforces execution and idempotency fences.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Execution
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/requests/${id}/redeem" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"name":"Builder 7","executor_id":"REPLACE_WITH_RETURNED_ID","resource":"REPLACE_WITH_RESOURCE","resource_version":"REPLACE_WITH_RESOURCE_VERSION","operation_key":"REPLACE_WITH_OPERATION_KEY"}'Read currently visible execution observations
Section titled “Read currently visible execution observations”GET /api/v1/executions
Read currently visible execution observations.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
Result and recovery
Section titled “Result and recovery”Execution array; worker-reported state is not independent verification.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
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/executions" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Record an authorized executor’s observed outcome
Section titled “Record an authorized executor’s observed outcome”POST /api/v1/executions/{id}
Record an authorized executor’s observed outcome.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
state (required) |
running | succeeded | failed | unknown |
Lifecycle state. Read the resource-specific enum; request and execution states differ. |
result |
JSON value |
Executor-reported JSON result. It is not independent proof of an external effect. |
Result and recovery
Section titled “Result and recovery”Updated Execution; terminal results cannot be overwritten.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Execution
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/executions/${id}" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"state":"running"}'Only the requesting agent may declare or clear its own open single-agent blocking dependency
Section titled “Only the requesting agent may declare or clear its own open single-agent blocking dependency”POST /api/v1/requests/{id}/blocking
Only the requesting agent may declare or clear its own open single-agent blocking dependency. Does not cancel the request.
Authorization: Current requester, authorized original decision recipient or exact bound executor, according to operation.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
blocking (required) |
boolean |
Explicit requester-declared agent dependency. Ordinary pending questions are not automatically blocking. |
Result and recovery
Section titled “Result and recovery”Updated Request with blocking state.
Invalid outcome/choice fails validation. A stale request version or terminal-state race conflicts. Permission is rechecked at decision, redemption and reporting.
Response media type: application/json. Request
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/requests/${id}/blocking" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"blocking":false}'