Guides
API reference
MCP server
Changelog
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
string
Only tasks linked to this record. A 24-character hex id.
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.string
Plain words matched against task titles and descriptions. Symbols such as + ( ) [ ] * ? can cause an error. Up to 200 characters.
integer
default:"20"
Tasks per page, 1 to 100. Default 20. From 1 to 100.
string
next_cursor from the previous page, with the same limit. Omit for the first page. Up to 200 characters.
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, plusstructuredContent with tasks, next_cursor.
API endpoints
- List tasks ·
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
string
required
task_id: a 24-character hex id. A 24-character hex id.
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, plusstructuredContent with task.
API endpoints
- Get a task ·
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
string
required
task_id: a 24-character hex id. A 24-character hex id.
integer
default:"20"
Events per page, 1 to 100. Default 20. From 1 to 100.
string
next_cursor from the previous page, with the same limit. Omit for the first page. Up to 200 characters.
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, plusstructuredContent with events, next_cursor.
API endpoints
- List task events ·
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
string
required
Task title. Up to 500 characters.
string
Task description (plain text). Up to 20000 characters.
string
Default backlog. One of
backlog, in_progress, scheduled_for_later, on_hold, cancelled, completed.string
none, low, medium, high or urgent. One of
none, low, medium, high, urgent.string
due_date as an ISO 8601 date (2026-03-01) or date-time (2026-03-01T09:00:00Z). Up to 40 characters.
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, plusstructuredContent with task.
API endpoints
- Create a task ·
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
string
required
task_id: a 24-character hex id. A 24-character hex id.
string
Task title. Up to 500 characters.
string
Task description (plain text). Up to 20000 characters.
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.string
none, low, medium, high or urgent. One of
none, low, medium, high, urgent.string
due_date as an ISO 8601 date (2026-03-01) or date-time (2026-03-01T09:00:00Z). Up to 40 characters.
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, plusstructuredContent with task.
API endpoints
- Update a task ·
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
string
required
task_id: a 24-character hex id. A 24-character hex id.
Returns
A readable text summary, plusstructuredContent with task_id, deleted.
API endpoints
- Delete a task ·
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
string
required
task_id: a 24-character hex id. A 24-character hex id.
Returns
A readable text summary, plusstructuredContent with task_id, run_id, started, status.
API endpoints
- Run workers on a task ·
POST /v1/platform/tasks/{id}/runs