Skip to content
Skip to main content

Notetaker configurations

Last updated:

A Notetaker configuration saves notetaker_settings defaults, such as display name, recording, summary, action items, and retention, alongside deduplication and dispatch policies. Nylas resolves these defaults again at dispatch, when it starts the bot. Configuration updates apply to Notetakers that are still awaiting dispatch. Once dispatched, each run keeps a snapshot of the settings it used.

Configurations are optional. You can pass notetaker_settings inline on every request instead; see Using Nylas Notetaker.

You can save defaults at several levels, from broadest to most specific. Each section below shows one example of when you’d use that level.

How Notetaker settings resolve

Each layer overrides the fields it sets, and Nylas merges the layers when it starts the bot, not when you create the Notetaker. Dispatch pauses follow a different rule: an active pause at any scope stops the bot. Grant configurations hold only the pause, never settings.
Diagram as text
  • Nylas: Platform defaults: The starting value for every field no layer sets.
  • Your app: Application configuration: POST /v3/notetakers/configs without a workspace_id, or retention in the Dashboard (Notetaker, then Settings). One per application. (Overridden by)
  • Your app: Workspace configuration: Applies to grants in the workspace. One per workspace. (Overridden by)
  • Your app: Calendar and series settings: notetaker_settings on calendar sync or a recurring event's sync. (Overridden by)
  • Your app: Per-Notetaker settings: notetaker_settings on the Notetaker request or a single event's sync. (Overridden by)
  • Nylas: Resolve at dispatch: For each field, the most specific layer that sets it wins.
    • Resolution rules: transcription_settings, messages, and video_output are replaced whole, not merged field by field.
    • Resolution rules: summary and action_items take effect only when transcription is on.
    • Resolution rules: deduplication_policy comes from the workspace configuration if one exists, else the application's. Lower layers can only opt out with disable.
    • Pause active at any scope → Bot doesn't dispatch: A future dispatch_disabled_until on the application, workspace, or grant configuration.
  • Nylas: Bot starts: It uses the settings in effect when it started. Later edits don't change a bot that's already running.

Set defaults across your application

Section titled “Set defaults across your application”

Example: you want every recording in your app to keep media for 7 days instead of the default of 14.

Make a POST /v3/notetakers/configs request with application_id set to your application ID and no workspace_id. Every Notetaker in your application inherits these defaults unless something more specific overrides them.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/notetakers/configs' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "application_id": "<APPLICATION_ID>",
    "display_name": "Company defaults",
    "notetaker_settings": {
      "name": "Acme Notetaker",
      "recording_type": "audio_video",
      "transcription": true,
      "summary": true,
      "retention_time": 604800
    },
    "deduplication_policy": "active"
  }'

You can have at most one application-level configuration per application. A second POST returns 409 Conflict.

Set defaults for one workspace

Section titled “Set defaults for one workspace”

Example: one of your customers wants deduplication on and a one-day retention window instead of the seven-day application default above.

A workspace is a grouping of grants (authenticated user accounts). Use one when one customer or team should behave differently than the rest of your application.

Create a workspace with POST /v3/workspaces:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/workspaces' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Acme Sales",
    "domain": "acme.com",
    "auto_group": true
  }'

When auto_group is true, new grants whose email domain matches the workspace’s domain are added automatically. You can also assign grants manually with POST /v3/workspaces/<WORKSPACE_ID>/manual-assign.

Then create a configuration for that workspace by passing workspace_id:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/notetakers/configs' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "workspace_id": "<WORKSPACE_ID>",
    "display_name": "Acme Sales defaults",
    "notetaker_settings": {
      "summary": true,
      "retention_time": 86400
    },
    "deduplication_policy": "active"
  }'

You can have at most one configuration per workspace. retention_time accepts 300 to 2,592,000 seconds (5 minutes to 30 days).

Set defaults for one calendar

Section titled “Set defaults for one calendar”

Example: a customer wants their Notetakers to use a custom display name on every meeting from one of their calendars.

Include notetaker_settings when you set up calendar sync. Nylas creates an internal configuration for that calendar. Update its settings through the calendar sync endpoint; the public configuration list and configuration CRUD endpoints don’t expose calendar configurations.

To inspect the calendar layer used by a Notetaker, request configuration details. Its scope is calendar.

Set defaults for one event

Section titled “Set defaults for one event”

Example: a customer wants audio only ("recording_type": "audio") on one specific event.

Include notetaker_settings when you set up event sync. Nylas manages these configurations through the sync endpoints, so they don’t appear in the public configuration list. In configuration details, a single-event or per-Notetaker layer has scope notetaker; a recurring-series layer has scope recurring_event. There is no event scope value.

Pause dispatch with a configuration

Section titled “Pause dispatch with a configuration”

Application, workspace, and grant configurations can also carry a dispatch policy. Set dispatch_disabled_until to an RFC 3339 timestamp and Nylas stops sending Notetakers to meetings for that scope until the timestamp passes, without touching calendar rules or scheduled Notetakers. Grant-scope configurations exist only for this purpose: they hold dispatch_disabled_until for one user and never contribute settings. See Pause Notetaker dispatch for the full behavior.

How settings combine

Section titled “How settings combine”

At dispatch, Nylas resolves settings from the most specific layer to the most general:

Per-Notetaker or single-event settings
  └─ Recurring-series configuration
       └─ Calendar configuration
            └─ Workspace configuration
                 └─ Application configuration
                      └─ Platform defaults

The most specific layer supplies each configured field. Omitted fields inherit from the next available parent. You create application and workspace configurations directly; Nylas manages calendar and event settings through their sync endpoints. Inline notetaker_settings on a Notetaker request supplies its most specific settings.

Nylas then applies dependency rules to the combined settings. For example, if a child configures summary: true but inherits transcription: false, the effective summary value is false. Action items also require transcription. The configured values stay unchanged, so enabling transcription later can make those features effective on future dispatches.

Composite settings are replaced whole

Section titled “Composite settings are replaced whole”

Three fields inside notetaker_settings are objects that Nylas treats as a single value rather than merging field by field: transcription_settings, messages, and video_output. When a more specific layer sets one of them, it replaces the parent’s object entirely. To change one field inside, send the whole object you want to end up with; to inherit the parent’s value unchanged, omit the field. Each of the 3 has its own way to clear an inherited value, described on its page: transcription settings, custom announcements, and custom video output.

Inspect resolved settings

Section titled “Inspect resolved settings”

Add ?config_details=true to an individual Notetaker GET request:

curl --request GET \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>?config_details=true' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

The response includes config_resolution alongside the effective notetaker_settings:

  • fields identifies the source configuration for each setting and any dependency normalization.
  • layers shows each layer’s own configured settings before inheritance or normalization, using public fields.

For a Notetaker awaiting dispatch, these details reflect the current configuration hierarchy. After dispatch, they reflect the captured resolution for that run. Later parent changes don’t rewrite that snapshot. Older runs without a captured resolution might not return config_resolution.

The API omits config_resolution unless you request it. debug=true also includes it; config_details=true requests configuration details specifically.

Update or delete a configuration

Section titled “Update or delete a configuration”

PATCH /v3/notetakers/configs/<CONFIG_ID> merges fields, so sending just one field leaves the rest untouched. To remove a local settings override and inherit again, set that field to null, for example {"notetaker_settings":{"summary":null}}. Sending "notetaker_settings": null clears all local settings overrides.

Updates are versioned; the version field increments on every change. To see past versions, add ?include=history to a GET /v3/notetakers/configs/<CONFIG_ID>.

DELETE /v3/notetakers/configs/<CONFIG_ID> removes a configuration. Notetakers that were using it fall back to the next level above (your application configuration, or the platform defaults).

To list configurations, use GET /v3/notetakers/configs.

Override on a single request

Section titled “Override on a single request”

Example: a customer wants to disable summaries for one meeting.

A configuration sets defaults. To override them on one Notetaker, pass notetaker_settings on your POST /v3/notetakers request. The request supplies the most specific configured values. Omitted values come from the inheritance chain, then dependency rules determine the effective settings.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "meeting_link": "https://meet.google.com/abc-xyz-123",
    "notetaker_settings": {
      "summary": false
    }
  }'

If you have a configuration you want to use without copying its fields, pass config_id on the request instead of inline notetaker_settings. Send one or the other on a given request; mixing config_id with inline notetaker_settings is unsupported.

curl --request POST \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "meeting_link": "https://meet.google.com/abc-xyz-123",
    "config_id": "<CONFIG_ID>"
  }'
Section titled “Related topics”