@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/tasks.md

@@ -0,0 +1,1344 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.tasks`: Tasks
+
+25 operations (8 read, 12 write, 4 destructive, 1 billable).
+
+5 of these also have a hand-written method (`g8.tasks`), marked **★** below. Prefer the hand-written method when one exists: it unwraps the `data` envelope and takes friendlier arguments. See [../sdk-clients.md](../sdk-clients.md).
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [tasks.d.ts](tasks.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`assignTaskExecutor`](#op-assigntaskexecutor) | `PUT /api/v1/tasks/{task_id}/assignment` | write | `tasks:write` | Assign Task Executor |
+| [`createGlobalTask`](#op-createglobaltask) | `POST /api/v1/tasks` | write | `tasks:write` | Create Global Task |
+| [`createSubtask`](#op-createsubtask) | `POST /api/v1/tasks/{task_id}/subtasks` | write | `tasks:write` | Create Subtask |
+| [`createTask`](#op-createtask) ★ | `POST /api/v1/contacts/{contact_id}/tasks` | write | `tasks:write` | Create Task |
+| [`createTaskCopies`](#op-createtaskcopies) | `POST /api/v1/tasks/{task_id}/copies` | write | `tasks:write` | Create Task Copies |
+| [`createTaskReply`](#op-createtaskreply) | `POST /api/v1/tasks/{task_id}/replies` | write | `tasks:write` | Create Task Reply |
+| [`deleteSubtask`](#op-deletesubtask) | `DELETE /api/v1/tasks/{task_id}/subtasks/{subtask_id}` | destructive | `tasks:delete` | Delete Subtask |
+| [`deleteTask`](#op-deletetask) ★ | `DELETE /api/v1/tasks/{task_id}` | destructive | `tasks:delete` | Delete Task |
+| [`deleteTaskReply`](#op-deletetaskreply) | `DELETE /api/v1/tasks/replies/{reply_id}` | destructive | `tasks:delete` | Delete Task Reply |
+| [`getTask`](#op-gettask) | `GET /api/v1/tasks/{task_id}` | read | `tasks:read` | Get Task |
+| [`getTaskRecord`](#op-gettaskrecord) | `GET /api/v1/tasks/records/{entity_type}/{entity_id}` | read | `tasks:read` | Get Task Record |
+| [`getTaskSettings`](#op-gettasksettings) | `GET /api/v1/tasks/settings` | read | `tasks:read` | Get Task Settings |
+| [`listAllTasks`](#op-listalltasks) ★ | `GET /api/v1/tasks` | read | `tasks:read` | List All Tasks |
+| [`listContactTasks`](#op-listcontacttasks) ★ | `GET /api/v1/contacts/{contact_id}/tasks` | read | `tasks:read` | List Contact Tasks |
+| [`listSubtasks`](#op-listsubtasks) | `GET /api/v1/tasks/{task_id}/subtasks` | read | `tasks:read` | List Subtasks |
+| [`listTaskReplies`](#op-listtaskreplies) | `GET /api/v1/tasks/{task_id}/replies` | read | `tasks:read` | List Task Replies |
+| [`reopenTaskThread`](#op-reopentaskthread) | `DELETE /api/v1/tasks/{task_id}/resolve` | destructive | `tasks:delete` | Reopen Task Thread |
+| [`resolveTaskThread`](#op-resolvetaskthread) | `POST /api/v1/tasks/{task_id}/resolve` | write | `tasks:write` | Resolve Task Thread |
+| [`snoozeTaskReminder`](#op-snoozetaskreminder) | `POST /api/v1/tasks/{task_id}/snooze` | write | `tasks:write` | Snooze Task Reminder |
+| [`startTaskExecution`](#op-starttaskexecution) | `POST /api/v1/tasks/{task_id}/start` | billable | `tasks:run` | Start Task Execution |
+| [`taskExecutionHistory`](#op-taskexecutionhistory) | `GET /api/v1/tasks/{task_id}/execution` | read | `tasks:read` | Task Execution History |
+| [`updateSubtask`](#op-updatesubtask) | `PUT /api/v1/tasks/{task_id}/subtasks/{subtask_id}` | write | `tasks:write` | Update Subtask |
+| [`updateTask`](#op-updatetask) ★ | `PATCH /api/v1/tasks/{task_id}` | write | `tasks:write` | Update Task |
+| [`updateTaskReply`](#op-updatetaskreply) | `PUT /api/v1/tasks/replies/{reply_id}` | write | `tasks:write` | Update Task Reply |
+| [`updateTaskSettings`](#op-updatetasksettings) | `PUT /api/v1/tasks/settings` | write | `tasks:write` | Update Task Settings |
+
+---
+
+<a id="op-assigntaskexecutor"></a>
+
+### `g8.api.tasks.assignTaskExecutor(input)`
+
+**Assign Task Executor**
+
+- HTTP: `PUT /api/v1/tasks/{task_id}/assignment`
+- operationId: `assign_task_executor_tasks__task_id__assignment_put` (also callable as `g8.api.call("assign_task_executor_tasks__task_id__assignment_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string (uuid)` | yes |  |
+| `body` | `TaskAssignmentRequest` | yes | Request body; fields below. |
+
+Body fields (`TaskAssignmentRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.expected_updated_at` | `string (date-time)` | yes |  |
+| `body.agent_id` | `string (uuid) \| null` | no |  |
+
+**Returns** `ApiResponse_TaskAssignmentResult_`: the envelope `{ data: TaskAssignmentResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskAssignmentResult` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `assigned` | `boolean` | yes |  |
+| `execution_started` | `boolean` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.assignTaskExecutor({
+  path: { task_id: "00000000-0000-0000-0000-000000000000" },
+  body: { expected_updated_at: "2026-01-01T09:00:00Z" },
+});
+```
+
+---
+
+<a id="op-createglobaltask"></a>
+
+### `g8.api.tasks.createGlobalTask(input)`
+
+**Create Global Task**
+
+- HTTP: `POST /api/v1/tasks`
+- operationId: `create_global_task_tasks_post` (also callable as `g8.api.call("create_global_task_tasks_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `TaskCreateRequest` | yes | Request body; fields below. |
+| `headers.idempotency-key` | `string (uuid) \| null` | no |  |
+
+Body fields (`TaskCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | Task title |
+| `body.assignee_id` | `string \| null` | no | User ID to assign the task to |
+| `body.description` | `string \| null` | no | Task description |
+| `body.due_date` | `string \| null` | no | Due date (ISO 8601) |
+| `body.entity_id` | `string \| null` | no |  |
+| `body.entity_type` | `string \| null` | no |  |
+| `body.parent_task_id` | `string \| null` | no | Parent task UUID. When set, this task is inserted as a subtask of the parent. Subtasks cannot themselves have subtasks (one level deep). |
+| `body.priority` | `integer \| null` | no | Priority (0=none, 1=high, 2=medium, 3=low; historical 4=low is preserved) min 0, max 4 |
+| `body.records` | `Array<Record<string, string>> \| null` | no | Optional related records: contact, company, deal, lead, application, team_member, or campaign (Studio). An empty list leaves the task standalone. |
+| `body.source_url` | `string \| null` | no | max length 2048 |
+| `body.subtask_sort_order` | `integer \| null` | no | Sort position within the parent's subtasks. When omitted on a subtask create, the handler appends to the end. |
+| `body.tags` | `Array<string> \| null` | no | max items 20 |
+| `body.task_type` | `string \| null` | no | Activity type, such as call or meeting |
+
+**Returns** `ApiResponse_TaskResponse_`: the envelope `{ data: TaskResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `assignee_id` | `string \| null` | no |  |
+| `assignee_name` | `string \| null` | no |  |
+| `completed_subtask_count` | `integer \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `due_date` | `string \| null` | no |  |
+| `entity_id` | `string \| null` | no |  |
+| `entity_label` | `string \| null` | no |  |
+| `entity_type` | `string \| null` | no |  |
+| `execution_id` | `string \| null` | no |  |
+| `executor_agent_id` | `string \| null` | no |  |
+| `executor_agent_name` | `string \| null` | no |  |
+| `executor_type` | `"human" \| "agent"` | no | default `"human"` |
+| `links` | `Array<Record<string, unknown>>` | no |  |
+| `parent_task_id` | `string \| null` | no |  |
+| `priority` | `integer \| null` | no |  |
+| `reminder_at` | `string \| null` | no |  |
+| `reminder_sent_at` | `string \| null` | no |  |
+| `source_external_id` | `string \| null` | no |  |
+| `source_meeting_id` | `integer \| null` | no |  |
+| `source_meeting_start_time` | `string \| null` | no |  |
+| `source_meeting_title` | `string \| null` | no |  |
+| `source_transcript_id` | `string \| null` | no |  |
+| `source_url` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subtask_count` | `integer \| null` | no |  |
+| `subtask_sort_order` | `integer \| null` | no |  |
+| `tags` | `Array<string>` | no |  |
+| `task_type` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+| `visibility` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.createGlobalTask({ body: { title: "Example" } });
+```
+
+---
+
+<a id="op-createsubtask"></a>
+
+### `g8.api.tasks.createSubtask(input)`
+
+**Create Subtask**
+
+- HTTP: `POST /api/v1/tasks/{task_id}/subtasks`
+- operationId: `create_subtask_tasks__task_id__subtasks_post` (also callable as `g8.api.call("create_subtask_tasks__task_id__subtasks_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+Create a subtask under this task.
+
+`entity_type` / `entity_id` name the RECORD the subtask hangs off and are
+required - the parent supplies the hierarchy, not the record link. That
+record is authorised against the caller's contact, company and deal
+scopes, so a subtask cannot be attached to something the key cannot see.
+
+`parent_task_id` in the body is ignored: the parent is the task in the
+path.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Parent task id (UUID). |
+| `body` | `SubtaskCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`SubtaskCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.entity_id` | `string` | yes | Record id. |
+| `body.entity_type` | `string` | yes | Record type: contact \| company \| deal. |
+| `body.title` | `string` | yes | Subtask title. |
+| `body.assignee_id` | `string \| null` | no | Assignee id. |
+| `body.assignee_name` | `string \| null` | no | Assignee display name. |
+| `body.description` | `string \| null` | no | Free-text body. |
+| `body.due_date` | `string \| null` | no | ISO 8601 due date. |
+| `body.parent_task_id` | `string \| null` | no | Ignored - the parent is the task in the path. Present for parity. |
+| `body.priority` | `integer \| null` | no | Priority. |
+| `body.records` | `Array<Record<string, unknown>> \| null` | no | Additional `{entity_type, entity_id}` records to link. When set, the FIRST entry becomes the primary record. |
+| `body.reminder_at` | `string \| null` | no | ISO 8601 UTC reminder time. Omit for no reminder. |
+| `body.source_url` | `string \| null` | no | Page the subtask was raised from. max length 2048 |
+| `body.subtask_sort_order` | `integer \| null` | no | Position among sibling subtasks. |
+| `body.tags` | `Array<string> \| null` | no | Labels (max 20). max items 20 |
+| `body.task_type` | `string \| null` | no | Task type. |
+| `body.visibility` | `string \| null` | no | public \| team \| private. Omit for the org default. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.createSubtask({
+  path: { task_id: "id" },
+  body: { entity_id: "id", entity_type: "example", title: "Example" },
+});
+```
+
+---
+
+<a id="op-createtask"></a>
+
+### `g8.api.tasks.createTask(input)`
+
+**Create Task**
+
+- HTTP: `POST /api/v1/contacts/{contact_id}/tasks`
+- operationId: `create_task_contacts__contact_id__tasks_post` (also callable as `g8.api.call("create_task_contacts__contact_id__tasks_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+- ★ Hand-written: [`g8.tasks.create()`](../sdk-clients.md#g8-tasks-create)
+
+Create a task on a contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact ID |
+| `body` | `TaskCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`TaskCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.title` | `string` | yes | Task title |
+| `body.assignee_id` | `string \| null` | no | User ID to assign the task to |
+| `body.description` | `string \| null` | no | Task description |
+| `body.due_date` | `string \| null` | no | Due date (ISO 8601) |
+| `body.entity_id` | `string \| null` | no |  |
+| `body.entity_type` | `string \| null` | no |  |
+| `body.parent_task_id` | `string \| null` | no | Parent task UUID. When set, this task is inserted as a subtask of the parent. Subtasks cannot themselves have subtasks (one level deep). |
+| `body.priority` | `integer \| null` | no | Priority (0=none, 1=high, 2=medium, 3=low; historical 4=low is preserved) min 0, max 4 |
+| `body.records` | `Array<Record<string, string>> \| null` | no | Optional related records: contact, company, deal, lead, application, team_member, or campaign (Studio). An empty list leaves the task standalone. |
+| `body.source_url` | `string \| null` | no | max length 2048 |
+| `body.subtask_sort_order` | `integer \| null` | no | Sort position within the parent's subtasks. When omitted on a subtask create, the handler appends to the end. |
+| `body.tags` | `Array<string> \| null` | no | max items 20 |
+| `body.task_type` | `string \| null` | no | Activity type, such as call or meeting |
+
+**Returns** `ApiResponse_TaskResponse_`: the envelope `{ data: TaskResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `assignee_id` | `string \| null` | no |  |
+| `assignee_name` | `string \| null` | no |  |
+| `completed_subtask_count` | `integer \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `due_date` | `string \| null` | no |  |
+| `entity_id` | `string \| null` | no |  |
+| `entity_label` | `string \| null` | no |  |
+| `entity_type` | `string \| null` | no |  |
+| `execution_id` | `string \| null` | no |  |
+| `executor_agent_id` | `string \| null` | no |  |
+| `executor_agent_name` | `string \| null` | no |  |
+| `executor_type` | `"human" \| "agent"` | no | default `"human"` |
+| `links` | `Array<Record<string, unknown>>` | no |  |
+| `parent_task_id` | `string \| null` | no |  |
+| `priority` | `integer \| null` | no |  |
+| `reminder_at` | `string \| null` | no |  |
+| `reminder_sent_at` | `string \| null` | no |  |
+| `source_external_id` | `string \| null` | no |  |
+| `source_meeting_id` | `integer \| null` | no |  |
+| `source_meeting_start_time` | `string \| null` | no |  |
+| `source_meeting_title` | `string \| null` | no |  |
+| `source_transcript_id` | `string \| null` | no |  |
+| `source_url` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subtask_count` | `integer \| null` | no |  |
+| `subtask_sort_order` | `integer \| null` | no |  |
+| `tags` | `Array<string>` | no |  |
+| `task_type` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+| `visibility` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.createTask({ path: { contact_id: 123 }, body: { title: "Example" } });
+```
+
+---
+
+<a id="op-createtaskcopies"></a>
+
+### `g8.api.tasks.createTaskCopies(input)`
+
+**Create Task Copies**
+
+- HTTP: `POST /api/v1/tasks/{task_id}/copies`
+- operationId: `create_task_copies_tasks__task_id__copies_post` (also callable as `g8.api.call("create_task_copies_tasks__task_id__copies_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string (uuid)` | yes |  |
+| `body` | `TaskCopyRequest` | yes | Request body; fields below. |
+
+Body fields (`TaskCopyRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.assignee_ids` | `Array<string (uuid)>` | yes | min items 1, max items 20 |
+| `body.expected_updated_at` | `string (date-time)` | yes |  |
+| `body.request_id` | `string (uuid)` | yes |  |
+
+**Returns** `unknown`.
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.createTaskCopies({
+  path: { task_id: "00000000-0000-0000-0000-000000000000" },
+  body: {
+    assignee_ids: ["00000000-0000-0000-0000-000000000000"],
+    expected_updated_at: "2026-01-01T09:00:00Z",
+    request_id: "00000000-0000-0000-0000-000000000000",
+  },
+});
+```
+
+---
+
+<a id="op-createtaskreply"></a>
+
+### `g8.api.tasks.createTaskReply(input)`
+
+**Create Task Reply**
+
+- HTTP: `POST /api/v1/tasks/{task_id}/replies`
+- operationId: `create_task_reply_tasks__task_id__replies_post` (also callable as `g8.api.call("create_task_reply_tasks__task_id__replies_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+Post a reply on this task's thread. INTERNAL to your organisation.
+
+Nothing here reaches a customer. `mentioned_user_ids` notifies those
+people inside graph8 - it does not email anyone outside it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task id (UUID). |
+| `body` | `TaskReplyCreateRequest` | yes | Request body; fields below. |
+
+Body fields (`TaskReplyCreateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | Reply text. |
+| `body.author_avatar_url` | `string \| null` | no | Avatar to show beside the reply. |
+| `body.mentioned_user_ids` | `Array<string>` | no | Users to notify. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.createTaskReply({ path: { task_id: "id" }, body: { body: "example" } });
+```
+
+---
+
+<a id="op-deletesubtask"></a>
+
+### `g8.api.tasks.deleteSubtask(input)`
+
+**Delete Subtask**
+
+- HTTP: `DELETE /api/v1/tasks/{task_id}/subtasks/{subtask_id}`
+- operationId: `delete_subtask_tasks__task_id__subtasks__subtask_id__delete` (also callable as `g8.api.call("delete_subtask_tasks__task_id__subtasks__subtask_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `tasks:delete`
+
+Delete one subtask. The parent and its siblings are untouched.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Parent task id (UUID). |
+| `path.subtask_id` | `string` | yes | Subtask id (UUID). |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.tasks.deleteSubtask({ path: { task_id: "id", subtask_id: "id" } });
+```
+
+---
+
+<a id="op-deletetask"></a>
+
+### `g8.api.tasks.deleteTask(input)`
+
+**Delete Task**
+
+- HTTP: `DELETE /api/v1/tasks/{task_id}`
+- operationId: `delete_task_tasks__task_id__delete` (also callable as `g8.api.call("delete_task_tasks__task_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `tasks:delete`
+- ★ Hand-written: [`g8.tasks.delete()`](../sdk-clients.md#g8-tasks-delete)
+
+Delete a task.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task ID |
+
+**Returns** `ApiResponse_dict_`: the envelope `{ data: Record<string, unknown>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.tasks.deleteTask({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-deletetaskreply"></a>
+
+### `g8.api.tasks.deleteTaskReply(input)`
+
+**Delete Task Reply**
+
+- HTTP: `DELETE /api/v1/tasks/replies/{reply_id}`
+- operationId: `delete_task_reply_tasks_replies__reply_id__delete` (also callable as `g8.api.call("delete_task_reply_tasks_replies__reply_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `tasks:delete`
+
+Delete a reply. AUTHOR ONLY. The rest of the thread stays.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Reply id (UUID). |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.tasks.deleteTaskReply({ path: { reply_id: "id" } });
+```
+
+---
+
+<a id="op-gettask"></a>
+
+### `g8.api.tasks.getTask(input)`
+
+**Get Task**
+
+- HTTP: `GET /api/v1/tasks/{task_id}`
+- operationId: `get_task_tasks__task_id__get` (also callable as `g8.api.call("get_task_tasks__task_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `tasks:read`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes |  |
+
+**Returns** `ApiResponse_TaskResponse_`: the envelope `{ data: TaskResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `assignee_id` | `string \| null` | no |  |
+| `assignee_name` | `string \| null` | no |  |
+| `completed_subtask_count` | `integer \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `due_date` | `string \| null` | no |  |
+| `entity_id` | `string \| null` | no |  |
+| `entity_label` | `string \| null` | no |  |
+| `entity_type` | `string \| null` | no |  |
+| `execution_id` | `string \| null` | no |  |
+| `executor_agent_id` | `string \| null` | no |  |
+| `executor_agent_name` | `string \| null` | no |  |
+| `executor_type` | `"human" \| "agent"` | no | default `"human"` |
+| `links` | `Array<Record<string, unknown>>` | no |  |
+| `parent_task_id` | `string \| null` | no |  |
+| `priority` | `integer \| null` | no |  |
+| `reminder_at` | `string \| null` | no |  |
+| `reminder_sent_at` | `string \| null` | no |  |
+| `source_external_id` | `string \| null` | no |  |
+| `source_meeting_id` | `integer \| null` | no |  |
+| `source_meeting_start_time` | `string \| null` | no |  |
+| `source_meeting_title` | `string \| null` | no |  |
+| `source_transcript_id` | `string \| null` | no |  |
+| `source_url` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subtask_count` | `integer \| null` | no |  |
+| `subtask_sort_order` | `integer \| null` | no |  |
+| `tags` | `Array<string>` | no |  |
+| `task_type` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+| `visibility` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.getTask({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-gettaskrecord"></a>
+
+### `g8.api.tasks.getTaskRecord(input)`
+
+**Get Task Record**
+
+- HTTP: `GET /api/v1/tasks/records/{entity_type}/{entity_id}`
+- operationId: `get_task_record_tasks_records__entity_type___entity_id__get` (also callable as `g8.api.call("get_task_record_tasks_records__entity_type___entity_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `tasks:read`
+
+Resolve the record a task points at to its display name and link.
+
+404 when the record does not exist or the key cannot see it. The task
+scope resolved for an API key carries no `record_scopes`, so the key's
+own resource grants (`get_task_record_scopes`, the same resolver
+`GET /tasks/{task_id}` uses) are attached before the lookup.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.entity_type` | `string` | yes | Record type, e.g. `contact`, `company`, `deal`. |
+| `path.entity_id` | `string` | yes | Record id. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.getTaskRecord({ path: { entity_type: "example", entity_id: "id" } });
+```
+
+---
+
+<a id="op-gettasksettings"></a>
+
+### `g8.api.tasks.getTaskSettings(input?)`
+
+**Get Task Settings**
+
+- HTTP: `GET /api/v1/tasks/settings`
+- operationId: `get_task_settings_tasks_settings_get` (also callable as `g8.api.call("get_task_settings_tasks_settings_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `tasks:read`
+
+The org's task settings: default visibility, mentions, and how a parent
+task completes relative to its subtasks.
+
+**Input**: none.
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.getTaskSettings();
+```
+
+---
+
+<a id="op-listalltasks"></a>
+
+### `g8.api.tasks.listAllTasks(input?)`
+
+**List All Tasks**
+
+- HTTP: `GET /api/v1/tasks`
+- operationId: `list_all_tasks_tasks_get` (also callable as `g8.api.call("list_all_tasks_tasks_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `tasks:read`
+- ★ Hand-written: [`g8.tasks.list()`](../sdk-clients.md#g8-tasks-list)
+
+List all tasks org-wide with optional filters.
+
+The backend list is unpaginated; ``limit``/``offset`` bound the response
+here (same approach as the MCP ``g8_get_tasks`` tool) so an org with many
+tasks can't return an unbounded payload. Ordering is deterministic
+(``due_date`` asc nulls-last, then ``created_at`` desc), so paging is stable.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `string \| null` | no | Filter by status (open, completed) |
+| `query.priority` | `integer \| null` | no | Filter by priority |
+| `query.assignee_id` | `string \| null` | no | Filter by assignee user ID |
+| `query.created_by` | `string \| null` | no | Filter by creator (email or user ID) |
+| `query.task_type` | `string \| null` | no | Filter by task type (call, email, meeting, ...) |
+| `query.entity_type` | `string \| null` | no | Filter by linked entity type (contact, company, deal, team_member) |
+| `query.entity_id` | `string \| null` | no | Filter by linked entity ID (pair with entity_type) |
+| `query.source_meeting_id` | `integer \| null` | no | Filter to tasks from a specific meeting |
+| `query.search` | `string \| null` | no | Search by task title |
+| `query.limit` | `integer` | no | Max tasks to return (default 100, max 200) default `100` |
+| `query.offset` | `integer` | no | Number of tasks to skip default `0` |
+
+**Returns** `ApiResponse_list_TaskResponse__`: the envelope `{ data: Array<TaskResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `assignee_id` | `string \| null` | no |  |
+| `assignee_name` | `string \| null` | no |  |
+| `completed_subtask_count` | `integer \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `due_date` | `string \| null` | no |  |
+| `entity_id` | `string \| null` | no |  |
+| `entity_label` | `string \| null` | no |  |
+| `entity_type` | `string \| null` | no |  |
+| `execution_id` | `string \| null` | no |  |
+| `executor_agent_id` | `string \| null` | no |  |
+| `executor_agent_name` | `string \| null` | no |  |
+| `executor_type` | `"human" \| "agent"` | no | default `"human"` |
+| `links` | `Array<Record<string, unknown>>` | no |  |
+| `parent_task_id` | `string \| null` | no |  |
+| `priority` | `integer \| null` | no |  |
+| `reminder_at` | `string \| null` | no |  |
+| `reminder_sent_at` | `string \| null` | no |  |
+| `source_external_id` | `string \| null` | no |  |
+| `source_meeting_id` | `integer \| null` | no |  |
+| `source_meeting_start_time` | `string \| null` | no |  |
+| `source_meeting_title` | `string \| null` | no |  |
+| `source_transcript_id` | `string \| null` | no |  |
+| `source_url` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subtask_count` | `integer \| null` | no |  |
+| `subtask_sort_order` | `integer \| null` | no |  |
+| `tags` | `Array<string>` | no |  |
+| `task_type` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+| `visibility` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.listAllTasks();
+```
+
+---
+
+<a id="op-listcontacttasks"></a>
+
+### `g8.api.tasks.listContactTasks(input)`
+
+**List Contact Tasks**
+
+- HTTP: `GET /api/v1/contacts/{contact_id}/tasks`
+- operationId: `list_contact_tasks_contacts__contact_id__tasks_get` (also callable as `g8.api.call("list_contact_tasks_contacts__contact_id__tasks_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `tasks:read`
+- ★ Hand-written: [`g8.tasks.listForContact()`](../sdk-clients.md#g8-tasks-listforcontact)
+
+List all tasks on a contact.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.contact_id` | `integer` | yes | Contact ID |
+| `query.status` | `string \| null` | no | Filter by status (open, completed) |
+
+**Returns** `ApiResponse_list_TaskResponse__`: the envelope `{ data: Array<TaskResponse>, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `assignee_id` | `string \| null` | no |  |
+| `assignee_name` | `string \| null` | no |  |
+| `completed_subtask_count` | `integer \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `due_date` | `string \| null` | no |  |
+| `entity_id` | `string \| null` | no |  |
+| `entity_label` | `string \| null` | no |  |
+| `entity_type` | `string \| null` | no |  |
+| `execution_id` | `string \| null` | no |  |
+| `executor_agent_id` | `string \| null` | no |  |
+| `executor_agent_name` | `string \| null` | no |  |
+| `executor_type` | `"human" \| "agent"` | no | default `"human"` |
+| `links` | `Array<Record<string, unknown>>` | no |  |
+| `parent_task_id` | `string \| null` | no |  |
+| `priority` | `integer \| null` | no |  |
+| `reminder_at` | `string \| null` | no |  |
+| `reminder_sent_at` | `string \| null` | no |  |
+| `source_external_id` | `string \| null` | no |  |
+| `source_meeting_id` | `integer \| null` | no |  |
+| `source_meeting_start_time` | `string \| null` | no |  |
+| `source_meeting_title` | `string \| null` | no |  |
+| `source_transcript_id` | `string \| null` | no |  |
+| `source_url` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subtask_count` | `integer \| null` | no |  |
+| `subtask_sort_order` | `integer \| null` | no |  |
+| `tags` | `Array<string>` | no |  |
+| `task_type` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+| `visibility` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.listContactTasks({ path: { contact_id: 123 } });
+```
+
+---
+
+<a id="op-listsubtasks"></a>
+
+### `g8.api.tasks.listSubtasks(input)`
+
+**List Subtasks**
+
+- HTTP: `GET /api/v1/tasks/{task_id}/subtasks`
+- operationId: `list_subtasks_tasks__task_id__subtasks_get` (also callable as `g8.api.call("list_subtasks_tasks__task_id__subtasks_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `tasks:read`
+
+The subtasks under one task, filtered by what this key can see.
+
+A private subtask belonging to someone else is absent rather than
+redacted, so a short list is not evidence there are no more.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Parent task id (UUID). |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.listSubtasks({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-listtaskreplies"></a>
+
+### `g8.api.tasks.listTaskReplies(input)`
+
+**List Task Replies**
+
+- HTTP: `GET /api/v1/tasks/{task_id}/replies`
+- operationId: `list_task_replies_tasks__task_id__replies_get` (also callable as `g8.api.call("list_task_replies_tasks__task_id__replies_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `tasks:read`
+
+The thread under a task, plus its resolution row if it has one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task id (UUID). |
+
+**Returns** `ApiResponse_CrmCollectionPayload_`: the envelope `{ data: CrmCollectionPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`CrmCollectionPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.listTaskReplies({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-reopentaskthread"></a>
+
+### `g8.api.tasks.reopenTaskThread(input)`
+
+**Reopen Task Thread**
+
+- HTTP: `DELETE /api/v1/tasks/{task_id}/resolve`
+- operationId: `reopen_task_thread_tasks__task_id__resolve_delete` (also callable as `g8.api.call("reopen_task_thread_tasks__task_id__resolve_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `tasks:delete`
+
+Reopen this task's discussion. The replies were never deleted.
+
+Spelled as a DELETE because what it removes is the RESOLUTION, not the
+thread - this is the app's own spelling and the inverse of the POST above.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task id (UUID). |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.tasks.reopenTaskThread({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-resolvetaskthread"></a>
+
+### `g8.api.tasks.resolveTaskThread(input)`
+
+**Resolve Task Thread**
+
+- HTTP: `POST /api/v1/tasks/{task_id}/resolve`
+- operationId: `resolve_task_thread_tasks__task_id__resolve_post` (also callable as `g8.api.call("resolve_task_thread_tasks__task_id__resolve_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+Mark this task's DISCUSSION resolved.
+
+Not the same as completing the task: a task can be done with an open
+thread, and a thread can be resolved while the task is still open.
+Idempotent - re-resolving returns the existing row rather than a second
+one.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task id (UUID). |
+| `body` | `ResolveThreadRequest` | no | Request body; fields below. |
+
+Body fields (`ResolveThreadRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.resolution_note` | `string \| null` | no | Why it was resolved. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.resolveTaskThread({ path: { task_id: "id" } });
+```
+
+---
+
+<a id="op-snoozetaskreminder"></a>
+
+### `g8.api.tasks.snoozeTaskReminder(input)`
+
+**Snooze Task Reminder**
+
+- HTTP: `POST /api/v1/tasks/{task_id}/snooze`
+- operationId: `snooze_task_reminder_tasks__task_id__snooze_post` (also callable as `g8.api.call("snooze_task_reminder_tasks__task_id__snooze_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+Push this task's reminder out by N minutes FROM NOW.
+
+Relative to the call, not to the existing reminder time, so snoozing an
+overdue reminder by 30 moves it to half an hour from now rather than to
+half an hour after a moment that has passed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task id (UUID). |
+| `body` | `SnoozeTaskRequest` | yes | Request body; fields below. |
+
+Body fields (`SnoozeTaskRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.minutes` | `integer` | yes | Minutes from now to fire the next reminder. > 0 |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.snoozeTaskReminder({ path: { task_id: "id" }, body: { minutes: 1 } });
+```
+
+---
+
+<a id="op-starttaskexecution"></a>
+
+### `g8.api.tasks.startTaskExecution(input)`
+
+**Start Task Execution**
+
+- HTTP: `POST /api/v1/tasks/{task_id}/start`
+- operationId: `start_task_execution_tasks__task_id__start_post` (also callable as `g8.api.call("start_task_execution_tasks__task_id__start_post", input)`)
+- Tier: `billable`: spends credits; the SDK never blindly retries it; confirm cost before bulk use
+- API-key scope: `tasks:run`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string (uuid)` | yes |  |
+| `headers.idempotency-key` | `string (uuid)` | yes |  |
+
+**Returns** `ApiResponse_TaskStartResult_`: the envelope `{ data: TaskStartResult, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskStartResult` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `work_item_id` | `string (uuid)` | yes |  |
+| `workflow_started` | `boolean` | yes |  |
+| `already_started` | `boolean` | no | default `false` |
+| `message` | `string \| null` | no |  |
+| `session_id` | `string (uuid) \| null` | no |  |
+
+**Example**
+
+```ts
+// billable: spends credits; the SDK never blindly retries it; confirm cost before bulk use.
+const result = await g8.api.tasks.startTaskExecution({
+  path: { task_id: "00000000-0000-0000-0000-000000000000" },
+  headers: { "idempotency-key": "00000000-0000-0000-0000-000000000000" },
+});
+```
+
+---
+
+<a id="op-taskexecutionhistory"></a>
+
+### `g8.api.tasks.taskExecutionHistory(input)`
+
+**Task Execution History**
+
+- HTTP: `GET /api/v1/tasks/{task_id}/execution`
+- operationId: `task_execution_history_tasks__task_id__execution_get` (also callable as `g8.api.call("task_execution_history_tasks__task_id__execution_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `tasks:read`
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string (uuid)` | yes |  |
+
+**Returns** `ApiResponse_TaskExecutionHistory_`: the envelope `{ data: TaskExecutionHistory, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskExecutionHistory` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `runs` | `Array<TaskExecutionRun>` | yes |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.taskExecutionHistory({ path: { task_id: "00000000-0000-0000-0000-000000000000" } });
+```
+
+---
+
+<a id="op-updatesubtask"></a>
+
+### `g8.api.tasks.updateSubtask(input)`
+
+**Update Subtask**
+
+- HTTP: `PUT /api/v1/tasks/{task_id}/subtasks/{subtask_id}`
+- operationId: `update_subtask_tasks__task_id__subtasks__subtask_id__put` (also callable as `g8.api.call("update_subtask_tasks__task_id__subtasks__subtask_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+Patch a subtask. Omitted fields are left alone.
+
+Two exceptions worth knowing. An explicit `null` on `due_date`,
+`assignee_id` or `task_type` CLEARS that field, which is different from
+omitting it. And `records: []` clears every record link, while omitting
+`records` leaves them unchanged.
+
+`expected_updated_at` makes the update conditional: if the stored row has
+moved on, the write is refused instead of overwriting someone else's edit.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Parent task id (UUID). |
+| `path.subtask_id` | `string` | yes | Subtask id (UUID). |
+| `body` | `SubtaskUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`SubtaskUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.assignee_id` | `string \| null` | no | Send explicit null to unassign. |
+| `body.assignee_name` | `string \| null` | no | Assignee display name. |
+| `body.clear_reminder` | `boolean \| null` | no | Explicitly remove the reminder. |
+| `body.description` | `string \| null` | no | New body. |
+| `body.due_date` | `string \| null` | no | ISO 8601. Send explicit null to clear. |
+| `body.expected_updated_at` | `string \| null` | no | Optimistic-concurrency guard. When set and the stored row is newer, the update is refused instead of overwriting. |
+| `body.priority` | `integer \| null` | no | New priority. |
+| `body.records` | `Array<Record<string, unknown>> \| null` | no | Replace record links. Empty list clears them; omit to leave alone. |
+| `body.reminder_at` | `string \| null` | no | ISO 8601 UTC reminder. |
+| `body.status` | `string \| null` | no | New status. |
+| `body.tags` | `Array<string> \| null` | no | Replace the labels. max items 20 |
+| `body.task_type` | `string \| null` | no | Send explicit null to clear. |
+| `body.title` | `string \| null` | no | New title. |
+| `body.visibility` | `string \| null` | no | public \| team \| private. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.updateSubtask({ path: { task_id: "id", subtask_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updatetask"></a>
+
+### `g8.api.tasks.updateTask(input)`
+
+**Update Task**
+
+- HTTP: `PATCH /api/v1/tasks/{task_id}`
+- operationId: `update_task_tasks__task_id__patch` (also callable as `g8.api.call("update_task_tasks__task_id__patch", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+- ★ Hand-written: [`g8.tasks.update()`](../sdk-clients.md#g8-tasks-update)
+
+Update a task.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.task_id` | `string` | yes | Task ID |
+| `body` | `TaskUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`TaskUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.assignee_id` | `string \| null` | no | User ID to assign the task to |
+| `body.description` | `string \| null` | no | Task description |
+| `body.due_date` | `string \| null` | no | Due date (ISO 8601) |
+| `body.expected_updated_at` | `string (date-time) \| null` | no |  |
+| `body.parent_task_id` | `string \| null` | no | New parent task UUID. Re-parents this task into a subtask of the given parent. Parent must exist and must not itself be a subtask. |
+| `body.priority` | `integer \| null` | no | Priority (0=none, 1=high, 2=medium, 3=low; historical 4=low is preserved) min 0, max 4 |
+| `body.records` | `Array<Record<string, string>> \| null` | no | Replace related records; an empty list removes all links and makes the task standalone. Omit to preserve existing links. |
+| `body.status` | `string \| null` | no | Task status (open, completed) |
+| `body.subtask_sort_order` | `integer \| null` | no | New sort position within the parent's subtasks (reorder). |
+| `body.tags` | `Array<string> \| null` | no | max items 20 |
+| `body.task_type` | `string \| null` | no | Activity type; null removes the saved type |
+| `body.title` | `string \| null` | no | Task title |
+
+**Returns** `ApiResponse_TaskResponse_`: the envelope `{ data: TaskResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`TaskResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `id` | `string` | yes |  |
+| `title` | `string` | yes |  |
+| `assignee_id` | `string \| null` | no |  |
+| `assignee_name` | `string \| null` | no |  |
+| `completed_subtask_count` | `integer \| null` | no |  |
+| `created_at` | `string \| null` | no |  |
+| `created_by` | `string \| null` | no |  |
+| `description` | `string \| null` | no |  |
+| `due_date` | `string \| null` | no |  |
+| `entity_id` | `string \| null` | no |  |
+| `entity_label` | `string \| null` | no |  |
+| `entity_type` | `string \| null` | no |  |
+| `execution_id` | `string \| null` | no |  |
+| `executor_agent_id` | `string \| null` | no |  |
+| `executor_agent_name` | `string \| null` | no |  |
+| `executor_type` | `"human" \| "agent"` | no | default `"human"` |
+| `links` | `Array<Record<string, unknown>>` | no |  |
+| `parent_task_id` | `string \| null` | no |  |
+| `priority` | `integer \| null` | no |  |
+| `reminder_at` | `string \| null` | no |  |
+| `reminder_sent_at` | `string \| null` | no |  |
+| `source_external_id` | `string \| null` | no |  |
+| `source_meeting_id` | `integer \| null` | no |  |
+| `source_meeting_start_time` | `string \| null` | no |  |
+| `source_meeting_title` | `string \| null` | no |  |
+| `source_transcript_id` | `string \| null` | no |  |
+| `source_url` | `string \| null` | no |  |
+| `status` | `string \| null` | no |  |
+| `subtask_count` | `integer \| null` | no |  |
+| `subtask_sort_order` | `integer \| null` | no |  |
+| `tags` | `Array<string>` | no |  |
+| `task_type` | `string \| null` | no |  |
+| `updated_at` | `string \| null` | no |  |
+| `visibility` | `string \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.updateTask({ path: { task_id: "id" }, body: {} });
+```
+
+---
+
+<a id="op-updatetaskreply"></a>
+
+### `g8.api.tasks.updateTaskReply(input)`
+
+**Update Task Reply**
+
+- HTTP: `PUT /api/v1/tasks/replies/{reply_id}`
+- operationId: `update_task_reply_tasks_replies__reply_id__put` (also callable as `g8.api.call("update_task_reply_tasks_replies__reply_id__put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+Edit a reply. AUTHOR ONLY.
+
+An organisation key has no member identity, so it is not the author of
+anything a human wrote and cannot edit those replies - it can edit the
+ones it posted itself.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.reply_id` | `string` | yes | Reply id (UUID). |
+| `body` | `TaskReplyUpdateRequest` | yes | Request body; fields below. |
+
+Body fields (`TaskReplyUpdateRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.body` | `string` | yes | Replacement text. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.updateTaskReply({ path: { reply_id: "id" }, body: { body: "example" } });
+```
+
+---
+
+<a id="op-updatetasksettings"></a>
+
+### `g8.api.tasks.updateTaskSettings(input)`
+
+**Update Task Settings**
+
+- HTTP: `PUT /api/v1/tasks/settings`
+- operationId: `update_task_settings_tasks_settings_put` (also callable as `g8.api.call("update_task_settings_tasks_settings_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `tasks:write`
+
+Change how a parent task completes. ORG ADMIN ONLY.
+
+The app gates this twice - `require_admin_access` on the route and an
+owner/admin role check in the body. The route gate is re-declared here;
+the body check reads the role off the principal `build_api_principal`
+resolves from the validated key, so a machine key (no human, no role) is
+refused exactly as the app would refuse a member.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `TaskCompletionSettingsRequest` | yes | Request body; fields below. |
+
+Body fields (`TaskCompletionSettingsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.parent_completion_mode` | `"manual" \| "auto_complete" \| "require_subtasks_done" \| null` | no | How a parent task completes relative to its subtasks. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.tasks.updateTaskSettings({ body: {} });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-taskexecutionrun"></a>
+
+### `TaskExecutionRun`
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `completed_at` | `string (date-time) \| null` | yes |  |
+| `created_at` | `string (date-time)` | yes |  |
+| `current_step` | `string \| null` | yes |  |
+| `details_available` | `boolean` | yes |  |
+| `next_action` | `string \| null` | yes |  |
+| `session_id` | `string (uuid) \| null` | yes |  |
+| `status` | `string` | yes |  |
+| `work_item_id` | `string (uuid)` | yes |  |
+| `continued_after_reply` | `boolean` | no | default `false` |