# Subtasks

A project’s checklist: list, add, update and complete.

### soontra_subtasks_list

List a project's subtasks (name, priority, due_date, completed_at, recurrence).

Scope: `read` · Read-only

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string (uuid) | yes |  |

Returns: The project's `subtasks` and their `count`.

- Returns at most 20 subtasks and cannot page.

- Ordered by position in the project.

- `assignee_ids` are included only when the credential also has the `directory` scope.

### soontra_subtasks_bulkComplete

Complete (or un-complete) up to 100 subtasks by id (duplicates are deduped; ids that match nothing come back in not_found). Completing recurring subtasks spawns their next occurrences. Consumes one write token per row (60/min budget, single-call debit capped at 50).

Scope: `write` · Writes

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `subtask_ids` | string (uuid)[] | yes | 1 to 100 items |
| `completed` | boolean | yes |  |
| `idempotency_key` | string | no | Unique key for this logical mutation. Reuse only to retry the exact same payload. 1-128 chars: A-Z a-z 0-9 _ . : - |

Returns: The `updated` count, the `completed` value applied, the changed `subtasks` and any `not_found` ids.

- Up to 100 ids a call; duplicates are removed.

- Each id counts as one write, but one call takes at most 50 from the 60 a minute budget.

### soontra_subtasks_bulkCreate

Create up to 50 subtasks under one project in one call. Consumes one write token per row (60/min budget, single-call debit capped at 50; 1/row of the 500/day workspace budget).

Scope: `write` · Writes

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string (uuid) | yes |  |
| `subtasks` | object[] | yes | 1 to 50 items |
| `subtasks[].name` | string | yes | 1 to 200 characters |
| `subtasks[].description` | string | no | up to 1000 characters |
| `subtasks[].priority` | "urgent" \| "high" \| "medium" \| "low" | no |  |
| `subtasks[].due_date` | string \| null | no |  |
| `subtasks[].assignee_ids` | string (uuid)[] | no | up to 20 items |
| `idempotency_key` | string | no | Unique key for this logical mutation. Reuse only to retry the exact same payload. 1-128 chars: A-Z a-z 0-9 _ . : - |

Returns: The `created` count and the new `subtasks`.

- Up to 50 subtasks a call, all under one project.

- Each subtask counts as one write against the rate limits.

- Rows take no `recurrence`; use `subtasks.create` for a repeating subtask.

### soontra_subtasks_create

Add a subtask to a project (recurrence optional - same rule shape as projects; it respawns when completed). Writes are drafts-only: nothing is ever published, scheduled, or deleted by this tool.

Scope: `write` · Writes

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string (uuid) | yes |  |
| `name` | string | yes | 1 to 200 characters |
| `description` | string | no | up to 1000 characters |
| `priority` | "urgent" \| "high" \| "medium" \| "low" | no |  |
| `due_date` | string \| null | no |  |
| `assignee_ids` | string (uuid)[] | no | up to 20 items |
| `recurrence` | object \| null | no |  |
| `recurrence.v` | 1 | yes |  |
| `recurrence.freq` | "daily" | yes |  |
| `recurrence.interval` | integer | yes | 1 to 365 |
| `idempotency_key` | string | no | Unique key for this logical mutation. Reuse only to retry the exact same payload. 1-128 chars: A-Z a-z 0-9 _ . : - |

Returns: The new `subtask` with `id`, `name`, `priority`, `due_date`, `completed_at` and `recurrence`.

- `name` is up to 200 characters and `description` up to 1,000.

- Up to 20 assignees.

### soontra_subtasks_update

Update or complete a subtask (set completed for done; recurrence: null stops the repeat). Completing a recurring subtask auto-creates the next occurrence.

Scope: `write` · Writes

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `project_id` | string (uuid) | yes |  |
| `subtask_id` | string (uuid) | yes |  |
| `name` | string | no | 1 to 200 characters |
| `description` | string \| null | no |  |
| `priority` | "urgent" \| "high" \| "medium" \| "low" | no |  |
| `due_date` | string \| null | no |  |
| `assignee_ids` | string (uuid)[] | no | up to 20 items |
| `completed` | boolean | no |  |
| `recurrence` | object \| null | no |  |
| `recurrence.v` | 1 | yes |  |
| `recurrence.freq` | "daily" | yes |  |
| `recurrence.interval` | integer | yes | 1 to 365 |
| `idempotency_key` | string | no | Unique key for this logical mutation. Reuse only to retry the exact same payload. 1-128 chars: A-Z a-z 0-9 _ . : - |

Returns: The updated `subtask`.

- Pass at least one field besides `project_id` and `subtask_id`.

- `completed: true` marks it done and `completed: false` reopens it.

- `description`, `due_date` and `recurrence` accept `null` to clear them.