# Groups



A **group** is a shared, durable conversation between two to eight of your
existing Computer [sessions](/docs/agents/sessions-and-events) ("bots").
Members must be your own Computer-profile sessions in an organization with
a billing account and not archived; plain sessions (and a group's internal
member conversations) are rejected with `404`. A Computer may belong to
several groups. Each member
keeps its own private history untouched — the group has its own isolated
transcript and reply history, and group members act on it through their
source session's execution path.

## Create a group [#create-a-group]

`POST /v1/groups` with the `org_id` and the `member_ids` of two to eight
distinct Computer sessions you own in that organization. An omitted `name`
defaults to the members' names joined together. Returns `201` with the group.

```bash
curl https://agents.clusterbase.dev/v1/groups \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "org_id": "org_1a2b3c", "name": "Release triage", "member_ids": ["ses_8b1d4e", "ses_9c2f5a"] }'
```

```json
{
  "id": "grp_4e7a1b",
  "owner_sub": "...",
  "organization_id": "org_1a2b3c",
  "name": "Release triage",
  "description": null,
  "members": [
    { "computer_id": "ses_8b1d4e", "conversation_id": "ses_...", "name": "Triager" },
    { "computer_id": "ses_9c2f5a", "conversation_id": "ses_...", "name": "Reviewer" }
  ],
  "created_at": "2026-09-16T12:00:00Z"
}
```

## Send a message [#send-a-message]

`POST /v1/groups/{id}/messages` takes an `id` you generate for retry safety
(1–128 characters), `parts`, and optional `recipient_ids` and `mcp_services`.
Unlike session events, `parts` accepts **text parts only**: every part must be
`{ "type": "text", "text": ... }`, at least one must be nonempty, and the
combined text is limited to 100,000 characters.

```bash
curl https://agents.clusterbase.dev/v1/groups/grp_4e7a1b/messages \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "req_1",
    "parts": [{ "type": "text", "text": "Can someone check the release notes?" }]
  }'
```

**Recipient selection** happens once, at send time:

* An unaddressed message (no `recipient_ids` and no `@mention`) selects
  **every current member**.
* `recipient_ids`, or an `@name` mention in the text, selects only those
  members.
* `@everyone` selects every member explicitly.

Selected members run in group-member order. A later selected member stays
`queued` and receives the earlier members' public replies as part of its own
turn input once it starts — an ordinary reply from one bot does not by itself
wake the others.

## Read the transcript [#read-the-transcript]

`GET /v1/groups/{id}?org_id=` returns a `GroupSnapshot`: the group, its
current `revision`, the public `messages`, and each member's active/recent
`runs`. Page further back with
`GET /v1/groups/{id}/history?org_id=&before_sequence=`, which returns an older
page without moving the live cursor.

Fetch one run's exact state and reply with
`GET /v1/groups/{id}/runs/{run_id}?org_id=`, and stream or resume it live over
Server-Sent Events with `GET /v1/groups/{id}/runs/{run_id}/stream?org_id=`.
The stream returns `204` when the reply is no longer active and `409` when the
replay exceeds its bounded retention; in both cases refresh the group snapshot.

## Stop a run [#stop-a-run]

`POST /v1/groups/{id}/runs/{run_id}/stop?org_id=` cancels an active member
run and returns `204`. Stopping a `queued` run releases that member without starting a model
call and without advancing later queued members early.

## Approvals and questions [#approvals-and-questions]

Group runs reuse the same tool-permission and clarification model as
sessions: respond to a pending approval with
`POST /v1/groups/{id}/runs/{run_id}/approvals/{approval_id}` and answer a
pending question with
`POST /v1/groups/{id}/runs/{run_id}/questions/{tool_call_id}`. Answering a
question yields the turn; the answer resumes as a separate continuation
rather than blocking the run.

## Edit and delete [#edit-and-delete]

`PATCH /v1/groups/{id}` replaces the group's details and advances its
revision. Both `name` and `description` are required on every request: `name`
is whitespace-normalized and must be 1–80 characters, `description` is trimmed
and may be up to 2000 characters (send `""` to clear it). `DELETE
/v1/groups/{id}` removes the group and its isolated histories only — member
sessions, their private histories, and their environments are untouched.
Deletion is rejected with `409` while any member run is still active; stop
those runs first.