> ## 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. # 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. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_tasks_update`](https://docs.heliyos.ai/mcp/tools/tasks#heliyos-tasks-update). ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/platform/tasks/{id} openapi: 3.0.3 info: title: Heliyos API version: 1.0.0 description: >- The REST API for Heliyos, the AI operating system for revenue. Every request is scoped to the workspace that owns the API key. Responses are JSON in a `{ meta, data }` envelope; errors use `{ message, error: { code, message, details } }`. contact: name: Heliyos support email: soham@heliyos.ai url: https://www.heliyos.ai servers: - url: https://api-prod.heliyos.ai description: Production security: - bearerAuth: [] tags: - name: Workspace description: >- The workspace your API key belongs to, and the log of credits it has used. Every other call in this API is scoped to this workspace. - name: Schemas description: >- Objects are your record types: companies, people, deal pipelines and any custom objects you add. Each object has fields, and a field's type decides what its records can hold. - name: Records description: >- Records are the rows of an object (base schema): companies, people, deals and custom objects. A record holds field values keyed by the object's field keys and links to other records. - name: Timeline description: >- The AI-written timeline of a company, person or deal: summary entries Heliyos writes on a schedule. For the exact change history see Activities, and for emails and meetings see Interactions. - name: Activities description: >- The change history of records and tasks: who created, changed or deleted what, and when. People, workers and the system each appear as the actor on the changes they make. - name: Interactions description: >- Email threads and meetings synced from connected mailboxes and calendars, linked to the people and companies they involve. - name: Notes description: >- Free-text notes, optionally linked to records, tasks and interactions. Notes show up on the timeline of every record they are linked to, and workers read them as customer memory. - name: Tasks description: >- Work items for people and workers, optionally linked to records. A task can be assigned to people, to workers, or both, and workers can be started on it directly. - name: Workers and runs description: >- Workers are the AI teammates of your workspace (the API calls them agents). Define what each one does and what starts it, ask Heliyos to do work, and follow every run, its steps and the reviews it waits on. - name: Reviews description: >- Reviews keep the team in control of consequential work. When a worker wants to send an email, change a deal, book a meeting, act in a connected app or needs a person's answer, the action waits as a review until someone approves or rejects it. - name: Scouts description: >- Scouts watch companies and the web for events such as funding rounds, product launches, leadership changes or press coverage, and record each finding as a signal. A workspace Scout defines what to look for; company Scouts are its copies running on individual companies. - name: Signals description: >- Signals are what Scouts find: one event, such as a funding round or a new executive, with a summary, its sources and the company it is about. New signals are unread until you mark them read. - name: Watchlist description: >- The watchlist is the set of companies your workers monitor. Each watched company uses one Watcher from your plan: the workers keep it enriched, pull in its emails and meetings, and run Scouts on it. - name: Knowledge base description: >- What your workers know about the business: the business context, four fixed texts (products, pain points, value proposition, qualification criteria) and any custom entries your team adds. Workers read it on their next run. Files your workers read live under Files, with kind `knowledge_base`. - name: Files description: >- Knowledge base files that workers read, and files attached to records, tasks and other resources. The API calls them attachments. Uploading takes three calls: get an upload URL, send the bytes to it, then create the file. - name: Labels description: >- Label groups that sort your email threads, for example Intent or Pricing questions. Heliyos files each classified thread under a group, and each group holds the more specific labels it brings together. The API calls them classification labels. - name: Team description: >- The people in your workspace and their roles: joined members and pending invitations. Inviting someone sends them an email. - name: Notification settings description: >- Which workspace events send notification emails, how often, and to whom. There is one settings document per workspace, shared by everyone in it. paths: /v1/platform/tasks/{id}: patch: tags: - Tasks summary: Update a task description: >- 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. operationId: updateTask parameters: - name: id in: path required: true schema: type: string pattern: ^[0-9a-fA-F]{24}$ description: The task's id. example: 6728c9afb2c3d4e5f6a7b8ce requestBody: required: true content: application/json: schema: type: object properties: title: type: string description: A new title. May be an empty string. description: type: string description: A new body. May be an empty string. status: type: string enum: - backlog - in_progress - scheduled_for_later - on_hold - cancelled - completed allOf: - $ref: '#/components/schemas/TaskStatus' description: A new stage. priority: type: string enum: - none - low - medium - high - urgent description: >- A new priority. Use one of these values; an update does not check it. dueDate: type: string format: date-time description: A new due date, as an ISO 8601 date or date-time. isFinished: type: boolean description: The done flag. assignedUser: type: array items: $ref: '#/components/schemas/TaskAssignee' description: >- 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. assignedAgents: type: array items: allOf: - $ref: '#/components/schemas/TaskWorkerAssignment' required: - agentId description: >- The complete new list of workers. Newly added `agentId`s must be workspace workers; each entry needs `agentId`. relationships: type: array items: $ref: '#/components/schemas/TaskRelationshipInput' description: >- The complete new set of links. Replaces the current links. At most 200. additionalProperties: false minProperties: 1 example: status: completed isFinished: true responses: '200': description: >- The updated task as stored: its id is in `id` (not `_id`) and relationships are not hydrated. content: application/json: schema: type: object required: - meta - data properties: meta: type: object required: - message properties: message: type: string description: A human-readable summary of the result. data: $ref: '#/components/schemas/Task' example: 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 '400': description: >- VALIDATION_FAILED: an empty body, a field with the wrong type or value, or a malformed id. Nothing is written. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: >- NOT_FOUND: no task with this id, or a relationships entry, assignee or worker is not in this workspace. Nothing is written. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: TaskStatus: type: string enum: - backlog - in_progress - scheduled_for_later - on_hold - cancelled - completed description: > The task's stage on the board: - `backlog`: not started. The default. - `in_progress`: being worked on, by a person or by workers. - `scheduled_for_later`: a worker set a wake-up for it and will pick it up at that time. - `on_hold`: waiting on a person or an outside event. - `cancelled`: dropped. - `completed`: done. TaskAssignee: type: object description: A person assigned to the task. properties: id: allOf: - $ref: '#/components/schemas/ObjectId' description: The user's id. Must be a member of the workspace. name: type: string description: The name shown on the task. Stored as sent. profilePicture: type: string nullable: true description: An avatar URL shown on the task. Stored as sent. TaskWorkerAssignment: type: object description: A worker assigned to the task. properties: agentId: allOf: - $ref: '#/components/schemas/ObjectId' description: The worker's id. Must be one of the workspace's workers. name: type: string description: The worker's name, shown on the task. Stored as sent. role: type: string enum: - executor - reviewer - approver description: >- `executor` does the work, `reviewer` checks it, `approver` signs it off. TaskRelationshipInput: type: object description: A record to link the task to. required: - objectId properties: objectId: allOf: - $ref: '#/components/schemas/ObjectId' description: >- Id of the linked record, task, note or interaction. Must belong to this workspace. schemaId: type: string nullable: true description: >- The linked record's object (base schema) id. Recommended for records. Empty or null is dropped. objectType: type: string nullable: true description: >- `company`, `people`, `deals` or a custom object type for records; `task`, `note` or `interaction` otherwise. example: company data: type: object additionalProperties: true description: >- An optional display snapshot of the record, stored as sent. Get and list replace it with the record's current values. Task: type: object additionalProperties: true properties: _id: allOf: - $ref: '#/components/schemas/ObjectId' description: The task's id. Create and update responses name it `id` instead. organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace the task belongs to. title: type: string description: The task's title. Can be an empty string. description: type: string description: The task's body, as plain text or markdown. status: $ref: '#/components/schemas/TaskStatus' priority: $ref: '#/components/schemas/TaskPriority' isFinished: type: boolean description: >- A done flag kept beside `status`. Heliyos does not derive it from `status`: set it yourself when you complete or reopen a task. dueDate: allOf: - $ref: '#/components/schemas/Timestamp' description: When the task is due. Absent when none is set. assignedUser: type: array description: The people assigned to the task. items: $ref: '#/components/schemas/TaskAssignee' assignedAgents: type: array description: The workers assigned to the task. items: $ref: '#/components/schemas/TaskWorkerAssignment' relationships: type: array description: >- The records the task is linked to. In list and get responses each entry is hydrated with the record's field values in `data` and its object in `schema`. items: $ref: '#/components/schemas/Relationship' currentRunId: type: string description: The id of the workers' current or last run on the task. currentRun: $ref: '#/components/schemas/TaskRunState' artifactsCount: type: integer description: Files linked to the task. List and get only. agentPaused: type: boolean description: True when workers are paused on this task. Starting a run clears it. agentRun: type: object additionalProperties: true description: >- The last note a worker left on the task (`note`, `runId`, `agent`, `at`). planCheckpoints: type: array description: >- The steps of the workers' plan for the task, each with `id`, `title`, `description`, `worker`, `note` and `status` (`pending`, `running`, `completed`, `failed` or `skipped`). items: type: object additionalProperties: true hubspotTaskId: type: string description: >- The linked HubSpot task id, when the workspace syncs tasks with HubSpot. metadata: $ref: '#/components/schemas/AuditMetadata' ErrorEnvelope: type: object required: - message - error properties: message: type: string description: Same as error.message. error: type: object required: - code - message properties: code: type: string enum: - VALIDATION_FAILED - UNAUTHENTICATED - FORBIDDEN_ACTION - NOT_FOUND - RATE_LIMITED - CONFLICT - INTERNAL message: type: string details: {} ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 TaskPriority: type: string enum: - none - low - medium - high - urgent description: The task's priority. Defaults to `medium`. Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' Relationship: type: object description: >- A linked resource, hydrated with a short summary so it can be shown without another call. properties: objectId: $ref: '#/components/schemas/ObjectId' schemaId: type: string nullable: true description: The linked record's object id, when the link points at a record. objectType: type: string nullable: true description: >- `company`, `people`, `deals`, a custom object type, `task`, `interaction` or `meeting`. data: type: object additionalProperties: true description: >- A summary of the linked resource. For a record, its field values (for example `company_name` and `logo`, or `people_name`). For a task, `title` and `status`. For an interaction, `subject` and `channelType`. Empty when the target no longer exists. schema: type: object nullable: true additionalProperties: true description: >- The linked record's object (`_id`, `name`, `objectType`, `fields`). Present on single-resource reads. TaskRunState: type: object description: >- The workers' current or last run on the task. Present only when the task has had a run, a worker note or a scheduled wake-up. properties: status: type: string description: >- The run's status, for example `queued`, `running`, `paused`, `awaiting_approval` (a worker action waits for review), `waiting`, `completed`, `failed` or `stopped`. `stalled` means the run says it is running but has written nothing for 20 minutes. summary: type: string description: The last note a worker left on the task. planSteps: type: integer description: Steps in the run's plan. completedSteps: type: integer description: Plan steps completed or skipped. artifactsCount: type: integer description: Files linked to the task. lastRunAt: allOf: - $ref: '#/components/schemas/Timestamp' description: When the run last changed. hasSchedule: type: boolean description: True when a worker scheduled a wake-up for the task. nextRunReason: type: string description: Why the worker scheduled the wake-up. nextRunAt: allOf: - $ref: '#/components/schemas/Timestamp' description: When the wake-up fires. Absent for a recurring schedule. AuditMetadata: type: object description: Who created and last changed the resource, and when. properties: created: type: object properties: at: $ref: '#/components/schemas/Timestamp' by: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the user (or the API key's owner) who created it. updated: type: object properties: at: $ref: '#/components/schemas/Timestamp' by: allOf: - $ref: '#/components/schemas/ObjectId' description: Id of the user who last changed it. securitySchemes: bearerAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.