Working with files and media
Learn how to add or retrieve files and media from Notion pages.
Files, images, and other media bring your Notion workspace to life — from company logos and product photos to contract PDFs and design assets. With the Notion API, you can programmatically upload, attach, and reuse these files wherever they’re needed.
In this guide, you’ll learn how to:
- Upload a new file using the Direct Upload method (single-part)
- Retrieve existing files already uploaded to your workspace
We’ll also walk through the different upload methods and supported file types, so you can choose the best path for your integration.
Upload methods at a glance
The Notion API supports three ways to add files to your workspace:
| Upload method | Description | Best for |
|---|---|---|
| Direct Upload | Upload a file (≤ 20MB) via a multipart/form-data request | The simplest method for most files |
| Direct Upload (multi-part) | Upload large files (> 20MB) in chunks across multiple requests | Larger media assets and uploads over time |
| Indirect Import | Import a file from a publicly accessible URL | Migration workflows and hosted content |
Supported block types
Uploaded files can be attached to:
- Media blocks:
file,image,pdf,audio,video - Page properties:
filesproperties in databases - Page-level visuals: page
iconandcover
💡 Need support for another block or content type? Let us know here.
Supported file types
Before uploading, make sure your file type is supported. Here’s what the API accepts:
| Category | Extensions | MIME types |
|---|---|---|
| Audio | .aac, .mid, .midi, .mp3, .ogg, .wav, .wma, .m4a, .m4b | audio/aac, audio/midi, audio/mpeg, audio/ogg, audio/wav, audio/x-ms-wma |
| Document | .json, .pdf, .txt | application/json, application/pdf, text/plain |
| Image | .gif, .heic, .ico, .jpeg, .jpg, .png, .svg, .tif, .tiff, .webp | image/gif, image/heic, image/vnd.microsoft.icon, image/jpeg, image/png, image/svg+xml, image/tiff, image/webp |
| Video | .amv, .asf, .avi, .f4v, .flv, .gifv, .m4v, .mkv, .mov, .mp4, .mpeg, .qt, .wmv | video/x-amv, video/x-ms-asf, video/x-msvideo, video/x-f4v, video/x-flv, video/mp4, video/mpeg, video/webm, video/quicktime, video/x-ms-wmv |
Ensure your file type matches the context
For example:
- You can’t use a video in an image block
- Page icons can’t be PDFs
- Text files can’t be embedded in video blocks
Free workspaces are limited to 5 MiB (binary megabytes) per file, and paid workspaces are limited to 5 GiB per file. These are the same size limits that apply to uploads in the Notion app UI.
Updated 2 days ago
Now that you know what’s supported, let’s walk through a real upload using the simplest method: uploading a single file in one request.