Guides
API reference
MCP server
Changelogcurl --request PATCH \
--url https://api-prod.heliyos.ai/v1/platform/tasks/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"status": "completed",
"isFinished": true
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({status: 'completed', isFinished: true})
};
fetch('https://api-prod.heliyos.ai/v1/platform/tasks/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api-prod.heliyos.ai/v1/platform/tasks/{id}"
payload = {
"status": "completed",
"isFinished": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"meta": {
"message": "Task updated successfully."
},
"data": {
"id": "6728c9afb2c3d4e5f6a7b8ce",
"organizationId": "66a0f1e2d3c4b5a697887766",
"title": "Send security questionnaire to Northwind Traders",
"status": "completed",
"priority": "high",
"isFinished": true,
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"schemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company"
}
],
"metadata": {
"created": {
"at": "2026-11-04T09:40:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-05T08:15:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"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>"
}
}Update a task
Changes the fields you send and keeps the rest. Send at least one field. relationships,
assignedUser and assignedAgents, when sent, each replace the whole list: include the entries
you want to keep.
Setting status does not change isFinished; send both when you complete or reopen a task.
Moving a task off scheduled_for_later cancels the worker’s pending wake-up.
After the write, Heliyos records an audit event, sends the workspace’s task-updated notification
email if it is turned on, updates the task in HubSpot if it is synced there, and fires a trigger
(task.cancelled when the status changes to cancelled, task.updated otherwise): workers that
subscribe to it can start, and their runs use credits. No trigger fires while workers are paused on
the task, or when the change only adds or removes whitespace.
curl --request PATCH \
--url https://api-prod.heliyos.ai/v1/platform/tasks/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"status": "completed",
"isFinished": true
}
'const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({status: 'completed', isFinished: true})
};
fetch('https://api-prod.heliyos.ai/v1/platform/tasks/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api-prod.heliyos.ai/v1/platform/tasks/{id}"
payload = {
"status": "completed",
"isFinished": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text){
"meta": {
"message": "Task updated successfully."
},
"data": {
"id": "6728c9afb2c3d4e5f6a7b8ce",
"organizationId": "66a0f1e2d3c4b5a697887766",
"title": "Send security questionnaire to Northwind Traders",
"status": "completed",
"priority": "high",
"isFinished": true,
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"schemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company"
}
],
"metadata": {
"created": {
"at": "2026-11-04T09:40:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-05T08:15:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"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_tasks_update.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.
Path Parameters
The task's id.
^[0-9a-fA-F]{24}$Body
A new title. May be an empty string.
A new body. May be an empty string.
A new stage.
backlog, in_progress, scheduled_for_later, on_hold, cancelled, completed A new priority. Use one of these values; an update does not check it.
none, low, medium, high, urgent A new due date, as an ISO 8601 date or date-time.
The done flag.
The complete new list of people. Newly added ids must be workspace members (you can always assign yourself); ids already on the task are kept even if that person has left.
Show child attributes
Show child attributes
The complete new list of workers. Newly added agentIds must be workspace workers; each entry needs agentId.
Show child attributes
Show child attributes
The complete new set of links. Replaces the current links. At most 200.
Show child attributes
Show child attributes
Was this page helpful?