# Coordinator HTTP API

Inputs, results, permissions and errors for the coordinator 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-assistance-settings"></a>

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

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


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

<a id="post-api-v1-assistance-settings"></a>

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


### Input

Content-Type: `application/json`.

[AssistanceUpdate](https://beepgrid.com/docs/reference/models/#assistanceupdate)

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


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

<a id="post-api-v1-fleet-status"></a>

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


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `target` | [Target](https://beepgrid.com/docs/reference/models/#target) | Target kind and stable ID. Choose a new target or an existing conversation, not both. |

### 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](https://beepgrid.com/docs/reference/models/#person) or [Agent](https://beepgrid.com/docs/reference/models/#agent) or [Service](https://beepgrid.com/docs/reference/models/#service) | Stable agent external ID when enrolling; an Agent object in a Session response. |
| `agents[].instances` | array of [Instance](https://beepgrid.com/docs/reference/models/#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](https://beepgrid.com/docs/reference/models/#person) or [Agent](https://beepgrid.com/docs/reference/models/#agent) or [Service](https://beepgrid.com/docs/reference/models/#service) | The agent that declared this blocking communication dependency. |
| `deadlocks[].dependencies[].to` | [Person](https://beepgrid.com/docs/reference/models/#person) or [Agent](https://beepgrid.com/docs/reference/models/#agent) or [Service](https://beepgrid.com/docs/reference/models/#service) | The individual agent whose reply is blocking the requester. |


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

<a id="post-api-v1-fleet-plan"></a>

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


### Input

Content-Type: `application/json`.

[OverseerInput](https://beepgrid.com/docs/reference/models/#overseerinput)

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


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

<a id="get-api-v1-fleet-plans"></a>

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

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.

[OverseerPlan](https://beepgrid.com/docs/reference/models/#overseerplan)


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

<a id="get-api-v1-fleet-plans-id"></a>

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

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


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

<a id="post-api-v1-fleet-plans-id-summary"></a>

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


### Input

Content-Type: `application/json`.

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

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


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

<a id="post-api-v1-fleet-command"></a>

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


### Input

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

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


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

<a id="coordinate"></a>

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


### Input

Content-Type: `application/json`.

[OverseerInput](https://beepgrid.com/docs/reference/models/#overseerinput)

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


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