> ## 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 notification settings > Changes the workspace's notification settings, creating them the first time. Send at least one field. Each field you send replaces that setting completely; fields you leave out are kept. - `eventTypes` is the full list of notifying events. To add one event, read the current list, add to it and send the whole list back. - `notifyEmails` is the full recipient list. Changing who receives notifications needs an owner or admin (an API key counts as an admin). Sending the stored list back unchanged is allowed for anyone who can edit the settings. A list can grow to at most 10 addresses. - The first save of a workspace that had no settings starts from notifications on, no recipients and no events, then applies what you sent. > [!NOTE] > > Notification emails can contain record names and summaries. Only add addresses that should see > that information. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_notification_settings_update`](https://docs.heliyos.ai/mcp/tools/notification-settings#heliyos-notification-settings-update). ## OpenAPI ````yaml /api-reference/openapi.json patch /v1/platform/notification-settings 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/notification-settings: patch: tags: - Notification settings summary: Update notification settings description: >- Changes the workspace's notification settings, creating them the first time. Send at least one field. Each field you send replaces that setting completely; fields you leave out are kept. - `eventTypes` is the full list of notifying events. To add one event, read the current list, add to it and send the whole list back. - `notifyEmails` is the full recipient list. Changing who receives notifications needs an owner or admin (an API key counts as an admin). Sending the stored list back unchanged is allowed for anyone who can edit the settings. A list can grow to at most 10 addresses. - The first save of a workspace that had no settings starts from notifications on, no recipients and no events, then applies what you sent. operationId: updateNotificationSettings parameters: [] requestBody: required: true content: application/json: schema: type: object properties: notifyEmails: type: array items: type: string format: email minItems: 0 description: >- The complete new recipient list. Replaces the current one. Each item must be a valid email address (surrounding spaces are trimmed). At most 10 addresses when you add any. Send `[]` to remove every recipient, which stops notifications. example: - ana.lopez@example.com - revops@example.com eventTypes: type: array items: $ref: '#/components/schemas/NotificationEventType' minItems: 0 description: >- The complete new list of notifying events, each `{ type, frequency }`. Replaces the current list. Send `[]` to turn off every event. isActive: type: boolean description: Turns every notification email on (`true`) or off (`false`). example: true additionalProperties: false minProperties: 1 examples: addEvent: summary: Turn on approval emails and a daily task digest value: eventTypes: - type: deal.approval frequency: immediate - type: task.created frequency: daily - type: organization.daily_summary frequency: daily pause: summary: Pause all notification emails value: isActive: false responses: '200': description: The saved settings. 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/NotificationSettings' example: meta: message: Notification settings saved successfully. data: id: 6721a9e0c4b5d6e7f8a9b0c1 organizationId: 66a0f1e2d3c4b5a697887766 notifyEmails: - ana.lopez@example.com - revops@example.com eventTypes: - type: deal.approval frequency: immediate - type: task.created frequency: daily - type: organization.daily_summary frequency: daily isActive: true metadata: created: at: '2026-10-02T08:15:00.000Z' by: 66a0f1e2d3c4b5a697881111 updated: at: '2026-11-05T11:02:00.000Z' by: 66a0f1e2d3c4b5a697881111 '400': description: >- VALIDATION_FAILED: an empty body, an unknown event type or frequency, an invalid email address, or a recipient list that grows past 10 addresses. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: >- FORBIDDEN_ACTION: notifyEmails changed by a member who is not an owner or admin. Nothing is written. 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: NotificationEventType: type: object required: - type - frequency properties: type: type: string enum: - task.created - task.updated - deal.created - deal.updated - deal.approval - leadset.created - leadset.records.available - organization.daily_summary - scout.signal_detected - integration.not_synced description: > The event that notifies: - `task.created`: a task was created. - `task.updated`: a task changed. - `deal.created`: a deal was created. - `deal.updated`: a deal changed. - `deal.approval`: a deal change is waiting for review. - `leadset.created`: a lead set was created. - `leadset.records.available`: new records are ready in a lead set. - `organization.daily_summary`: the workspace's daily briefing email. Sent only when its frequency is `daily`. - `scout.signal_detected`: a Scout found a signal. Always sent at once: a `daily` frequency is saved as `immediate`. - `integration.not_synced`: a connected integration stopped syncing. Always sent, even when notifications are off or this event is not in the list (see `notifyEmails`). frequency: type: string enum: - immediate - daily description: | - `immediate`: one email per event, sent when it happens. - `daily`: collected and sent together in the daily digest. NotificationSettings: type: object properties: id: allOf: - $ref: '#/components/schemas/ObjectId' description: The settings document's id. organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace the settings belong to. notifyEmails: type: array description: >- Every address notification emails go to. Notifications are sent only when this list has at least one address, with one exception: an `integration.not_synced` email goes to the person whose integration failed when the list is empty. items: type: string format: email eventTypes: type: array description: >- The events that send notifications, each with its frequency. An event not listed sends nothing. items: $ref: '#/components/schemas/NotificationEventType' isActive: type: boolean description: >- The master switch. `false` stops every notification email except `integration.not_synced`. Events already collected for the daily digest are discarded if it is `false` when the digest goes out. 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 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.