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

​
Ask Heliyos

heliyos_ask · Destructive Asks Heliyos (the orchestrator and its workers) a question or gives it a job, in plain language, for example “summarise what changed with Acme this week” or “draft a follow-up to the Globex thread”. It can read and act on the whole workspace: it may change records and tasks or send email, and consequential actions wait for approval in Heliyos, so confirm jobs that change things with the user first. Waits up to 90 s: a finished run returns its answer and run_id. Otherwise it returns {run_id, status, thread_id} and the text “Still running”; then call heliyos_runs_get with that run_id and wait: true. Pass thread_id to continue the same conversation. Runs use credits; calling it twice starts two runs. Needs a client tool timeout of at least 120 s. Returns structuredContent {run_id, status, thread_id, done, answer?}.

​
Inputs

​
string
required
The question or instruction. Up to 20000 characters.
​
string
thread_id from an earlier heliyos_ask, to ask a follow-up in the same conversation. Up to 100 characters.

​
Returns

A readable text summary, plus structuredContent with run_id, status, thread_id, done, answer.

​
API endpoints

​
Get a run

heliyos_runs_get · Read · Idempotent Reads one worker run: its status, whether it is done, its steps (seq, type, title, status, start and end times, a one-line summary each), reviews waiting on a person, credits used, and the final answer once there is one. wait: true waits up to 30 s for the run to finish or stop on a person; call again with wait: true while done is false, unless the run waits on a person (awaiting_approval, paused, waiting, scheduled): then it only moves when someone acts in Heliyos, and wait: true returns at once. “detailed” adds each step’s raw input, output and error. Returns structuredContent {run:{id, status, done, steps, reviews, answer?}}.

​
Inputs

​
string
required
The run id (run_id) from heliyos_ask, heliyos_tasks_run, heliyos_tasks_get or heliyos_runs_list. Up to 128 characters.
​
boolean
default:"false"
true: wait up to 30 s for the run to finish before answering.
​
string
default:"concise"
“concise” (default) returns status and one line per step; “detailed” returns each step’s raw input, output and error, plus run title and workers. One of concise, detailed.

​
Returns

A readable text summary, plus structuredContent with run.

​
API endpoints

  • Get a run · GET /v1/platform/workers/runs/{id}

​
List runs

heliyos_runs_list · Read · Idempotent Lists worker runs (chats with Heliyos, task runs and automatic runs), newest first, optionally in one status, for one task, one worker or one company, or in a date range. Shows each run’s id, status, title and start time; read one with heliyos_runs_get. Order with sort. Returns structuredContent {runs:[{id, status, title, …}], next_cursor}.

​
Inputs

​
string
Only runs in this status, for example running, awaiting_approval, completed or failed. One of queued, running, awaiting_approval, paused, waiting, scheduled, completed, failed, skipped, cancelled, stopped.
​
string
Only runs on this task (its own runs and chats that mention it). A 24-character hex id.
​
string
Only runs of this worker (id from heliyos_workers_list). A 24-character hex id.
​
string
Only runs about this company record. A 24-character hex id.
​
string
Only runs started at or after this date (ISO 8601). Up to 40 characters.
​
string
Only runs started at or before this date; a date alone includes that whole day (UTC). Up to 40 characters.
​
object
Sort order. Omit for newest first. With a sort, next_cursor is a page cursor from this tool; pass it back unchanged.
​
integer
default:"20"
Runs 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 run; “detailed” returns task, workers and tool calls too. One of concise, detailed.

​
Returns

A readable text summary, plus structuredContent with runs, next_cursor.

​
API endpoints

​
List reviews

heliyos_reviews_list · Read · Idempotent Lists reviews: worker actions waiting for a person’s decision (an email draft, a deal change, a meeting, a task, a document, or a question the worker asked), pending ones by default, newest first. Filter by status, type, or the record or task they are about. Each shows its id, type, title, summary, the worker and the records. Read one with heliyos_reviews_get, decide it with heliyos_reviews_decide. Returns structuredContent {reviews:[{id, status, type, title, summary, worker, run_id, records}], next_cursor}.

​
Inputs

​
string
default:"pending"
pending (default), approved or rejected. One of pending, approved, rejected.
​
string
Only one type: deal_update, email_draft, meeting_scheduled, task, document, decision (questions and ad-hoc approvals), classification_label, or a tool name. Up to 64 characters.
​
string
Only reviews about this record (company, person, deal) or task. A 24-character hex id.
​
integer
default:"20"
Reviews 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 id, type, title, summary, worker and records per review; “detailed” returns the reasoning and draft or deal details too. One of concise, detailed.

​
Returns

A readable text summary, plus structuredContent with reviews, next_cursor.

​
API endpoints

​
Get a review

heliyos_reviews_get · Read · Idempotent Fetches one review by id with everything a person needs to decide it: the worker’s proposal and reasoning, the draft email (subject, recipients, body) or the deal’s fields before and after, the records and run it belongs to, and, once decided, the comment and outcome. Long texts are cut at 400 characters in concise. Returns structuredContent {review}.

​
Inputs

​
string
required
review_id: a 24-character hex id. A 24-character hex id.
​
string
default:"concise"
“concise” (default) returns the proposal with shortened texts; “detailed” returns full texts, the raw proposed arguments and the outcome. One of concise, detailed.

​
Returns

A readable text summary, plus structuredContent with review.

​
API endpoints

​
Approve or reject a review

heliyos_reviews_decide · Destructive Decides one pending review. Approving does the thing the worker proposed: the email is sent, the deal or label is changed, the meeting is booked, or the paused run continues with its action; rejecting discards it and tells the worker why (feedback). A review is decided once; a second call fails. Approving acts on the user’s behalf and cannot be undone: read it with heliyos_reviews_get and confirm with the user first. For a deal_update you may pass the fields as the user edited them in data; for a paused tool call, edited arguments in args. Returns structuredContent {review_id, decision, status, run_notified}.

​
Inputs

​
string
required
review_id: a 24-character hex id. A 24-character hex id.
​
string
required
approved or rejected. One of approved, rejected.
​
string
A note kept on the review. Up to 5000 characters.
​
string
What to tell the worker, for example why it was rejected or what to change. Up to 5000 characters.
​
object
deal_update and approved only: the deal’s fields as the user confirmed or edited them (field key to value).
​
object
A paused tool call and approved only: the tool’s arguments as the user edited them (see proposal in heliyos_reviews_get).

​
Returns

A readable text summary, plus structuredContent with review_id, decision, status, run_notified, review.

​
API endpoints

Last modified on November 5, 2026