Using Notetaker retention policies

Every recorded meeting can produce up to five files: a recording, transcript, thumbnail, and (when enabled) a summary and action items. By default, Nylas keeps them for 14 days, then deletes them. Change the duration by setting retention_time (in seconds) anywhere notetaker_settings is accepted.

The retention clock starts when the media is stored, which is usually a few minutes after the meeting ends and processing finishes. Not when the bot joined, not when the call started.

Set a default for your application

If 14 days isn’t the right window for your app, set retention_time on your application configuration:

curl --request POST \
  --url 'https://api.us.nylas.com/v3/notetakers/configs' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "display_name": "Company defaults",
    "notetaker_settings": {
      "retention_time": 604800
    }
  }'

That’s 7 days (604,800 seconds). Every Notetaker your app schedules from now on uses it. If you already have an application configuration, PATCH it with PATCH /v3/notetakers/configs/<CONFIG_ID>; only the fields you send are touched.

Different retention for one customer

A workspace configuration overrides the application default for every grant in that workspace. Reach for one when a single customer needs a different window, like a regulated customer that requires 90 days, or a trial customer you cap at 24 hours. For setting up the workspace itself, see Notetaker configurations.

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",
    "notetaker_settings": {
      "retention_time": 7776000
    }
  }'

Override on one Notetaker

To extend or shrink retention on a single recording, send retention_time on the Notetaker itself, either at create time or after.

curl --request PATCH \
  --url 'https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{
    "notetaker_settings": {
      "retention_time": 31536000
    }
  }'

That’s a year. One thing worth knowing: the new expiration recalculates from when the media was originally stored, not from when you sent the PATCH. So extending from 7 days to a year on day 5 buys you 360 more days, not 365.

Shrinking works the same way with a smaller value. If the new expiration is already in the past, Nylas deletes the media on its next sweep, but it isn’t instant. If you need media gone right now, use the DELETE endpoint below.

Delete media immediately

If you need media gone before the retention window ends, delete the Notetaker. The DELETE endpoint removes the bot and all 5 possible files at once, and it’s irreversible, so download anything you want to keep first.

Read the expiration back

The expiration timestamp shows up in three places:

The first notetaker.media webhook (when media first becomes available) includes retained_until on the media object, a Unix timestamp.
GET /v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/media returns expires_at (Unix timestamp) and ttl (seconds remaining at the time of the request) for each file.
GET /v3/notetakers/configs/<CONFIG_ID> returns the merged notetaker_settings, including retention_time.

What happens at expiration

At the scheduled time, Nylas:

Deletes the recording, transcript, summary, action items, and thumbnail.
Sets the Notetaker’s state and status to media_deleted.
Fires one final notetaker.media webhook with status: media_deleted and no media object.

After that, the media endpoint returns 410 Gone with the body media deleted.

Only the media is deleted. The Notetaker record itself (state history, timestamps, original settings) stays around indefinitely.