> ## 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. # List triggers > Returns the catalogue of triggers a worker can be set to run on: the events it can subscribe to, mentions and schedules. Use it to fill `triggers` on **Create a worker** and **Update a worker**. The whole catalogue comes back in one response; it is not paged. Every workspace has the same shared triggers. A workspace can also have entries of its own, listed after the shared ones; an own entry with the same `name` as a shared one replaces it. **From catalogue entry to worker trigger.** | Catalogue entry | Trigger object on the worker | | --- | --- | | `kind` `event`, for example `deal.updated` | `{ "type": "event", "events": ["deal.updated"] }`. One trigger can list several event names; `"*"` means every event. | | `kind` `mention` (`mention`) | `{ "type": "mention" }`. Every active worker answers mentions, with or without it. | | `kind` `schedule` (`schedule`) | `{ "type": "scheduled", "match": { "schedule": "0 8 * * 1-5", "timezone": "Europe/Berlin" } }` for a repeating 5-field cron, or `match.at` (`YYYY-MM-DDTHH:MM:SS` local time) with `match.timezone` for one run. | | Not in the catalogue | `{ "type": "task_created" }` runs on every new task; `match.taskType` limits it to some task types. | **Things to know.** - The API does not check event names against this catalogue when you save a worker. A name that is not in it never fires. - Triggers with an `integration` only fire while that app is connected (`integration.connected`). - `company.attribute_updated`, `people.attribute_updated` and `deal.attribute_updated` watch fields picked in the Heliyos app. Created through the API, they run on a change to any field of that object. - A trigger with `type` `scheduled` is registered when you save the worker; check `scheduleSync` in that response. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_triggers_list`](https://docs.heliyos.ai/mcp/tools/workers-triggers-and-tools#heliyos-triggers-list), [`heliyos_workers_tools_list`](https://docs.heliyos.ai/mcp/tools/workers-triggers-and-tools#heliyos-workers-tools-list). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/platform/workers/triggers 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/workers/triggers: get: tags: - Workers and runs summary: List triggers description: >- Returns the catalogue of triggers a worker can be set to run on: the events it can subscribe to, mentions and schedules. Use it to fill `triggers` on **Create a worker** and **Update a worker**. The whole catalogue comes back in one response; it is not paged. Every workspace has the same shared triggers. A workspace can also have entries of its own, listed after the shared ones; an own entry with the same `name` as a shared one replaces it. **From catalogue entry to worker trigger.** | Catalogue entry | Trigger object on the worker | | --- | --- | | `kind` `event`, for example `deal.updated` | `{ "type": "event", "events": ["deal.updated"] }`. One trigger can list several event names; `"*"` means every event. | | `kind` `mention` (`mention`) | `{ "type": "mention" }`. Every active worker answers mentions, with or without it. | | `kind` `schedule` (`schedule`) | `{ "type": "scheduled", "match": { "schedule": "0 8 * * 1-5", "timezone": "Europe/Berlin" } }` for a repeating 5-field cron, or `match.at` (`YYYY-MM-DDTHH:MM:SS` local time) with `match.timezone` for one run. | | Not in the catalogue | `{ "type": "task_created" }` runs on every new task; `match.taskType` limits it to some task types. | **Things to know.** - The API does not check event names against this catalogue when you save a worker. A name that is not in it never fires. - Triggers with an `integration` only fire while that app is connected (`integration.connected`). - `company.attribute_updated`, `people.attribute_updated` and `deal.attribute_updated` watch fields picked in the Heliyos app. Created through the API, they run on a change to any field of that object. - A trigger with `type` `scheduled` is registered when you save the worker; check `scheduleSync` in that response. operationId: listWorkerTriggers parameters: [] responses: '200': description: Every trigger in the catalogue. 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: type: object properties: triggers: type: array description: >- The shared triggers by name, then the workspace's own by name. items: $ref: '#/components/schemas/WorkerTriggerCatalogEntry' example: meta: message: Successful request data: triggers: - _id: 6710a1b2c3d4e5f6a7b8c901 organizationId: null name: deal.attribute_updated kind: event label: Deal attribute changed description: >- Chosen deal fields changed. Pick the pipeline (schema) and the attributes to watch. objectType: deals source: platform selectsAttributes: true createdAt: '2026-09-01T08:00:00.000Z' updatedAt: '2026-11-01T08:00:00.000Z' - _id: 6710a1b2c3d4e5f6a7b8c902 organizationId: null name: mention kind: mention label: '@mention' description: A person mentioned the worker in a comment or note. objectType: null source: platform createdAt: '2026-09-01T08:00:00.000Z' updatedAt: '2026-11-01T08:00:00.000Z' - _id: 6710a1b2c3d4e5f6a7b8c903 organizationId: null name: schedule kind: schedule label: Schedule description: >- Runs once at a date and time, or on a repeating schedule you configure on the worker. objectType: null source: internal createdAt: '2026-09-01T08:00:00.000Z' updatedAt: '2026-11-01T08:00:00.000Z' - _id: 6710a1b2c3d4e5f6a7b8c904 organizationId: null name: task.created kind: event label: Task created description: A task was created. objectType: task source: platform createdAt: '2026-09-01T08:00:00.000Z' updatedAt: '2026-11-01T08:00:00.000Z' - _id: 6710a1b2c3d4e5f6a7b8c905 organizationId: null name: typeform.response kind: event label: Typeform response description: >- A form was submitted. The answers the form maps are already saved to the company, person and, when the form creates deals, the deal. Your own instructions say what to do with them. objectType: company source: typeform provider: typeform providerRef: TYPEFORM_NEW_RESPONSE integration: title: Typeform iconSrc: https://cdn.example.com/icons/typeform.svg connected: false createdAt: '2026-09-01T08:00:00.000Z' updatedAt: '2026-11-01T08:00:00.000Z' '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_ACTION: you cannot view workers.' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: WorkerTriggerCatalogEntry: type: object additionalProperties: true description: One trigger a worker can be set to run on. properties: _id: $ref: '#/components/schemas/ObjectId' organizationId: allOf: - $ref: '#/components/schemas/ObjectId' nullable: true description: >- `null` for the triggers every workspace has. A workspace's own entry carries its id. name: type: string description: >- The trigger's name. For a `kind` `event` entry, this is the event name you put in a trigger's `events`, for example `deal.updated`. kind: type: string enum: - event - mention - schedule description: > How the entry maps to a trigger on **Create a worker** and **Update a worker**: - `event`: add `name` to the `events` of a trigger with `type` `event`. - `mention`: a trigger with `type` `mention`. Every active worker answers mentions anyway. - `schedule`: a trigger with `type` `scheduled` and a cron or one-time `at` in `match`. label: type: string description: A short name for the trigger, as the Heliyos app shows it. description: type: string description: When the trigger fires, in a sentence. objectType: type: string nullable: true description: >- What the event is about: `interaction` (an email or meeting), `task`, `company`, `people`, `deals`, `note`, `baseschema` (an object's fields), `review`, `scout` or `signal`. `null` for `mention` and `schedule`. source: type: string description: >- Where the event comes from. `platform`: a change made in Heliyos, by a person, the API or a worker. `internal`: Heliyos's own background work, such as inbox sync or research. Any other value names the service that delivers the event. Informational: read `integration` to know whether a connected app is needed. provider: type: string description: >- A key for the app that delivers the event. Present on entries that have `integration`. providerRef: type: string description: >- The app's own name for the event, on entries that come from a connected app. selectsAttributes: type: boolean description: >- `true` on `company.attribute_updated`, `people.attribute_updated` and `deal.attribute_updated`: in the Heliyos app you pick the fields to watch. The API stores only the `match` keys listed on **Create a worker**, so such a subscription created through the API runs when any field of that object changes. isActive: type: boolean description: Absent or `true`. Inactive entries are not listed. integration: $ref: '#/components/schemas/WorkerIntegrationLink' createdAt: $ref: '#/components/schemas/Timestamp' updatedAt: $ref: '#/components/schemas/Timestamp' 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 WorkerIntegrationLink: type: object description: >- The connected app that delivers this trigger or performs this action. Present only when one does; Heliyos's own triggers and tools have none. properties: title: type: string description: >- The app's name, for example `Gmail`, `Outlook`, `Google Drive`, `OneDrive`, `HubSpot` or `Typeform`. Where two apps can do the job (email and calendar through Gmail or Outlook), the connected one is named; with neither connected, the first one is. iconSrc: type: string description: The app's logo URL. Absent when Heliyos has no logo for it. connected: type: boolean description: >- `true` when the workspace has this app connected and working now. While it is `false`, the trigger does not fire and the action cannot work. Connect the app in Heliyos first. 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.