# Create a Notetaker Configuration

> **POST** `https://api.us.nylas.com/v3/notetakers/configs`

Source: https://developer.nylas.com/docs/reference/api/notetaker-configurations/create-notetaker-config/

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](/docs/v3/notetaker/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](/docs/v3/notetaker/custom-video-output/),
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.

**Authentication:** NYLAS_API_KEY

## Request body

Content-Type: application/json

- `application_id` (string) - 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_id` (string) - The workspace ID. Provide to create a workspace-scope configuration.
Mutually exclusive with `grant_id`.
- `grant_id` (string) - The grant ID. Provide to create a policy-only grant configuration for
[dispatch suppression](/docs/v3/notetaker/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_name` (string) - A human-readable name to identify this configuration.
- `notetaker_settings` (object) - Flat Notetaker settings for the configuration system. Omitted fields inherit from
the parent configuration. After inheritance, dependency rules determine effective
settings: summary and action_items require transcription. Nylas captures effective
settings at dispatch; later parent edits do not rewrite an existing run's snapshot.

Cannot be used together with the legacy `name` and `meeting_settings` fields.
  - `name` (string) - The display name shown when the Notetaker joins a meeting.
  - `recording_type` (string) - What Notetaker records. `audio_video` produces an MP4 recording of the meeting's
video and audio. `audio` produces an MP3 audio-only recording and does not capture
video. Transcription, summaries, and action items work with either value. When no
level of the configuration hierarchy sets it, Notetaker records audio and video.
  - `transcription` (boolean) - When `true`, Notetaker transcribes the meeting's audio.
  - `transcription_settings` (object, nullable) - Optional settings that tune how Notetaker transcribes audio. `transcription` must be
`true` for these settings to take effect. Provide any combination of the fields below.

The fields fall into two independent groups:

- **Language hints** (`expected_languages`, `fallback_language`) constrain automatic
  language detection. This declares the languages you expect; it does not translate
  transcripts or force the recording into a specific language.
- **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward
  domain-specific terms such as names, acronyms, and product names.

Set on individual Notetakers, on calendar sync, on event sync, or on a configuration.
When set on a configuration or calendar, scheduled Notetakers inherit the value unless
the request overrides it. Send `null` or `{}` to clear inherited settings and return to
default transcription behavior.

See [Set transcription languages](/docs/v3/notetaker/transcription-settings/) for
supported language codes and validation rules.
    - `expected_languages` (array) - Language codes the audio is expected to contain. Optional. When provided, it must
contain at least one supported code and cannot be `null` or empty. When omitted,
transcription considers all supported languages.
    - `fallback_language` (string) - Language to use if Notetaker does not detect one of the `expected_languages`. Optional.
When `expected_languages` is set, the fallback must be one of those codes. When
`expected_languages` is omitted, transcription considers all supported languages and
the fallback may be any supported code. When `fallback_language` is omitted, the
transcriber auto-detects the language. The field is not stored, so responses do not
return it.
    - `keywords` (array) - Domain-specific terms that bias transcription toward recognizing them correctly, such
as names, acronyms, and product names. Optional. Up to 200 terms; each term must be
1 to 200 characters and cannot contain control characters. Cannot be `null`.
    - `use_speaker_names_as_keywords` (boolean) - When `true`, Notetaker adds known speaker names to the keyword set so they are
transcribed accurately. Optional. Cannot be `null`.
  - `summary` (boolean) - When `true`, Notetaker generates a summary of the meeting. Requires
`transcription` to also be `true`.
  - `summary_settings` (object)
    - `custom_instructions` (string) - Custom instructions for the AI summary model.
  - `action_items` (boolean) - When `true`, Notetaker generates a list of action items. Requires
`transcription` to also be `true`.
  - `action_items_settings` (object)
    - `custom_instructions` (string) - Custom instructions for the AI action items model.
  - `leave_after_silence_seconds` (integer) - Seconds of continuous silence after which the Notetaker automatically leaves
the meeting. Must be between 10 and 3600 seconds (1 hour).
  - `messages` (object) - Custom announcements the Notetaker bot posts to the meeting chat. Use this to
greet attendees when the bot joins, or to acknowledge new participants as they
arrive. Messages are optional; when omitted, the bot only posts the default
recording-and-transcription notice described in [Using Nylas Notetaker](/docs/v3/notetaker/).

Like other `notetaker_settings` fields, `messages` participates in the
configuration hierarchy and uses whole-object override semantics: the most
specific layer that sets `messages` completely replaces the parent's value
(there is no per-message merging). See [Custom announcements](/docs/v3/notetaker/custom-announcements/)
for the full inheritance model.
    - `on_join` (array) - Messages the bot sends shortly after it joins the meeting. Each message has
its own configurable delay measured from the moment the bot joins. Up to
10 messages per trigger.
      - `type` (string) **(required)** - The message format. Currently only `text` is supported. Plain-text content
is preferred; any HTML tags in `content` are stripped before the message
is sent.
      - `content` (string) **(required)** - The message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
`content` becomes empty after sanitization are rejected with a validation
error.
      - `send_after_ms` (integer) **(required)** - Delay in milliseconds between the moment the bot joins the meeting and
the moment this message is posted. Each `on_join` message is scheduled
independently against its own delay; messages are posted in the order
their delays expire.
    - `on_participant_join` (array) - Messages the bot sends when a new participant joins the meeting. Each message
uses a trailing debounce window — if another participant joins before the
window expires, the timer resets and only one message is posted per burst of
joins. Up to 10 messages per trigger.
      - `type` (string) **(required)** - The message format. Currently only `text` is supported. Plain-text content
is preferred; any HTML tags in `content` are stripped before the message
is sent.
      - `content` (string) **(required)** - The message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
`content` becomes empty after sanitization are rejected with a validation
error.
      - `debounce_ms` (integer) **(required)** - Trailing debounce window in milliseconds. When a participant joins, the
bot waits this long before posting the message. If another participant
joins inside the window, the timer resets — the message is only posted
once the window expires without another join event. This collapses a
burst of nearly-simultaneous joins into a single announcement.
  - `video_output` (object) - A static image the Notetaker bot shows as its camera feed when it joins a meeting,
instead of a blank tile. Sometimes called the bot avatar. Supported on Google Meet,
Microsoft Teams, and Zoom; on other providers the bot joins without showing the image.
Author images at a 16:9 aspect ratio. Text in the image appears mirrored in the
recording.

Upload the image in one of two ways:

- **Multipart** (recommended): send the request as `multipart/form-data` and set
  `file_key` to the name of the file part that contains the image. The JSON part must be
  named `config` on the configuration endpoints and `notetaker` on the Notetaker
  endpoints. File parts up to 4 MiB.
- **JSON + base64**: send `media_type` and `data` together on a plain `application/json`
  request. The decoded image must be 1,376,256 bytes (about 1.31 MB) or smaller.

Accepted formats are PNG, JPEG, and static WebP, up to 3840x2160 pixels and no more than
8,294,400 total pixels. The format is detected from the file content, not the declared
content type.

On `PATCH`, omitting `video_output` preserves the existing image, sending a new image
replaces it, and sending an empty object (`{}`) disables video output at that layer.

Accepted when you create or update a configuration or a Notetaker. Not supported on
calendar sync or event sync requests. See
[Notetaker custom video output](/docs/v3/notetaker/custom-video-output/).
    - `file_key` (string) - The name of the multipart file part that contains the image. Only valid on
`multipart/form-data` requests, must reference exactly one file part, and cannot be
combined with `media_type` or `data`.
    - `media_type` (string) - The image MIME type. On a JSON write, required together with `data` and must match
the actual file content. Always returned in responses.
    - `data` (string) - The base64-encoded image bytes. Only valid on `application/json` requests, required
together with `media_type`, and must decode to 1,376,256 bytes or smaller.
    - `size` (integer) - The stored image size in bytes. Read-only; rejected on writes.
    - `preview_url` (string) - A signed URL for previewing the stored image. Valid for 1 hour; fetch the
configuration again to get a fresh URL. Read-only; rejected on writes.
    - `preview_url_expires_at` (integer) - When `preview_url` expires, as a Unix timestamp in seconds. Read-only; rejected
on writes.
  - `retention_time` (integer) - How long Notetaker media (recording, transcript, summary, action items, and
thumbnail) is kept before Nylas automatically deletes it, in seconds. The
clock starts when the media is first stored after the meeting ends. Defaults
to 1,209,600 seconds (14 days). Like other `notetaker_settings` fields, the
effective value is resolved from the configuration hierarchy — set it on an
application or workspace configuration for a new default, or override it on
a single Notetaker to extend or shrink retention just for that bot.
- `deduplication_policy` (string) - Controls deduplication for an application or workspace configuration.
Grant configurations do not accept this field.
- `dispatch_disabled_until` (string, 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](/docs/v3/notetaker/dispatch-suppression/).

## Responses

### 201 - Success. Returns the created configuration.

- `request_id` (string) - The request ID.
- `data` (object)
  - `config_id` (string) - The unique identifier for the configuration.
  - `application_id` (string) - The application ID that owns this configuration.
  - `scope` (string) - The scope of a configuration exposed by the public configuration endpoints.
Grant configurations carry dispatch_disabled_until and never contribute settings.
Calendar, recurring-series, and per-Notetaker configurations are managed through
sync endpoints and are not included in the public configuration list.
  - `display_name` (string) - A human-readable name for this configuration.
  - `notetaker_settings` (object) - Flat Notetaker settings for the configuration system. Omitted fields inherit from
the parent configuration. After inheritance, dependency rules determine effective
settings: summary and action_items require transcription. Nylas captures effective
settings at dispatch; later parent edits do not rewrite an existing run's snapshot.

Cannot be used together with the legacy `name` and `meeting_settings` fields.
    - `name` (string) - The display name shown when the Notetaker joins a meeting.
    - `recording_type` (string) - What Notetaker records. `audio_video` produces an MP4 recording of the meeting's
video and audio. `audio` produces an MP3 audio-only recording and does not capture
video. Transcription, summaries, and action items work with either value. When no
level of the configuration hierarchy sets it, Notetaker records audio and video.
    - `transcription` (boolean) - When `true`, Notetaker transcribes the meeting's audio.
    - `transcription_settings` (object, nullable) - Optional settings that tune how Notetaker transcribes audio. `transcription` must be
`true` for these settings to take effect. Provide any combination of the fields below.

The fields fall into two independent groups:

- **Language hints** (`expected_languages`, `fallback_language`) constrain automatic
  language detection. This declares the languages you expect; it does not translate
  transcripts or force the recording into a specific language.
- **Keyword hints** (`keywords`, `use_speaker_names_as_keywords`) bias recognition toward
  domain-specific terms such as names, acronyms, and product names.

Set on individual Notetakers, on calendar sync, on event sync, or on a configuration.
When set on a configuration or calendar, scheduled Notetakers inherit the value unless
the request overrides it. Send `null` or `{}` to clear inherited settings and return to
default transcription behavior.

See [Set transcription languages](/docs/v3/notetaker/transcription-settings/) for
supported language codes and validation rules.
      - `expected_languages` (array) - Language codes the audio is expected to contain. Optional. When provided, it must
contain at least one supported code and cannot be `null` or empty. When omitted,
transcription considers all supported languages.
      - `fallback_language` (string) - Language to use if Notetaker does not detect one of the `expected_languages`. Optional.
When `expected_languages` is set, the fallback must be one of those codes. When
`expected_languages` is omitted, transcription considers all supported languages and
the fallback may be any supported code. When `fallback_language` is omitted, the
transcriber auto-detects the language. The field is not stored, so responses do not
return it.
      - `keywords` (array) - Domain-specific terms that bias transcription toward recognizing them correctly, such
as names, acronyms, and product names. Optional. Up to 200 terms; each term must be
1 to 200 characters and cannot contain control characters. Cannot be `null`.
      - `use_speaker_names_as_keywords` (boolean) - When `true`, Notetaker adds known speaker names to the keyword set so they are
transcribed accurately. Optional. Cannot be `null`.
    - `summary` (boolean) - When `true`, Notetaker generates a summary of the meeting. Requires
`transcription` to also be `true`.
    - `summary_settings` (object)
      - `custom_instructions` (string) - Custom instructions for the AI summary model.
    - `action_items` (boolean) - When `true`, Notetaker generates a list of action items. Requires
`transcription` to also be `true`.
    - `action_items_settings` (object)
      - `custom_instructions` (string) - Custom instructions for the AI action items model.
    - `leave_after_silence_seconds` (integer) - Seconds of continuous silence after which the Notetaker automatically leaves
the meeting. Must be between 10 and 3600 seconds (1 hour).
    - `messages` (object) - Custom announcements the Notetaker bot posts to the meeting chat. Use this to
greet attendees when the bot joins, or to acknowledge new participants as they
arrive. Messages are optional; when omitted, the bot only posts the default
recording-and-transcription notice described in [Using Nylas Notetaker](/docs/v3/notetaker/).

Like other `notetaker_settings` fields, `messages` participates in the
configuration hierarchy and uses whole-object override semantics: the most
specific layer that sets `messages` completely replaces the parent's value
(there is no per-message merging). See [Custom announcements](/docs/v3/notetaker/custom-announcements/)
for the full inheritance model.
      - `on_join` (array) - Messages the bot sends shortly after it joins the meeting. Each message has
its own configurable delay measured from the moment the bot joins. Up to
10 messages per trigger.
        - `type` (string) **(required)** - The message format. Currently only `text` is supported. Plain-text content
is preferred; any HTML tags in `content` are stripped before the message
is sent.
        - `content` (string) **(required)** - The message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
`content` becomes empty after sanitization are rejected with a validation
error.
        - `send_after_ms` (integer) **(required)** - Delay in milliseconds between the moment the bot joins the meeting and
the moment this message is posted. Each `on_join` message is scheduled
independently against its own delay; messages are posted in the order
their delays expire.
      - `on_participant_join` (array) - Messages the bot sends when a new participant joins the meeting. Each message
uses a trailing debounce window — if another participant joins before the
window expires, the timer resets and only one message is posted per burst of
joins. Up to 10 messages per trigger.
        - `type` (string) **(required)** - The message format. Currently only `text` is supported. Plain-text content
is preferred; any HTML tags in `content` are stripped before the message
is sent.
        - `content` (string) **(required)** - The message text the bot posts to the meeting chat. After HTML tags are
stripped, the remaining text must be at least 1 character. Requests whose
`content` becomes empty after sanitization are rejected with a validation
error.
        - `debounce_ms` (integer) **(required)** - Trailing debounce window in milliseconds. When a participant joins, the
bot waits this long before posting the message. If another participant
joins inside the window, the timer resets — the message is only posted
once the window expires without another join event. This collapses a
burst of nearly-simultaneous joins into a single announcement.
    - `video_output` (object) - A static image the Notetaker bot shows as its camera feed when it joins a meeting,
instead of a blank tile. Sometimes called the bot avatar. Supported on Google Meet,
Microsoft Teams, and Zoom; on other providers the bot joins without showing the image.
Author images at a 16:9 aspect ratio. Text in the image appears mirrored in the
recording.

Upload the image in one of two ways:

- **Multipart** (recommended): send the request as `multipart/form-data` and set
  `file_key` to the name of the file part that contains the image. The JSON part must be
  named `config` on the configuration endpoints and `notetaker` on the Notetaker
  endpoints. File parts up to 4 MiB.
- **JSON + base64**: send `media_type` and `data` together on a plain `application/json`
  request. The decoded image must be 1,376,256 bytes (about 1.31 MB) or smaller.

Accepted formats are PNG, JPEG, and static WebP, up to 3840x2160 pixels and no more than
8,294,400 total pixels. The format is detected from the file content, not the declared
content type.

On `PATCH`, omitting `video_output` preserves the existing image, sending a new image
replaces it, and sending an empty object (`{}`) disables video output at that layer.

Accepted when you create or update a configuration or a Notetaker. Not supported on
calendar sync or event sync requests. See
[Notetaker custom video output](/docs/v3/notetaker/custom-video-output/).
      - `file_key` (string) - The name of the multipart file part that contains the image. Only valid on
`multipart/form-data` requests, must reference exactly one file part, and cannot be
combined with `media_type` or `data`.
      - `media_type` (string) - The image MIME type. On a JSON write, required together with `data` and must match
the actual file content. Always returned in responses.
      - `data` (string) - The base64-encoded image bytes. Only valid on `application/json` requests, required
together with `media_type`, and must decode to 1,376,256 bytes or smaller.
      - `size` (integer) - The stored image size in bytes. Read-only; rejected on writes.
      - `preview_url` (string) - A signed URL for previewing the stored image. Valid for 1 hour; fetch the
configuration again to get a fresh URL. Read-only; rejected on writes.
      - `preview_url_expires_at` (integer) - When `preview_url` expires, as a Unix timestamp in seconds. Read-only; rejected
on writes.
    - `retention_time` (integer) - How long Notetaker media (recording, transcript, summary, action items, and
thumbnail) is kept before Nylas automatically deletes it, in seconds. The
clock starts when the media is first stored after the meeting ends. Defaults
to 1,209,600 seconds (14 days). Like other `notetaker_settings` fields, the
effective value is resolved from the configuration hierarchy — set it on an
application or workspace configuration for a new default, or override it on
a single Notetaker to extend or shrink retention just for that bot.
  - `deduplication_policy` (string) - Controls whether Notetakers governed by this configuration participate in
deduplication. `active` and `inactive` are available on application and workspace
configurations. `inherit` and `disable` are available on calendar, event, and
per-notetaker configurations.
  - `dispatch_disabled_until` (string, nullable) - An RFC 3339 timestamp that suppresses Notetaker dispatch while it's in the future.
While suppression is active, Nylas rejects immediate join requests and doesn't
dispatch scheduled Notetakers governed by this configuration. `null` means dispatch
is enabled; a past timestamp means the suppression has expired. Only application,
workspace, and grant configurations accept this field. See
[Pause Notetaker dispatch](/docs/v3/notetaker/dispatch-suppression/).
  - `version` (integer) - The version number, incremented on each update.
  - `created_at` (integer) - When the configuration was created, in Unix timestamp seconds.
  - `updated_at` (integer) - When the configuration was last updated, in Unix timestamp seconds.

### 400 - Bad Request

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 401 - Unauthorized

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.
  - `provider_error` (object) - The error from the provider.

### 429 - Rate Limit

- `request_id` (string) - The request ID.
- `error` (object) - The response error object.
  - `type` (string) - The error type.
  - `message` (string) - The error message.