https://api.us.nylas.com/v3/grants/{grant_id}/calendars/{calendar_id}Return a calendar
Returns the specified calendar.
Path parameters
ID of the grant to access. Use /me/ to refer to the grant associated with an access token.
ID of the calendar to access. You can use primary to refer to the primary calendar associated
with a grant. Nylas recommends you URL-encode this field, or you might receive a
404 error if the ID contains special characters (for example,
#).
For an Agent Account,
the GET and PUT requests also accept the account's own email address, in any letter case,
to reach its primary calendar. DELETE takes the calendar's real ID only.
Query parameters
Specify fields that you want Nylas to return, as a comma-separated list (for example,
select=id,updated_at). This allows you to receive only the portion of object data that you're
interested in. You can use select to optimize response size and reduce latency by limiting queries
to only the information that you need.
"Junior sports league carpool drivers""41009df5-bf11-4c97-aa18-b285b5f2e386"hex_colorstring(Not supported for iCloud or EWS) The background color of the calendar, in hexadecimal format (for
example, #0099EE). When empty, Nylas uses the default background color.
You can set or modify this value using a PUT request only.
"#039BE5"hex_foreground_colorstring(Google only) The foreground color of the calendar, in hexadecimal format (for example, #0099EE).
When empty, Nylas uses the default foreground color.
You can modify this value using a PUT request only.
"#039BE5"idstringA globally unique object identifier for Microsoft accounts. An email address for Google accounts.
"5d3qmne77v32r8l4phyuksl2x, [email protected]"locationstring(Not supported for iCloud or EWS) The geographic location of the calendar, as free-form text.
"London, England"owner_emailstring(Microsoft only) The email address of the account that owns the calendar. Use it to tell the grant's own calendars apart from calendars shared with the grant.
This field is read-only.
"[email protected]"timezonestring(Google, Agent Accounts, and virtual calendars only) An IANA timezone database
formatted string (for example, America/New_York).
"America/Los_Angeles"notetakerobjectNotetaker settings for a calendar. Choose exactly one of the following modes to declare what Notetaker should do; combining them returns a validation error:
notetaker_settings(preferred) — inline flat settings using the configuration system.config_id— reference an existing application or workspace configuration.autocreate— create Notetakers for matching events using the inherited configuration.name+meeting_settings(⚠️ deprecated) — legacy nested settings.
rules is optional and declares which events Notetaker should join. You can
combine rules with notetaker_settings or with the legacy meeting_settings
mode.
notetaker_settingsobjectFlat 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.
recording_typestringWhat 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.
"audio_video"transcription_settingsobjectnullableOptional 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 for supported language codes and validation rules.
expected_languagesarray<string>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.
["en","es"]fallback_languagestringLanguage 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.
"en"keywordsarray<string>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.
["Nylas","AssemblyAI"]summarybooleanWhen true, Notetaker generates a summary of the meeting. Requires
transcription to also be true.
trueaction_itemsbooleanWhen true, Notetaker generates a list of action items. Requires
transcription to also be true.
trueleave_after_silence_secondsintegerSeconds of continuous silence after which the Notetaker automatically leaves the meeting. Must be between 10 and 3600 seconds (1 hour).
300600messagesobjectCustom 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.
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
for the full inheritance model.
on_joinarray<object>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*stringThe message format. Currently only text is supported. Plain-text content
is preferred; any HTML tags in content are stripped before the message
is sent.
"text"content*stringThe 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.
"👋 Hey team! I'm your AI notetaker — here to capture the key points."on_participant_joinarray<object>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*stringThe message format. Currently only text is supported. Plain-text content
is preferred; any HTML tags in content are stripped before the message
is sent.
"text"content*stringThe 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.
"👋 Welcome! Recording and transcription are running."debounce_ms*integerTrailing 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.
3000video_outputobjectA 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-dataand setfile_keyto the name of the file part that contains the image. The JSON part must be namedconfigon the configuration endpoints andnotetakeron the Notetaker endpoints. File parts up to 4 MiB. - JSON + base64: send
media_typeanddatatogether on a plainapplication/jsonrequest. 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.
file_keystringwrite-onlyThe 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.
"avatar"media_typestringThe image MIME type. On a JSON write, required together with data and must match
the actual file content. Always returned in responses.
"image/png"datastring<byte>write-onlyThe 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.
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="retention_timeintegerHow long Notetaker media (recording, transcript, summary, action items, and thumbnail) is kept before Nylas automatically deletes it, in seconds. Must be between 300 and 2,592,000 seconds (5 minutes to 30 days). The clock starts when the media is first stored after the meeting ends. Defaults to 1,209,600 seconds (14 days). Nylas resolves the effective value from the configuration hierarchy each time it checks for expiration, so changing it on an application or workspace configuration also re-times existing media that inherits it. Setting it on a single Notetaker overrides the configuration for that bot, and can only be changed while the Notetaker is still scheduled.
1209600604800config_idstringThe ID of an application or workspace Notetaker configuration
to apply to this calendar. Mutually exclusive with notetaker_settings,
autocreate, and the legacy name and meeting_settings fields.
"d4e78fca-2a90-4b6e-91c3-a7f2bcb0d498"autocreatebooleanWhen true, Nylas creates Notetakers for matching events on this calendar using
settings resolved from the configuration hierarchy (default → application →
workspace → calendar). Mutually exclusive with notetaker_settings, config_id,
and the legacy name and meeting_settings fields.
truededuplication_policystringControls whether Notetakers created from this calendar participate in deduplication.
inherit: Use the deduplication policy resolved from the configuration hierarchy.disable: Opt this calendar out of deduplication entirely.
"inherit"meeting_settingsobjectDeprecated. Use notetaker_settings instead. Cannot be used together with
notetaker_settings, config_id, or autocreate.
action_itemsbooleanWhen true, Notetaker generates a list of action items from the meeting. If action_items is
true, video_recording, audio_recording, and transcription must also be true.
truetrueleave_after_silence_secondsintegerThe number of seconds of silence after which the Notetaker bot automatically leaves the meeting. This helps end recordings when meetings have concluded but participants haven't disconnected the call. Must be between 10 and 3600 seconds (1 hour).
300360summarybooleanWhen true, Notetaker generates a summary of the meeting. If summary is true,
video_recording, audio_recording, and transcription must also be true.
truetruetranscriptionbooleanWhen true, Notetaker transcribes the meeting's audio. If transcription is true,
video_recording and audio_recording must also be true.
truetruetranscription_settingsobjectnullableOptional 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, or on event sync. When set on a calendar,
events inherit the value unless the event's own request overrides it. Send null or {}
to clear inherited settings and return to default transcription behavior.
See Set transcription languages for supported language codes and validation rules.
expected_languagesarray<string>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.
["en","es"]fallback_languagestringLanguage 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.
"en"keywordsarray<string>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.
["Nylas","AssemblyAI"]messagesobjectCustom 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.
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
for the full inheritance model.
on_joinarray<object>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*stringThe message format. Currently only text is supported. Plain-text content
is preferred; any HTML tags in content are stripped before the message
is sent.
"text"content*stringThe 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.
"👋 Hey team! I'm your AI notetaker — here to capture the key points."on_participant_joinarray<object>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*stringThe message format. Currently only text is supported. Plain-text content
is preferred; any HTML tags in content are stripped before the message
is sent.
"text"content*stringThe 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.
"👋 Welcome! Recording and transcription are running."debounce_ms*integerTrailing 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.
3000namestringDeprecated. Use notetaker_settings.name instead. Only valid with the legacy
meeting_settings mode.
"Nylas Notetaker""Nylas Notetaker"rulesobjectRules for when the Notetaker bot should join a meeting. Optional; can be combined
with notetaker_settings or with the legacy meeting_settings mode.
event_selectionarray<object>Specify the types of events Notetaker should join. Each item can be either a single criterion (a string) or a group of criteria (an array of strings). Top-level items are OR'd together; criteria inside a nested array are AND'd together.
Valid criteria:
- "all": Join all events with meeting links.
- "external": Join all events where the host's domain differs from any participant's domain.
- "internal": Join all events where the host's domain matches all participants' domains.
- "own_events": Join all events where the user is the host.
- "participant_only": Join all events where the user is a participant, but not the host.
Examples:
- ["internal", "own_events"]: Match events that are internal OR owned by the user.
- [["own_events", "external"]]: Match events that are owned by the user AND have at least one external participant.
- ["internal", ["own_events", "external"]]: Match events that are internal, OR events that are both owned by the user AND have at least one external participant.
["internal",["own_events","external"]]Rate limited. The provider or Nylas throttled the request. If a provider throttles a request and
says how long to wait, the Retry-After header gives that number of seconds. When the header
is missing, retry with exponential backoff. See
429 rate limit errors by provider.