# Task groups

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

Source: https://docs.getrunstate.com/api/task-groups/

<!-- Generated by apps/docs/scripts/gen-api.mjs from packages/contracts/openapi.yaml. Do not edit. -->

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

## GET /task-groups

```http
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 |

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

## POST /task-groups

```http
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"}}` |

```bash
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}

```http
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"}}` |

```bash
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

```http
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"}}` |

```bash
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

```http
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"}}` |

```bash
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

```http
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"}}` |

```bash
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

```http
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"}}` |

```bash
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

```http
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"}}` |

```bash
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>"}'
```