# Requests HTTP API

Inputs, results, permissions and errors for the requests endpoints.

Use the server URL of your own deployment. Worker examples require a currently valid bearer token; provider callbacks use native signatures. `REPLACE_WITH_RETURNED_ID` values refer to IDs obtained through setup or prior operations. [Headless setup](https://beepgrid.com/docs/start/headless.md) supplies the credentials and entities.

<a id="get-api-v1-requests-id-trace"></a>

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

`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](https://beepgrid.com/docs/reference/models/#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

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

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

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

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.

[Request](https://beepgrid.com/docs/reference/models/#request)


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

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

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


### Input

Content-Type: `application/json`.

[AskInput](https://beepgrid.com/docs/reference/models/#askinput)

### 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](https://beepgrid.com/docs/reference/models/#request)


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

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

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

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](https://beepgrid.com/docs/reference/models/#request)


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

<a id="post-api-v1-requests-id-responses"></a>

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


### Input

Content-Type: `application/json`.

[ResponseInput](https://beepgrid.com/docs/reference/models/#responseinput)

### 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](https://beepgrid.com/docs/reference/models/#request)


### 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/requests/${id}/responses" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"outcome":"answered","version":1}'
```

<a id="post-api-v1-requests-id-answer-and-share"></a>

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


### Input

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

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](https://beepgrid.com/docs/reference/models/#request)


### 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/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"]}'
```

<a id="post-api-v1-requests-id-replace"></a>

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


### Input

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](https://beepgrid.com/docs/reference/models/#mention) | Addressing metadata for existing chat participants. It does not narrow audience or grant authority. maxItems=20. |

### 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](https://beepgrid.com/docs/reference/models/#request) | Original request after supersession. |
| `replacement` (required) | [Request](https://beepgrid.com/docs/reference/models/#request) | New pending request; future decisions use this ID. |


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

<a id="post-api-v1-requests-id-cancel"></a>

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


### Input

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

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](https://beepgrid.com/docs/reference/models/#request)


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

<a id="post-api-v1-requests-id-supersede"></a>

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


### Input

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

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](https://beepgrid.com/docs/reference/models/#request)


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

<a id="post-api-v1-requests-id-redeem"></a>

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


### Input

Content-Type: `application/json`.

[Action](https://beepgrid.com/docs/reference/models/#action)

### 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](https://beepgrid.com/docs/reference/models/#execution)


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

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

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

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.

[Execution](https://beepgrid.com/docs/reference/models/#execution)


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

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

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


### Input

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

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](https://beepgrid.com/docs/reference/models/#execution)


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

<a id="setrequestblocking"></a>

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


### Input

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

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](https://beepgrid.com/docs/reference/models/#request)


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