> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks

> 7 tools: heliyos_tasks_list, heliyos_tasks_get, heliyos_tasks_events, heliyos_tasks_create, heliyos_tasks_update, heliyos_tasks_delete, heliyos_tasks_run.

| Tool | What it does | Kind |
| - | - | - |
| [`heliyos_tasks_list`](#heliyos-tasks-list) | List tasks | Read |
| [`heliyos_tasks_get`](#heliyos-tasks-get) | Get a task | Read |
| [`heliyos_tasks_events`](#heliyos-tasks-events) | Read a task's activity | Read |
| [`heliyos_tasks_create`](#heliyos-tasks-create) | Create a task | Write |
| [`heliyos_tasks_update`](#heliyos-tasks-update) | Update a task | Write |
| [`heliyos_tasks_delete`](#heliyos-tasks-delete) | Delete a task | Destructive |
| [`heliyos_tasks_run`](#heliyos-tasks-run) | Run workers on a task | Destructive |

Write and destructive tools change your workspace. Clients that support it ask before they run.

## List tasks

`heliyos_tasks_list` · **Read** · Idempotent

Lists tasks, newest first, optionally only those linked to one record (record\_id), in one status, or matching text. Each task shows its id, title, status, priority, due date and whether workers are running on it. Use heliyos\_tasks\_get for the description and links. Returns structuredContent \{tasks:\[\{id, title, status, ...}], next\_cursor}.

### Inputs

**record\_id** `string`

Only tasks linked to this record. A 24-character hex id.

**status** `string`

backlog, in\_progress, scheduled\_for\_later (a worker set a wake-up for it), on\_hold (waiting on a person or an event), cancelled or completed. One of `backlog`, `in_progress`, `scheduled_for_later`, `on_hold`, `cancelled`, `completed`.

**search** `string`

Plain words matched against task titles and descriptions. Symbols such as + ( ) \[ ] \* ? can cause an error. Up to 200 characters.

**limit** `integer` (default: 20)

Tasks per page, 1 to 100. Default 20. From 1 to 100.

**cursor** `string`

next\_cursor from the previous page, with the same limit. Omit for the first page. Up to 200 characters.

**response\_format** `string` (default: concise)

"concise" (default) returns one row per task; "detailed" returns assignees, workers and linked records too. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `tasks`, `next_cursor`.

### API endpoints

* [List tasks](https://docs.heliyos.ai/api-reference/tasks/list-tasks.md) · `GET /v1/platform/tasks`

## Get a task

`heliyos_tasks_get` · **Read** · Idempotent

Fetches one task by id: title, status, priority, due date, assignees and workers, the workers' run status and run\_id, the records it is linked to, and its description (cut at 1500 characters in concise). Returns structuredContent \{task}.

### Inputs

**task\_id** `string` *required*

task\_id: a 24-character hex id. A 24-character hex id.

**response\_format** `string` (default: concise)

"concise" (default) returns the task with a shortened description; "detailed" returns the full description and times. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `task`.

### API endpoints

* [Get a task](https://docs.heliyos.ai/api-reference/tasks/get-a-task.md) · `GET /v1/platform/tasks/{id}`

## Read a task's activity

`heliyos_tasks_events` · **Read** · Idempotent

Returns the activity (change history) of one task: who changed what and when (people and workers), newest first, each with a one-line change summary. "detailed" adds the paths of the changed fields. For a company, person or deal use heliyos\_records\_events; for what the workers did on the task use heliyos\_runs\_list with task\_id. Returns structuredContent \{events:\[\{id, at, operation\_type, actor, change\_summary}], next\_cursor}.

### Inputs

**task\_id** `string` *required*

task\_id: a 24-character hex id. A 24-character hex id.

**limit** `integer` (default: 20)

Events per page, 1 to 100. Default 20. From 1 to 100.

**cursor** `string`

next\_cursor from the previous page, with the same limit. Omit for the first page. Up to 200 characters.

**response\_format** `string` (default: concise)

"concise" (default) returns one line per change; "detailed" returns the changed field paths too. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `events`, `next_cursor`.

### API endpoints

* [List task events](https://docs.heliyos.ai/api-reference/activities/list-task-events.md) · `GET /v1/platform/tasks/{id}/events`

## Create a task

`heliyos_tasks_create` · **Write**

Creates a task, optionally linked to records (a company, person or deal). Creating a task can start workers that subscribe to new tasks. Calling it twice creates two tasks. To have workers act on it now, call heliyos\_tasks\_run with the returned id. Returns structuredContent \{task}.

### Inputs

**title** `string` *required*

Task title. Up to 500 characters.

**description** `string`

Task description (plain text). Up to 20000 characters.

**status** `string`

Default backlog. One of `backlog`, `in_progress`, `scheduled_for_later`, `on_hold`, `cancelled`, `completed`.

**priority** `string`

none, low, medium, high or urgent. One of `none`, `low`, `medium`, `high`, `urgent`.

**due\_date** `string`

due\_date as an ISO 8601 date (2026-03-01) or date-time (2026-03-01T09:00:00Z). Up to 40 characters.

**record\_ids** `string[]`

Ids of records (companies, people, deals) to link the task to, 1 to 10. Each id is checked first; an unknown id fails the call and nothing is written. Up to 10 items.

### Returns

A readable text summary, plus `structuredContent` with `task`.

### API endpoints

* [Create a task](https://docs.heliyos.ai/api-reference/tasks/create-a-task.md) · `POST /v1/platform/tasks`

## Update a task

`heliyos_tasks_update` · **Write** · Idempotent

Changes a task's title, description, status, priority, due date or linked records by id; what you leave out is kept. Setting status completed also marks it finished. record\_ids REPLACES the task's links (pass every record it should stay linked to). Returns structuredContent \{task}.

### Inputs

**task\_id** `string` *required*

task\_id: a 24-character hex id. A 24-character hex id.

**title** `string`

Task title. Up to 500 characters.

**description** `string`

Task description (plain text). Up to 20000 characters.

**status** `string`

backlog, in\_progress, scheduled\_for\_later (a worker set a wake-up for it), on\_hold (waiting on a person or an event), cancelled or completed. One of `backlog`, `in_progress`, `scheduled_for_later`, `on_hold`, `cancelled`, `completed`.

**priority** `string`

none, low, medium, high or urgent. One of `none`, `low`, `medium`, `high`, `urgent`.

**due\_date** `string`

due\_date as an ISO 8601 date (2026-03-01) or date-time (2026-03-01T09:00:00Z). Up to 40 characters.

**record\_ids** `string[]`

Ids of records (companies, people, deals) to link the task to, 1 to 10. Each id is checked first; an unknown id fails the call and nothing is written. Up to 10 items.

### Returns

A readable text summary, plus `structuredContent` with `task`.

### API endpoints

* [Update a task](https://docs.heliyos.ai/api-reference/tasks/update-a-task.md) · `PATCH /v1/platform/tasks/{id}`

## Delete a task

`heliyos_tasks_delete` · **Destructive** · Idempotent

Permanently deletes one task by id. This cannot be undone: confirm with the user first. Returns structuredContent \{task\_id, deleted}.

### Inputs

**task\_id** `string` *required*

task\_id: a 24-character hex id. A 24-character hex id.

### Returns

A readable text summary, plus `structuredContent` with `task_id`, `deleted`.

### API endpoints

* [Delete a task](https://docs.heliyos.ai/api-reference/tasks/delete-a-task.md) · `DELETE /v1/platform/tasks/{id}`

## Run workers on a task

`heliyos_tasks_run` · **Destructive**

Starts the workers (AI agents) on one task now and marks it in progress. If a run is already open, returns that run instead of starting another. Runs use credits; the call fails when the workspace is out of them. Returns structuredContent \{task\_id, run\_id, started, status}; follow the run with heliyos\_runs\_get using run\_id.

### Inputs

**task\_id** `string` *required*

task\_id: a 24-character hex id. A 24-character hex id.

### Returns

A readable text summary, plus `structuredContent` with `task_id`, `run_id`, `started`, `status`.

### API endpoints

* [Run workers on a task](https://docs.heliyos.ai/api-reference/tasks/run-workers-on-a-task.md) · `POST /v1/platform/tasks/{id}/runs`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.