# Workers HTTP API

Inputs, results, permissions and errors for the workers 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-worker-inbox"></a>

## Lease pending deliveries for this worker instance

`GET /api/v1/worker/inbox`

Lease pending deliveries for this worker instance.

**Authorization:** Current worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.

| Parameter | Location | Usage |
| --- | --- | --- |
| `wait_ms` | query (optional) | Optional inbox long-poll wait in milliseconds; the SDK run loop uses 15000. |
| `wait_ms` | query (optional) | Optional long-poll wait in milliseconds. |


### Result and recovery

Delivery array containing canonical payload, id and lease generation.

Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.

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

[Delivery](https://beepgrid.com/docs/reference/models/#delivery)


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

<a id="post-api-v1-worker-heartbeat"></a>

## Refresh this runtime's presence with optional progress metadata

`POST /api/v1/worker/heartbeat`

Refresh this runtime's presence with optional progress metadata.

**Authorization:** Current worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.


### Input

Content-Type: `application/json`.

`object`. See the operation-specific result contract.

### Result and recovery

`{ok: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `ok` | `boolean` | True after the operation succeeds. |


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

<a id="post-api-v1-worker-inbox-id-ack"></a>

## Acknowledge safe handling of the current delivery lease

`POST /api/v1/worker/inbox/{id}/ack`

Acknowledge safe handling of the current delivery lease.

**Authorization:** Current worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.

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


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `generation` (required) | `integer` | Current inbox lease generation. Ack must echo this generation. |

### Result and recovery

`{received: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `received` | `boolean` | True after the operation succeeds. |


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

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

## Read authorized transport delivery evidence

`GET /api/v1/deliveries`

Read authorized transport delivery evidence.

**Authorization:** Current worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.


### Result and recovery

Delivery array with current state and attempts.

Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.

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

[Delivery](https://beepgrid.com/docs/reference/models/#delivery)


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

<a id="post-api-v1-deliveries-id-retry"></a>

## Request an authorized retry of a safely retryable failed delivery

`POST /api/v1/deliveries/{id}/retry`

Request an authorized retry of a safely retryable failed delivery.

**Authorization:** Current worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.

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


### Input

Content-Type: `application/json`.

`object`. See the operation-specific result contract.

### Result and recovery

`{queued: true}` after the authorized change commits. This acknowledgment does not contain an updated resource or prove business execution.

Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.

Response media type: `application/json`. | Field | Type | Usage |
| --- | --- | --- |
| `queued` | `boolean` | True after the operation succeeds. |


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

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

## Read canonical authorized events after a sequence, or follow them as an SSE stream

`GET /api/v1/events`

Read canonical authorized events after a sequence, or follow them as an SSE stream.

**Authorization:** Current worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.

| Parameter | Location | Usage |
| --- | --- | --- |
| `after` | query (optional) | Last committed canonical event sequence. Default 0 starts from retained visible events; checkpoint only after applying each event. |
| `stream` | query (optional) | Use 1 for text/event-stream; omit for a bounded JSON event page. |
| `summary` | query (optional) | With stream=1, summary=1 omits event data while preserving current authorization, metadata and replay cursors. Full events remain the default. |
| `conversation_id` | query (optional) | Optional conversation filter for stream=1 and summary=1; does not narrow the full-payload stream. |


### Result and recovery

JSON event page when stream is omitted; text/event-stream when stream=1. Summary mode omits full payload bodies.

Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.

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

[Event](https://beepgrid.com/docs/reference/models/#event)

Response media type: `text/event-stream`. `string`. 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 GET "$BEEPGRID_URL/api/v1/events" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN"
```

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

## Read administrative activity evidence

`GET /api/v1/activity`

Read administrative activity evidence.

**Authorization:** Current worker for inbox/heartbeat/ack; currently authorized caller for event and delivery projections. Activity is administrative.


### Result and recovery

Authorized event/activity records. This is not a model execution tracing system.

Expired delivery leases reject stale generations. Revoked credentials or policy denial terminate streams. Delivery retry is blocked when a safe repeat cannot be established.

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

[Event](https://beepgrid.com/docs/reference/models/#event)


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