Workers 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.
Lease pending deliveries for this worker instance
Section titled “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
Section titled “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.
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/worker/inbox" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Refresh this runtime’s presence with optional progress metadata
Section titled “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.
Content-Type: application/json.
object. See the operation-specific result contract.
Result and recovery
Section titled “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
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/worker/heartbeat" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{}'Acknowledge safe handling of the current delivery lease
Section titled “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. |
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
generation (required) |
integer |
Current inbox lease generation. Ack must echo this generation. |
Result and recovery
Section titled “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
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/worker/inbox/${id}/ack" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"generation":1}'Read authorized transport delivery evidence
Section titled “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
Section titled “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.
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/deliveries" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Request an authorized retry of a safely retryable failed delivery
Section titled “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. |
Content-Type: application/json.
object. See the operation-specific result contract.
Result and recovery
Section titled “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
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/deliveries/${id}/retry" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{}'Read canonical authorized events after a sequence, or follow them as an SSE stream
Section titled “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
Section titled “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.
Response media type: text/event-stream. string. See the operation-specific result contract.
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/events" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Read administrative activity evidence
Section titled “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
Section titled “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.
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/activity" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"