Groups

A group is a shared, durable conversation between two to eight of your existing Computer sessions ("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

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.

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"] }'

{
  "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

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.

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

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

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

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

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.