> ## 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. # Create a worker > Creates a custom worker. It starts active unless you send `isActive: false`, and its triggers take effect at once. What you leave out gets a default: empty instructions, no tools or actions, memory on, and every knowledge base file linked. `toolName` is made from the name (lowercase, other characters as `_`, at most 48 characters) unless you send one. Scheduled triggers are registered after the save; `scheduleSync` in the response says whether each one is in place. Creating a worker is free. Its runs are not: each call to a custom worker during a run spends credits (feature `worker_run` in **List credit usage**). Needs a workspace owner or admin. An API key counts as an admin. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_workers_create`](https://docs.heliyos.ai/mcp/tools/workers-triggers-and-tools#heliyos-workers-create). ## OpenAPI ````yaml /api-reference/openapi.json post /v1/platform/agents 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/agents: post: tags: - Workers and runs summary: Create a worker description: >- Creates a custom worker. It starts active unless you send `isActive: false`, and its triggers take effect at once. What you leave out gets a default: empty instructions, no tools or actions, memory on, and every knowledge base file linked. `toolName` is made from the name (lowercase, other characters as `_`, at most 48 characters) unless you send one. Scheduled triggers are registered after the save; `scheduleSync` in the response says whether each one is in place. Creating a worker is free. Its runs are not: each call to a custom worker during a run spends credits (feature `worker_run` in **List credit usage**). Needs a workspace owner or admin. An API key counts as an admin. operationId: createAgent parameters: [] requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 200 description: >- The worker's name, 1 to 200 characters after trimming. Unique in the workspace. example: Account researcher description: type: string maxLength: 2000 description: >- One line on what the worker is for, up to 2,000 characters. Heliyos reads it to decide when to call the worker. example: >- Researches a company before a first call and writes a brief on the record. icon: type: string maxLength: 100 description: An icon name for the Heliyos app, up to 100 characters. example: search instructions: type: string maxLength: 50000 description: >- What the worker does and how, in Markdown, up to 50,000 characters. Defaults to empty. example: >- When a meeting is booked with a new company, research it and add a note with its products, recent news and likely priorities. isActive: type: boolean description: '`false` creates the worker paused. Defaults to `true`.' toolName: type: string pattern: ^[a-z0-9_]{1,48}$ description: >- The snake_case name Heliyos calls the worker by, 1 to 48 characters of `a-z`, `0-9` and `_`. Defaults to one made from `name`. Cannot be changed later. example: account_researcher toolNames: type: array items: type: string maxLength: 200 maxItems: 500 description: >- Built-in tools the worker may use, by name. Up to 500. Defaults to none. actionIds: type: array items: $ref: '#/components/schemas/ObjectId' maxItems: 500 description: >- Workspace actions the worker may run. Each must be an action of this workspace. Up to 500. toolPolicy: type: object properties: readOnly: type: boolean description: '`true`: read only.' additionalProperties: false description: >- `{ readOnly }`: `true` lets the worker read but never change data. memory: type: object properties: enabled: type: boolean description: Memory on or off. additionalProperties: false description: >- `{ enabled }`: whether the worker keeps memory across runs. Defaults to on. resources: type: object properties: scope: type: string enum: - everything - org_knowledge - account_files - selected_files allKbFiles: type: boolean linkedKbFileIds: type: array items: type: string pattern: ^[0-9a-fA-F]{24}$ maxItems: 1000 fileIds: type: array items: type: string pattern: ^[0-9a-fA-F]{24}$ maxItems: 1000 additionalProperties: false allOf: - $ref: '#/components/schemas/WorkerResources' description: >- The files the worker reads. Merged over the defaults (`scope` `everything`, every knowledge base file). triggers: type: array items: $ref: '#/components/schemas/WorkerTriggerInput' maxItems: 50 description: What starts the worker, up to 50 entries. Defaults to none. schedule: type: object properties: cron: type: array maxItems: 20 items: type: string maxLength: 100 description: 5-field cron expressions. additionalProperties: false description: >- Legacy. Up to 20 cron expressions in `cron`. Use a `scheduled` trigger instead. required: - name additionalProperties: false example: name: Account researcher description: >- Researches a company before a first call and writes a brief on the record. instructions: >- When a meeting is booked with a new company, research it and add a note with its products, recent news and likely priorities. toolPolicy: readOnly: false triggers: - type: event events: - meeting.booked - type: scheduled match: schedule: 0 8 * * 1 timezone: Europe/Berlin responses: '201': description: The created worker, with the outcome of its schedule registration. 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/WorkerSaved' example: meta: message: Agent created. data: _id: 6720f3a1b2c3d4e5f6a7b8c9 organizationId: 66a0f1e2d3c4b5a697887766 name: Account researcher type: custom isActive: true isExcluded: false description: >- Researches a company before a first call and writes a brief on the record. instructions: >- When a meeting is booked with a new company, research it and add a note with its products, recent news and likely priorities. toolName: account_researcher toolNames: [] actionIds: [] toolPolicy: readOnly: false memory: enabled: true resources: scope: everything allKbFiles: true linkedKbFileIds: [] fileIds: [] triggers: - type: event events: - meeting.booked source: user - type: scheduled events: [] match: schedule: 0 8 * * 1 timezone: Europe/Berlin dependencies: [] source: user runtime: sandbox metadata: created: at: '2026-11-05T10:00:00.000Z' by: 66a0f1e2d3c4b5a697881111 updated: at: '2026-11-05T10:00:00.000Z' by: 66a0f1e2d3c4b5a697881111 createdAt: '2026-11-05T10:00:00.000Z' updatedAt: '2026-11-05T10:00:00.000Z' scheduleSync: created: - 6729c0d1e2f3a4b5c6d7e8f9 deleted: [] failed: [] '400': description: Validation failed 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: an action, file or dependency worker id is not this workspace's. Nothing is written. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '409': description: >- CONFLICT: a worker with this name already exists. 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: ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 WorkerResources: type: object description: The knowledge files the worker reads. properties: scope: type: string enum: - everything - org_knowledge - account_files - selected_files description: > The file scope picked in the Heliyos app: `everything` (the default), `org_knowledge` (knowledge base files), `account_files` (files on records) or `selected_files` (files you pick). Which knowledge base files the worker reads is set by `allKbFiles` and `linkedKbFileIds`. allKbFiles: type: boolean description: >- `true` links every knowledge base file of the workspace. When absent, every file is linked unless `linkedKbFileIds` names some. linkedKbFileIds: type: array maxItems: 1000 description: >- Knowledge base files linked to the worker. Each must be a file of this workspace. Up to 1,000. items: $ref: '#/components/schemas/ObjectId' fileIds: type: array maxItems: 1000 description: >- Other files picked for the worker. Each must be a file of this workspace. Up to 1,000. items: $ref: '#/components/schemas/ObjectId' WorkerTriggerInput: type: object description: One thing that starts the worker. required: - type properties: type: type: string enum: - task_created - mention - event - scheduled - webhook - schedule - playground description: > - `task_created`: the worker runs when a task is created. `match.taskType` limits it to some task types. - `mention`: the worker runs when someone mentions it in chat. Every active worker answers mentions, with or without this entry; `match.mentionPattern` is kept with it. - `event`: the worker runs on the named events in `events`, for example `task.created`, `deal.updated`, `email.received`, `meeting.completed` or `company.attribute_updated`. `*` means every event. An event name that Heliyos never emits never matches. - `scheduled`: the worker runs on a schedule. Put a 5-field cron in `match.schedule` (UTC unless `match.timezone` is set), or a one-time local time in `match.at` with `match.timezone`. - `webhook`: older spelling of `event`, with the event name in `match.webhookEvent`. Saved as `event`. - `schedule`: older spelling of `scheduled`. Saved as `scheduled`. - `playground`: used by test runs in the Heliyos app. Has no effect when set through the API. source: type: string enum: - default - user description: >- Accepted and ignored. Triggers you send are always saved with `source` `user`. events: type: array maxItems: 200 description: >- `event` triggers only: the event names to run on. Up to 200 names of up to 200 characters. items: type: string maxLength: 200 example: - deal.updated - meeting.completed match: type: object description: > Conditions and timing. These keys are stored; any other key is dropped: - `taskType` (array of strings): `task_created` only, the task types to run on. - `taskStatus` (string): a task status condition. - `mentionPattern` (string): `mention` only, text the mention must contain. - `webhookEvent` (string or array): `webhook` only, the event names. - `schedule` (string): `scheduled` only, a 5-field cron such as `0 8 * * 1-5`. - `at` (string): `scheduled` only, a one-time local wall time `YYYY-MM-DDTHH:MM:SS`. - `timezone` (string): an IANA zone such as `Europe/Berlin` for `schedule` or `at`. Default UTC. - `recurrence` (object): the Heliyos app's own description of the schedule, so its editor can reopen it. additionalProperties: true example: schedule: 0 8 * * 1-5 timezone: Europe/Berlin dependencies: type: array maxItems: 50 description: >- Ids of other workers in this workspace that must finish before this one starts. Up to 50. items: $ref: '#/components/schemas/ObjectId' WorkerSaved: allOf: - $ref: '#/components/schemas/Worker' - type: object properties: scheduleSync: $ref: '#/components/schemas/WorkerScheduleSync' 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: {} Worker: type: object properties: _id: $ref: '#/components/schemas/ObjectId' organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace the worker belongs to. name: type: string description: The worker's name, unique in the workspace. type: type: string enum: - default - custom description: >- `default`: built into every workspace. Only its instructions, description, icon, active flag, memory and its own triggers can change, and it cannot be deleted. `custom`: created by you, fully editable and deletable. isActive: type: boolean description: >- `false` pauses the worker: nothing starts it and Heliyos does not call it. icon: type: string description: The icon the Heliyos app shows for the worker. isExcluded: type: boolean description: >- `true` for older built-in workers that run on a separate pipeline. They are listed for reference, and Heliyos never calls them. description: type: string description: >- One line that tells Heliyos (and people) what the worker is for. Heliyos reads it to decide when to call the worker. instructions: type: string description: What the worker does and how, in Markdown. toolName: type: string description: >- The stable snake_case name Heliyos calls the worker by. Set on create and never changed. toolNames: type: array description: The built-in tools the worker may use, by name. items: type: string actionIds: type: array description: The workspace actions the worker may run. items: $ref: '#/components/schemas/ObjectId' toolPolicy: type: object description: Limits on what the worker may do. properties: readOnly: type: boolean description: '`true`: the worker may read but never change data.' memory: type: object properties: enabled: type: boolean description: '`true`: the worker keeps memory across runs.' resources: $ref: '#/components/schemas/WorkerResources' triggers: type: array description: >- What starts the worker. An empty list means it only runs when Heliyos or a person calls it. items: $ref: '#/components/schemas/WorkerTrigger' schedule: type: object description: Legacy cron list. Schedules live on `scheduled` triggers now. properties: cron: type: array items: type: string description: 5-field cron expressions. runtime: type: string enum: - sandbox - light description: How Heliyos runs the worker. Set by Heliyos, read-only. metadata: $ref: '#/components/schemas/AuditMetadata' createdAt: $ref: '#/components/schemas/Timestamp' updatedAt: $ref: '#/components/schemas/Timestamp' WorkerScheduleSync: type: object description: >- What happened to the worker's schedules after the save. The worker is saved even when a schedule fails, but a failed schedule never fires: check `failed`. properties: created: type: array description: >- Ids of the worker's schedules that are registered after this save, including ones that already existed. A one-time `at` in the past is skipped and not listed. items: type: string deleted: type: array description: >- Ids of schedules removed by this save because no trigger asks for them any more. items: type: string failed: type: array description: >- One line per schedule that could not be registered. Empty when every schedule is in place. items: type: string WorkerTrigger: type: object description: >- A stored trigger. Event subscriptions are stored as `event`, schedules as `scheduled`. properties: type: type: string description: >- `task_created`, `mention`, `event`, `scheduled` or `playground`. Workers saved long ago can still show `webhook` or `schedule`. source: type: string enum: - default - user description: >- `default`: built into a default worker. It stays when you change the worker's triggers. `user`: added by a person or the API, removable. events: type: array description: '`event` triggers: the subscribed event names.' items: type: string match: type: object additionalProperties: true description: Conditions and timing, as in the trigger input. dependencies: type: array description: Workers that must finish first. items: $ref: '#/components/schemas/ObjectId' 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. Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' 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.