Skip to main content
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 connection.

​
Upload methods at a glance

The Notion API supports three ways to add files to your workspace:

​
Supported block types

Uploaded files can be attached to:
  • Media blocks: file, image, pdf, audio, video
  • embed blocks: attach an uploaded file to render it inline (see Embed)
  • Page properties: files properties in databases
  • Page-level visuals: page icon and cover
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: CAD and 3D model files attach as file blocks, the same as documents. Some HTTP clients label a file application/octet-stream when their MIME database has no entry for its extension. For any upload, the API treats that generic type as unspecified and resolves the real type from the filename extension or the content_type recorded when the file upload was created. If neither gives a supported type, the request fails.
Ensure your file type matches the contextFor 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

​
File size limits

  • Free workspaces are limited to 5 MiB (binary megabytes) per file
  • Paid workspaces are limited to 5 GiB per file.
These are the same size limits that apply to uploads in the Notion app UI. Use the Retrieve a user or List all users API to get the file size limit for a bot user. Public connections that can be added to both free or paid workspaces can retrieve or cache each bot’s file size limit. This can help avoid HTTP 400 validation errors for attempting to send files above the size limit.
For example, in a free workspace where bots are limited to FileUploads of 5 MiB, the response looks like:

​
Other limitations

The rest of the pages in this guide, as well as the API reference for the File Upload API, include additional validations and restrictions to keep in mind as you build your connection and send files. One final limit to note here is both the Create a file upload and Send a file upload APIs allow a maximum length of a filename (including the extension) of 900 bytes. However, we recommend using shorter names for performance and easier file management and lookup using the List file uploads API. What’s Next 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.