Handling Notetaker media files

After your Notetaker bot leaves a meeting, Nylas automatically creates media for the event based on your Notetaker settings. By default, this includes an MP4 audio/video recording, a PNG thumbnail from the video, and a text transcript of the conversation. If you set video_recording to false and audio_recording to true, Nylas creates an MP3 audio-only recording and transcript instead. Nylas also sends you notetaker.media webhook notifications with updates about the media processing status.

When Nylas is finished processing the files, it sends a notetaker.media webhook notification with URLs for the recording, thumbnail, and transcript.

Nylas stores Notetaker media files for a maximum of 14 days. After the 14-day storage period, the files are deleted and you can’t retrieve them using the Nylas API. We recommend downloading and storing these files as soon as they’re available if you need access to them beyond Nylas’ retention period.

How Nylas delivers media files

Nylas delivers media files using temporary, pre-authenticated download URLs. When media processing completes, Nylas generates a unique URL for each file (recording, transcript, thumbnail, summary, and action items) and includes them in the notetaker.media webhook notification.

These URLs authorize access to the file directly, with no additional authentication required to download. This means you can pass the URL to any HTTP client or download tool without providing your API key or grant credentials.

Each media URL is valid for 60 minutes from the time it was generated. After that, the URL expires and any download attempt returns an error. This is a deliberate security constraint: short-lived URLs limit the window of exposure if a URL is ever logged or leaked unintentionally.

To get fresh URLs after the 60-minute window, make a request to the Get Notetaker Media endpoint. Each call generates new URLs with a fresh 60-minute validity window. See Regenerate expired media URLs for details.

Understanding the media response fields

When you call the Get Notetaker Media endpoint, each media object in the response includes metadata alongside the download URL:

Field	Description
`url`	Pre-authenticated download URL, valid for 60 minutes from generation.
`created_at`	When the file was created, as a Unix timestamp in seconds.
`expires_at`	When the file will be permanently deleted from Nylas servers, as a Unix timestamp in seconds.
`ttl`	Seconds remaining until the file is deleted. This is the difference between `expires_at` and the time of your request.
`size`	File size in bytes.
`type`	MIME type (for example, `video/mp4`, `application/json`, `image/png`).
`name`	File name.
`duration`	Recording duration in seconds (recording only).

The ttl and expires_at fields reflect the file’s retention period on Nylas servers, not the URL’s 60-minute validity window. Use these fields to track how much time you have left to download the file before it’s permanently deleted.

Download and store Notetaker media files

Nylas only stores Notetaker media files for up to 14 days, so we recommend you set up a system that downloads and stores the files as they become available. The easiest way to do this is to subscribe to notetaker.media webhook notifications and set up an automated process to download the files when their state is available.

The media URLs included in notetaker.media webhook notifications are valid for 60 minutes. After that point, you’ll need to regenerate the URLs by making a request to the Get Notetaker Media endpoint.

{
  "specversion": "1.0",
  "type": "notetaker.media",
  "source": "/nylas/notetaker",
  "id": "<WEBHOOK_ID>",
  "time": 1737500935555,
  "data": {
    "application_id": "<NYLAS_APPLICATION_ID>",
    "object": {
      "id": "<NOTETAKER_ID>",
      "grant_id": "<NYLAS_GRANT_ID>",
      "object": "notetaker",
      "meeting_settings": {
        "video_recording": true,
        "audio_recording": true,
        "transcription": true,
        "summary": true,
        "summary_settings": {
          "custom_instructions": "Focus on action items related to the product launch."
        },
        "action_items": true,
        "action_items_settings": {
          "custom_instructions": "Group action items by team member."
        },
        "leave_after_silence_seconds": 300
      },
      "meeting_provider": "Google Meet",
      "meeting_link": "https://meet.google.com/abc-defg-hij",
      "join_time": 1737500936450,
      "event": {
        "ical_uid": "<ICAL_UID>",
        "event_id": "<EVENT_ID>",
        "master_event_id": "<MASTER_EVENT_ID>"
      },
      "status": "available",
      "state": "available",
      "media": {
        "recording": "<SIGNED_URL>",
        "recording_duration": "1800",
        "recording_file_format": "mp4",
        "thumbnail": "<SIGNED_URL>",
        "transcript": "<SIGNED_URL>",
        "summary": "<SIGNED_URL>",
        "action_items": "<SIGNED_URL>"
      }
    }
  }
}

You can then store the files in your own infrastructure and present them to your users as necessary.

Regenerate expired media URLs

If you don’t download media files within 60 minutes of the webhook notification, the URLs expire. You can generate fresh URLs at any time by calling the Get Notetaker Media endpoint.

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID>/media" \
  --header 'Accept: application/json, application/gzip' \
  --header 'Authorization: Bearer <NYLAS_API_KEY>'

{
  "request_id": "5fa64c92-e840-4357-86b9-2aa364d35b88",
  "data": {
    "action_items": {
      "created_at": 1703088000,
      "expires_at": 1704297600,
      "name": "meeting_action_items.json",
      "size": 289,
      "ttl": 3600,
      "type": "application/json",
      "url": "https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/..."
    },
    "recording": {
      "created_at": 1703088000,
      "duration": 1800,
      "expires_at": 1704297600,
      "name": "meeting_recording.mp4",
      "size": 52428800,
      "ttl": 3600,
      "type": "video/mp4",
      "url": "https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/..."
    },
    "summary": {
      "created_at": 1703088000,
      "expires_at": 1704297600,
      "name": "meeting_summary.json",
      "size": 437,
      "ttl": 3600,
      "type": "application/json",
      "url": "https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/..."
    },
    "thumbnail": {
      "created_at": 1703088000,
      "expires_at": 1704297600,
      "name": "thumbnail.png",
      "size": 437,
      "ttl": 3600,
      "type": "image/png",
      "url": "https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/..."
    },
    "transcript": {
      "created_at": 1703088000,
      "expires_at": 1704297600,
      "name": "transcript.json",
      "size": 10240,
      "ttl": 3600,
      "type": "application/json",
      "url": "https://storage.googleapis.com/nylas-notetaker-uc1-prod-notetaker/..."
    }
  }
}

Each call returns new URLs with a fresh 60-minute window. The endpoint is idempotent and read-only, so you can call it as often as you need without side effects.

The endpoint only returns media when the Notetaker’s state is media_available. If media is still processing, you’ll get a 404 response. If the media has already been deleted past the retention period, you’ll get a 410. The response includes all media types that were enabled in your Notetaker settings at the time of the meeting.

Recording and thumbnail formats

Nylas automatically creates recording and thumbnail media for each event your Notetaker attends.

Video recording format

Notetaker video recordings capture the main meeting interface, excluding any browser UI elements and meeting platform toolbars. The behavior varies slightly for each provider:

Google Meet: Recording of participant grid and shared screen content.
Microsoft Teams: Recording of the main meeting area.
Zoom: Recording of the full meeting window.

Nylas generates an MP4 file with the following specifications:

Video specs:
- Format: .mp4 video file
- Resolution: 1280x720
- Frame rate: 12 FPS
Audio specs:
- Format: Stereo audio track.
- Quality: 48 kHz sampling.
- Content: All meeting audio, including participants and shared content.

Audio-only recording format

If you set video_recording to false and audio_recording to true in your Notetaker settings, Nylas records only the meeting audio and does not capture any video. In this mode:

Nylas creates an MP3 audio file instead of an MP4 video file.
The MP3 file appears as the recording in the media output and in notetaker.media webhook notifications.
Nylas still generates a speaker-labelled transcript from the audio.
No video recording or thumbnail is created.

Audio-only recordings cannot have video recovered. Because Nylas does not capture video data in this mode, there is no way to retrieve or reconstruct the video after the meeting ends.

Thumbnail format

Nylas automatically generates a thumbnail from approximately half-way through the meeting’s video recording with the following specifications:

Format: .png image file
Resolution: 1280px width (height scaled proportionally)

Transcript and AI-generated content formats

Transcript format

For most events, Nylas includes the following information in each transcript:

Speaker attribution: Users’ names.
Timing information: start and end times, in milliseconds.

It also separates each speaker’s contribution into individual text segments that fall within the start and end times, as in the following example.

{
  "object": "transcript",
  "type": "speaker_labelled",
  "transcript": [
    {
      "speaker": "Nyla",
      "start": 100,
      "end": 10420,
      "text": "Did you know that a day on Venus is longer than its year? It takes Venus about 243 Earth days to rotate once, but only about 225 Earth days to orbit the Sun."
    },
    {
      "speaker": "Leyah",
      "start": 10500,
      "end": 12500,
      "text": "That's wild. So technically, you could have a birthday before a sunrise there."
    }
  ]
}

In rare cases, Nylas might return the transcript as a raw text file without speaker labels or timestamps.

{
  "object": "transcript",
  "type": "raw",
  "transcript": "The Moon is slowly moving away from the Earth at a rate of about 3.8 centimeters per year."
}

Although it’s rare that Nylas returns transcripts as raw text, your project should be able to handle both formats. You can use the type field to determine which format you’re working with.

Action items format

When action_items is true, Nylas generates a JSON file that contains a list of action items from the meeting.

[
  "Test the Notetaker implementation."
]

Meeting summary format

When summary is true, Nylas generates a JSON file that contains a short summary of the meeting.

"Participants discussed their project's new Notetaker implementation and what needs to be done to test it."

Media security model

Nylas applies multiple layers of protection to Notetaker media files throughout their lifecycle.

What Nylas enforces

Every media URL is scoped to a single file and valid for 60 minutes by design, limiting the window of exposure if a URL is inadvertently shared or logged. Nylas generates URLs on demand with each API request and does not issue persistent download tokens or reuse previously generated URLs after they expire.

All media downloads are served over HTTPS with TLS encryption. Media URLs do not contain or expose your API key, grant tokens, or account identifiers, and cannot be used to discover or access any other Nylas resources.

Once the retention window passes, media files are permanently deleted from Nylas servers. Deleted files cannot be recovered, and any previously generated URLs for those files stop working.

Your responsibilities

Media URLs function as short-lived bearer credentials. Anyone with a valid URL can download the file during the 60-minute window without any additional authentication, so treat them with the same care you’d give an API key.

Download files to your own infrastructure promptly and store the files themselves rather than the URLs. If your application passes media URLs to a frontend, be aware that they’re visible in browser network tabs and developer tools. Consider proxying downloads through your backend instead.

Once files are on your infrastructure, enforce authentication, authorization, and audit logging that meet your security and compliance requirements.

Delete a Notetaker and its media

You don’t have to wait for the 14-day retention window to expire. If you’ve already downloaded the files you need, you can immediately and permanently delete a Notetaker and all of its associated media (recordings, transcripts, thumbnails, summaries, and action items) by calling the DELETE /v3/notetakers/<NOTETAKER_ID> or DELETE /v3/grants/<NYLAS_GRANT_ID>/notetakers/<NOTETAKER_ID> endpoint.

This is useful for data-conscious applications that want to minimize how long sensitive meeting content stays on third-party infrastructure. For example, you could automate deletion as part of your media download pipeline: once your system has successfully retrieved and stored all media files, it calls the delete endpoint to remove the data from Nylas servers right away.

Deleting a Notetaker is permanent and irreversible. Once deleted, Nylas cannot recover the Notetaker or any of its media files. Nylas Support also cannot retrieve or investigate deleted data on your behalf. Only delete a Notetaker after you have confirmed that all files are safely stored on your own infrastructure.

For more details, see Delete a Notetaker.

Keep in mind

Nylas takes a few minutes to process media files after Notetaker leaves a meeting.
We recommend you add error handling and retry logic to your project for downloading media files, in case the initial download fails.
Make sure your project can handle multiple downloads simultaneously, and plan for scale; popular applications might need to handle thousands of downloads per day.
If you’re storing files to present them to your users, store them securely and back them up regularly.