Task groups

Collective completion: decide once when N results are accepted, the first is accepted, or all members finish.

All paths are relative to the API base URL (https://api.getrunstate.com) and require Authorization: Bearer <api key>. See the API overview for authentication, idempotency and the error envelope.

GET /task-groups

GET /v1/spaces/{spaceId}/task-groups

Read-only group list.

Key permission: coordination_read

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Responses

Status	Meaning
`200`	Groups

curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/task-groups" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"

POST /task-groups

POST /v1/spaces/{spaceId}/task-groups

Open a collective-completion group with its own gate scope.

Key permission: coordination_write
Idempotency-Key header: required
TypeScript SDK: run.groups.create()
Python SDK: run.groups.create()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`parentScopeId`	string (uuid)	no
`mailboxId`	string (uuid)	yes
`condition`	string	yes	one of `FIRST_ACCEPTED`, `N_ACCEPTED`, `ALL_TERMINAL`
`threshold`	integer	no	min 1
`deadline`	string (date-time)	no

Responses

Status	Meaning
`201`	groupId and gate scopeId
`409`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/task-groups" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mailboxId":"<mailboxId>","condition":"FIRST_ACCEPTED"}'

GET /task-groups/{id}

GET /v1/spaces/{spaceId}/task-groups/{id}

Group state, outcome, and member verdicts.

Key permission: coordination_read
TypeScript SDK: group.status(), group.wait()
Python SDK: group.status(), group.wait()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Responses

Status	Meaning
`200`	Group view
`404`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X GET "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/task-groups/<id>" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY"

POST /task-groups/{id}/tasks

POST /v1/spaces/{spaceId}/task-groups/{id}/tasks

Submit a member task delivered through the group mailbox.

Key permission: coordination_write
Idempotency-Key header: required
TypeScript SDK: group.submit()
Python SDK: group.submit()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`taskKey`	string	yes	length 1–512
`input`	any JSON	no
`deadline`	string (date-time)	no

Responses

Status	Meaning
`201`	Member task created
`409`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/task-groups/<id>/tasks" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"taskKey":"<taskKey>"}'

POST /task-groups/{id}/seal

POST /v1/spaces/{spaceId}/task-groups/{id}/seal

Close group membership; ALL_TERMINAL evaluates only after seal.

Key permission: coordination_write
TypeScript SDK: group.seal()
Python SDK: group.seal()

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Responses

Status	Meaning
`200`	SEALED
`409`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/task-groups/<id>/seal" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST /task-groups/{id}/tasks/{taskId}/accept

POST /v1/spaces/{spaceId}/task-groups/{id}/tasks/{taskId}/accept

Idempotent accept verdict; requires member task SUCCEEDED.

Key permission: coordination_write
TypeScript SDK: group.accept(taskId)
Python SDK: group.accept(task_id)

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required
`taskId`	string (uuid)	required

Responses

Status	Meaning
`200`	Verdict and group state
`409`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/task-groups/<id>/tasks/<taskId>/accept" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST /task-groups/{id}/tasks/{taskId}/reject

POST /v1/spaces/{spaceId}/task-groups/{id}/tasks/{taskId}/reject

Idempotent reject verdict; requires member task terminal.

Key permission: coordination_write
TypeScript SDK: group.reject(taskId)
Python SDK: group.reject(task_id)

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required
`taskId`	string (uuid)	required

Responses

Status	Meaning
`200`	Verdict and group state
`409`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/task-groups/<id>/tasks/<taskId>/reject" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

POST /task-groups/{id}/join-task

POST /v1/spaces/{spaceId}/task-groups/{id}/join-task

Join an outside joinable task to an OPEN group.

Key permission: coordination_write
TypeScript SDK: group.joinTask(taskId)
Python SDK: group.join_task(task_id)

Path parameters

Name	Type	Notes
`spaceId`	string (uuid)	required
`id`	string (uuid)	required

Request body (JSON)

Field	Type	Required	Notes
`taskId`	string (uuid)	yes

Responses

Status	Meaning
`200`	Group state
`409`	Error envelope `{"error":{"code","message","requestId"}}`

curl -X POST "$RUNSTATE_BASE_URL/v1/spaces/$RUNSTATE_SPACE_ID/task-groups/<id>/join-task" \
  -H "Authorization: Bearer $RUNSTATE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"taskId":"<taskId>"}'