Guides
API reference
MCP server
Changelogcurl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/orchestrator/chats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "Summarise what changed with Contoso this week and list open risks.",
"wait": 60
}
'{
"meta": {
"message": "Successful request"
},
"data": {
"runId": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e",
"status": "completed",
"threadId": "3fa9c2d17b4e",
"output": {
"final_response_by": "Heliyos",
"response": "Contoso moved to Negotiation on Tuesday. Two risks: procurement wants a security review, and the champion is out until Nov 12."
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}Ask Heliyos
Sends a message to Heliyos, the same as typing it into Ask Heliyos in the app. Heliyos reads the workspace, plans, and calls workers to do the work. It can answer a question (“summarise what changed with Contoso this week”) or carry out a job (“draft a follow-up to the Fabrikam thread”).
What it returns. The call starts a run and answers with runId, status and threadId.
With wait above 0 it holds the request for up to that many seconds until the run settles:
finishes, or stops to wait on a person or a schedule. If the run completes in time, output
carries the reply. Otherwise follow the run:
- Call Get a run with the
runIdandwait=30. Repeat whilestatusisqueuedorrunning. - When
statusiscompleted, readoutput.response. Onfailed, readerrorwithinclude=detail. - When
statusisawaiting_approval,paused,waitingorscheduled, polling will not move it. A person has to act in Heliyos (Review), or the scheduled time has to come.
List runs with threadId returns every run of a conversation.
Conversations. Leave threadId out to start a new conversation; Heliyos returns its id.
Send it back to continue. If the thread’s run is still open, your message joins that run instead
of starting another: it is queued while the run works, read after the decision while it waits
for a review, and resumes it when it is paused.
Reviews. Consequential actions, such as sending an email or changing a deal, wait for a
person’s approval unless the workspace’s autopilot allows them. The run then shows
awaiting_approval and lists the reviews in reviews.
Credits. Each call to a custom worker during the run spends credits once the call finishes.
Default workers and Heliyos’s own reasoning are free. Tools the run uses can spend credits too,
for example company enrichment. The run’s total is in usage.credits on Get a run, and each
charge is in List credit usage under worker_run.
Timeouts. wait is at most 90 seconds; set your HTTP client’s timeout above it (120 seconds
is safe). A run has no fixed time limit and keeps working after the call returns. If you
disconnect early, the run is not affected.
Every call starts or continues work: calling twice with the same message runs it twice.
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/orchestrator/chats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"message": "Summarise what changed with Contoso this week and list open risks.",
"wait": 60
}
'{
"meta": {
"message": "Successful request"
},
"data": {
"runId": "9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e",
"status": "completed",
"threadId": "3fa9c2d17b4e",
"output": {
"final_response_by": "Heliyos",
"response": "Contoso moved to Negotiation on Tuesday. Two risks: procurement wants a security review, and the champion is out until Nov 12."
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}heliyos_ask.Authorizations
A workspace API key, sent as Authorization: Bearer heliyos_.... Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in.
Body
The question or instruction, in plain language. 1 to 20,000 characters after trimming.
1 - 20000"Summarise what changed with Contoso this week and list open risks."
The threadId from an earlier answer, to continue that conversation. 1 to 100 characters of letters, digits and _ . : @ = + -. Leave it out to start a new conversation. An id Heliyos has not seen starts a new conversation under that id.
1 - 100^[A-Za-z0-9_.:@=+-]+$"3fa9c2d17b4e"
Ids of files you already uploaded, up to 20. Heliyos and its workers can read them during the run. Each must be a file of this workspace.
20A 24-character hexadecimal id.
^[0-9a-fA-F]{24}$Seconds to hold the request while the run works, 0 to 90. 0 (the default) answers at once. The call returns as soon as the run finishes or waits on a person or a schedule.
0 <= x <= 9060
Was this page helpful?