File objects contain data about files uploaded to Notion as well as external files linked in Notion.

All file objects

Each file object contains the following keys. In addition, it must contain a key corresponding with the value of type. The value is an object containing type-specific configuration. The type-specific configurations are described in the sections below.

Property

Type

Description

Example value

{type}

string (enum)

Type of this file object. Possible values are: "external", "file".

"external"

Externally hosted files vs. Files hosted by Notion

For files and URLs hosted outside of Notion, we support retrieving the link as well as updating it to a different link. We don't currently support uploading files to Notion through the API, however, for files already uploaded to Notion, we support retrieving the file URL. The table below details what's supported for Embed, Image, Video, Audio, and File blocks, as well as page icon and page cover image properties.

Name

Retrieve

Create

Link to externally hosted file

Yes

Yes

File uploaded to Notion

Yes

No

Files uploaded to Notion objects

All files hosted by Notion have a type of "file".

File objects contain the following information within the file property:

📘

Links to files hosted by Notion will expire.

When retrieving files hosted by Notion, within the file property, the expiry_time key contains the timestamp that the link expires.

Property

Type

Description

Example value

url

string

Authenticated S3 URL to the file. The file URL will be valid for 1 hour but updated links can be requested if required.

"https://s3.us-west-2.amazonaws.com/secure.notion-static.com/9bc6c6e0-32b8-4d55-8c12-3ae931f43a01/brocolli.jpeg?..."

expiry_time

string (ISO 8601 date time)

Date and time when this will expire. Formatted as an ISO 8601 date time string.

"2020-03-17T19:10:04.968Z"

External file objects

All external file objects have a type of "external".

An external file is any URL that isn't hosted by Notion.

External file objects contain the following information within the external property:

Property

Type

Description

Example value

url

string

Link to the externally hosted content.

"https://website.domain/files/doc.txt"