Working with files and media

Overview

Files, images, and other types of media are used throughout Notion to bring your pages to life. Files and media can be found in page covers, page icons, media blocks, and file properties in databases.

In this guide, you’ll learn about how files and other types of media are represented in our API and what you can do with them.

Files and media stored and hosted externally (Recommended)

Users can add externally hosted files and other media to Notion using the API. The developer is responsible for the asset and making it available via a secure URL.

Add files and media via the Notion API

For details on how to add externally hosted files and media to a page or database, reference to the API reference.

Retrieving files or media via the Notion API

In the API, files and media types are referenced by the source URL that points to where the file is stored. The source URLs for these files can be statically referenced.

Files and media hosted by Notion

Users can upload files and other media directly to Notion using the UI. Files uploaded in this manner are stored on Notion S3 instance and access to the file is hosted by Notion.

Uploading files and media via the Notion API

The API currently does not support uploading new files.

Retrieving files and media via the Notion API

In the API, files and media types are referenced by the public URL that points to where the file is stored.

Each time a database or page is queried, a new public URL is generated for all files hosted by Notion. The public URLs are updated hourly and the previous public URLs are only valid for one hour. The exact time when the URL will expire can be found in the expiry_time property of the file object.

Since the public URLs expire hourly, they shouldn’t be statically referenced. If the public URL is directly referenced, the file will not be accessible at that URL after the expiration time is reached and a new URL must be retrieved via the Notion API.

{
	"url": "https://s3.us-west-2.amazonaws.com/secure.notion-static.com/9bc6c6e0-32b8-4d55-8c12-3ae931f43a01/brocolli.jpeg?...",
	"expiry_time": "2020-03-17T19:10:04.968Z"
}