Coordinator 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.
Read OSS Coordinator settings and provider availability
Section titled “Read OSS Coordinator settings and provider availability”GET /api/v1/assistance/settings
Read OSS Coordinator settings and provider availability.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
Result and recovery
Section titled “Result and recovery”AssistanceSettings: overseer, version and overseer_configured.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
Response media type: application/json. AssistanceSettings
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/assistance/settings" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Owner-controlled optional assistance
Section titled “Owner-controlled optional assistance”POST /api/v1/assistance/settings
Owner-controlled optional assistance. Enabling requires a configured provider. Coordinator supports automatic dispatch and a separate explicit review flow.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
Content-Type: application/json.
Result and recovery
Section titled “Result and recovery”Updated AssistanceSettings. Provider setup is a separate server configuration.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
Response media type: application/json. AssistanceSettings
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/assistance/settings" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{}'Read-only structured fleet status filtered by current View permission
Section titled “Read-only structured fleet status filtered by current View permission”POST /api/v1/fleet/status
Read-only structured fleet status filtered by current View permission.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
target |
Target | Target kind and stable ID. Choose a new target or an existing conversation, not both. |
Result and recovery
Section titled “Result and recovery”Authorized agents, dependency deadlocks, counts and as_of. Each agent item contains agent, instances and fresh. This is communication/presence evidence, not inferred model execution.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
Response media type: application/json. | Field | Type | Usage |
| — | — | — |
| agents | array of object | At most 100 selected/visible agents. |
| deadlocks | array of object | Currently visible communication cycles. |
| total | integer | Number of included agents. |
| fresh | integer | Number with a connected instance. |
| missing_or_stale | integer | Number without a currently connected instance. |
| as_of | string | Observation time. format=“date-time”. |
| summary | string | Human-readable presence summary. |
| mode | string | read_only. |
| commands_supported | boolean | False; this endpoint does not dispatch work. |
agents fields
Array result.
| Field | Type | Usage |
|---|---|---|
agents[].agent |
Person or Agent or Service | Stable agent external ID when enrolling; an Agent object in a Session response. |
agents[].instances |
array of Instance | Visible runtime observations. |
agents[].fresh |
boolean |
At least one valid runtime is currently connected. |
deadlocks fields
Array result.
| Field | Type | Usage |
|---|---|---|
deadlocks[].dependencies |
array of object |
Explicit blocking-request edges in this cycle. |
deadlocks[].dependencies fields
Array result.
| Field | Type | Usage |
|---|---|---|
deadlocks[].dependencies[].request_id |
string |
Explicitly blocking open request. |
deadlocks[].dependencies[].conversation_id |
string |
Its current authorized history. |
deadlocks[].dependencies[].from |
Person or Agent or Service | The agent that declared this blocking communication dependency. |
deadlocks[].dependencies[].to |
Person or Agent or Service | The individual agent whose reply is blocking the requester. |
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/fleet/status" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{}'Optional overseer
Section titled “Optional overseer”POST /api/v1/fleet/plan
Optional overseer. Acts only as the caller. Outbound messages, questions and tasks require a saved preview and explicit confirmation.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
Content-Type: application/json.
Result and recovery
Section titled “Result and recovery”OverseerPlan; instructions are not dispatched until confirmation where required.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
Response media type: application/json. OverseerPlan
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/fleet/plan" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"prompt":"REPLACE_WITH_PROMPT"}'List Coordinator plans belonging to the authorized caller
Section titled “List Coordinator plans belonging to the authorized caller”GET /api/v1/fleet/plans
List Coordinator plans belonging to the authorized caller.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
Result and recovery
Section titled “Result and recovery”OverseerPlan array.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
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/fleet/plans" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Read a Coordinator plan and its current attributed replies
Section titled “Read a Coordinator plan and its current attributed replies”GET /api/v1/fleet/plans/{id}
Read a Coordinator plan and its current attributed replies.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
| Parameter | Location | Usage |
|---|---|---|
id |
path (required) | Stable identifier returned by the engine. Treat it as opaque. |
Result and recovery
Section titled “Result and recovery”OverseerPlan with dispatches, replies and optional summary.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
Response media type: application/json. OverseerPlan
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/fleet/plans/${id}" \ -H "Authorization: Bearer $BEEPGRID_TOKEN"Read-only summary of currently authorized replies; changed permissions or replies invalidate derived output
Section titled “Read-only summary of currently authorized replies; changed permissions or replies invalidate derived output”POST /api/v1/fleet/plans/{id}/summary
Read-only summary of currently authorized replies; changed permissions or replies invalidate derived output.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
| 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”Updated OverseerPlan with reply_summary or safe summary error.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
Response media type: application/json. OverseerPlan
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/fleet/plans/${id}/summary" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{}'Atomically confirm a server-saved preview under current caller permissions
Section titled “Atomically confirm a server-saved preview under current caller permissions”POST /api/v1/fleet/command
Atomically confirm a server-saved preview under current caller permissions. Idempotent per plan. No free-form targets or instructions accepted.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
Content-Type: application/json.
| Field | Type | Usage |
|---|---|---|
plan_id (required) |
string |
Saved Coordinator plan ID; confirmation accepts this server-owned plan, not arbitrary replacement instructions. |
Result and recovery
Section titled “Result and recovery”OverseerPlan with attributed dispatches. Repeated confirmation does not create duplicate instructions.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
Response media type: application/json. OverseerPlan
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/fleet/command" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"plan_id":"REPLACE_WITH_RETURNED_ID"}'Plan and dispatch distinct ordinary communications under current permissions, then durably collect and summarize settled replies
Section titled “Plan and dispatch distinct ordinary communications under current permissions, then durably collect and summarize settled replies”POST /api/v1/fleet/coordinate
Plan and dispatch distinct ordinary communications under current permissions, then durably collect and summarize settled replies. Idempotent recovery. Does not grant business execution authority. Use /fleet/plan and /fleet/command for explicit review.
Authorization: Authenticated person with current fleet visibility and required contact/assistance permissions. This is available in OSS without the UI.
Content-Type: application/json.
Result and recovery
Section titled “Result and recovery”Automatic OverseerPlan with selected specialists and attributed dispatches, or a status answer.
Disabled/unconfigured assistance or provider failure returns an assistance error. Stale/expired plans, changed scope or revoked access block dispatch. Per-person model calls are rate-limited.
Response media type: application/json. OverseerPlan
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/fleet/coordinate" \ -H "Authorization: Bearer $BEEPGRID_TOKEN" \ -H "Content-Type: application/json" \ --data '{"prompt":"REPLACE_WITH_PROMPT"}'