NYnylas
Notetaker Configurations

Create a Notetaker Configuration

Changed on

Creates a new configuration for the application. Configurations define reusable settings that Notetakers inherit through a hierarchical chain.

The scope of the configuration is determined by which context fields you provide:

  • application_id only → application scope
  • workspace_id → workspace scope
  • grant_id → grant scope. Grant configurations are policy-only: they support dispatch_disabled_until for dispatch suppression and reject notetaker_settings and deduplication_policy.
  • Other scopes (calendar, recurring event) are created automatically by the calendar and event sync endpoints.

workspace_id and grant_id are mutually exclusive.

Calendar and event settings are managed through their sync endpoints, not the public configuration endpoints.

To upload a custom video output image, send the request as multipart/form-data with the JSON body in a part named config and the image in a file part referenced by notetaker_settings.video_output.file_key. Small images (up to 1,376,256 decoded bytes) can be sent inline on application/json requests using video_output.media_type and video_output.data instead.

post/v3/notetakers/configs

Request

Request body

application_idstring

Optional. If provided, must match the application ID associated with your API key — Nylas infers the application from your credentials when this field is omitted.

workspace_idstring

The workspace ID. Provide to create a workspace-scope configuration. Mutually exclusive with grant_id.

grant_idstring

The grant ID. Provide to create a policy-only grant configuration for dispatch suppression. Grant configurations support only dispatch_disabled_until — requests that include notetaker_settings or deduplication_policy return 400 Bad Request. The configuration's config_id is the grant ID. Mutually exclusive with workspace_id.

display_namestring

A human-readable name to identify this configuration.

deduplication_policy'active' | 'inactive'

Controls deduplication for an application or workspace configuration. Grant configurations do not accept this field.

dispatch_disabled_untilstring date-time nullable

An RFC 3339 timestamp that suppresses Notetaker dispatch while it's in the future. Accepted on application, workspace, and grant configurations. While active, Nylas rejects immediate join requests and doesn't dispatch scheduled Notetakers governed by this configuration. See Pause Notetaker dispatch.

Example request

{
  "application_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "workspace_id": "ws-12345",
  "grant_id": "e19f8e1a-eb1c-41c0-b6d6-a24a6a9d6b28",
  "display_name": "Company defaults",
  "notetaker_settings": {
    "name": "Acme Notetaker",
    "recording_type": "audio_video",
    "transcription": true,
    "transcription_settings": {
      "expected_languages": [
        "en",
        "es"
      ],
      "fallback_language": "en",
      "keywords": [
        "Nylas",
        "AssemblyAI"
      ],
      "use_speaker_names_as_keywords": true
    },
    "summary": true,
    "summary_settings": {
      "custom_instructions": "Summarize in bullet points."
    },
    "action_items": true,
    "action_items_settings": {
      "custom_instructions": "Only return the 5 most important action items."
    },
    "leave_after_silence_seconds": 600,
    "messages": {
      "on_join": [
        {
          "type": "text",
          "content": "👋 Hey team! I'm your AI notetaker — here to capture the key points.",
          "send_after_ms": 5000
        }
      ],
      "on_participant_join": [
        {
          "type": "text",
          "content": "👋 Welcome! Recording and transcription are running.",
          "debounce_ms": 3000
        }
      ]
    },
    "video_output": {
      "file_key": "avatar",
      "media_type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==",
      "size": 184320,
      "preview_url": "https://storage.googleapis.com/...",
      "preview_url_expires_at": 1786128794
    },
    "retention_time": 604800
  },
  "deduplication_policy": "active",
  "dispatch_disabled_until": "2026-08-01T00:00:00Z"
}

Response

Success. Returns the created configuration.

request_idstring

The request ID.

Example response

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88"
}

Changes

  • a669a04b02baRevision changes
    • breaking

      the request property became not nullable

    • breaking

      the request property / became not nullable

  • 763d6b969cd7Revision changes
    • info

      added the optional property / to the response with the status