Migrate to notetaker_settings

The top-level name and meeting_settings fields on Notetaker requests are now deprecated in favor of a single notetaker_settings object. This page walks through the swap for every endpoint that accepts those fields.

You don’t have to create a configuration to make this change. The simplest migration is a like-for-like swap: move what you already pass in name and meeting_settings into notetaker_settings on the same request. Inline settings keep working the same way they always have. The request payload is the only thing that changes. Configurations are useful when you want shared defaults across many Notetakers, but they’re opt-in.

Webhook payloads still carry meeting_settings. While requests have moved to notetaker_settings, the resolved settings on the notetaker.created, notetaker.updated, notetaker.meeting_state, and notetaker.media webhook payloads continue to appear inside meeting_settings for backwards compatibility. Webhook consumers should keep reading from meeting_settings. The deduplication shape on webhooks is meeting_settings.deduplication_settings (an object with scope, key, and workspace_id), which is the resolved form of the request-side deduplication_policy string.

What’s changing

• name (top-level) → notetaker_settings.name
• meeting_settings.* → notetaker_settings.* (the field names inside are identical, except that video_recording and audio_recording become recording_type)
• meeting_settings and name still work today, but new features (such as deduplication_policy) are only available through notetaker_settings or config_id.
• You cannot mix legacy fields and new fields in the same request. If both meeting_settings (or top-level name) and notetaker_settings are present, Nylas returns a 400 Bad Request.

Field mapping

Most field names and types inside meeting_settings carry over to notetaker_settings unchanged. The one exception is recording: the two booleans collapse into a single recording_type enum.

Legacy field	New field	Notes
name (top-level)	notetaker_settings.name	Moves inside the settings object.
meeting_settings.video_recording and meeting_settings.audio_recording	notetaker_settings.recording_type	Two booleans become one enum. audio_video replaces both set to true; audio replaces video_recording: false with audio_recording: true.
meeting_settings.transcription	notetaker_settings.transcription
meeting_settings.transcription_settings.*	notetaker_settings.transcription_settings.*	Language and keyword hints. See Transcription settings.
meeting_settings.summary	notetaker_settings.summary
meeting_settings.summary_settings.custom_instructions	notetaker_settings.summary_settings.custom_instructions
meeting_settings.action_items	notetaker_settings.action_items
meeting_settings.action_items_settings.custom_instructions	notetaker_settings.action_items_settings.custom_instructions
meeting_settings.leave_after_silence_seconds	notetaker_settings.leave_after_silence_seconds
meeting_settings.messages	notetaker_settings.messages	Custom chat announcements. See Custom announcements.

Don’t send recording_type together with video_recording or audio_recording in the same notetaker_settings object; Nylas returns 400 Bad Request with the message recording_type cannot be combined with audio_recording or video_recording.

Four fields exist only on the new shape and have no legacy equivalent: retention_time and video_output inside notetaker_settings, deduplication_policy alongside it, and config_id on the request.

Migrate a join request

Endpoints: POST /v3/grants/{grant_id}/notetakers and POST /v3/notetakers.

Before (legacy)

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",
    "name": "Acme Notetaker",
    "meeting_settings": {
      "video_recording": true,
      "audio_recording": true,
      "transcription": true,
      "summary": true,
      "summary_settings": {
        "custom_instructions": "Summarize in bullet points."
      },
      "leave_after_silence_seconds": 600
    }
  }'

After (notetaker_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": {
      "name": "Acme Notetaker",
      "recording_type": "audio_video",
      "transcription": true,
      "summary": true,
      "summary_settings": {
        "custom_instructions": "Summarize in bullet points."
      },
      "leave_after_silence_seconds": 600
    }
  }'

The same swap applies to PATCH /v3/grants/{grant_id}/notetakers/{notetaker_id} when updating a scheduled Notetaker. Don’t forget those requests: a PATCH that still sends top-level name alongside notetaker_settings returns the same 400.

Migrate a calendar sync request

Endpoints: POST /v3/grants/{grant_id}/calendars and PUT /v3/grants/{grant_id}/calendars/{calendar_id}.

The name and meeting_settings fields live inside the notetaker object on calendar requests. Move them into notetaker_settings within the same object.

Before (legacy)

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {
      "name": "Sales Calendar Bot",
      "meeting_settings": {
        "video_recording": true,
        "audio_recording": true,
        "transcription": true,
        "summary": true,
        "summary_settings": {
          "custom_instructions": "Use the MEDPIC sales methodology."
        }
      },
      "rules": {
        "event_selection": ["internal", "own_events"],
        "participant_filter": {
          "participants_gte": 3,
          "participants_lte": 10
        }
      }
    }
  }'

After (notetaker_settings)

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/calendars/<CALENDAR_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {
      "notetaker_settings": {
        "name": "Sales Calendar Bot",
        "recording_type": "audio_video",
        "transcription": true,
        "summary": true,
        "summary_settings": {
          "custom_instructions": "Use the MEDPIC sales methodology."
        }
      },
      "rules": {
        "event_selection": ["internal", "own_events"],
        "participant_filter": {
          "participants_gte": 3,
          "participants_lte": 10
        }
      }
    }
  }'

The rules object (event selection and participant filters) is unchanged. Only the settings block moves.

Migrate an event sync request

Endpoints: POST /v3/grants/{grant_id}/events and PUT /v3/grants/{grant_id}/events/{event_id}.

Same pattern as calendar sync: the notetaker object holds the settings.

Before (legacy)

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {
      "name": "Finance Meeting Notetaker",
      "meeting_settings": {
        "video_recording": true,
        "audio_recording": true,
        "transcription": true,
        "action_items": true,
        "action_items_settings": {
          "custom_instructions": "Only return the 5 most important action items."
        },
        "leave_after_silence_seconds": 360
      }
    }
  }'

After (notetaker_settings)

curl --request PUT \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/events/<EVENT_ID>?calendar_id=<CALENDAR_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker": {
      "notetaker_settings": {
        "name": "Finance Meeting Notetaker",
        "recording_type": "audio_video",
        "transcription": true,
        "action_items": true,
        "action_items_settings": {
          "custom_instructions": "Only return the 5 most important action items."
        },
        "leave_after_silence_seconds": 360
      }
    }
  }'

What you get after migrating

Moving to notetaker_settings unlocks features that the legacy fields don’t support:

• deduplication_policy: opt a calendar sync or single event out of deduplication. See Notetaker deduplication.
• retention_time: keep media for longer or shorter than the 14-day default. See Notetaker retention policies.
• video_output: the image the bot shows as its camera feed. See Notetaker custom video output.
• config_id: reference a shared configuration instead of repeating the same settings on every request.
• Future additions: new fields added to Notetaker will land on notetaker_settings, not on meeting_settings.