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 of this file object. Possible values are: |
|
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
fileproperty, theexpiry_timekey contains the timestamp that the link expires.
Property | Type | Description | Example value |
|---|---|---|---|
|
| Authenticated S3 URL to the file. The file URL will be valid for 1 hour but updated links can be requested if required. |
|
|
| Date and time when this will expire. Formatted as an ISO 8601 date time string. |
|
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 |
|---|---|---|---|
|
| Link to the externally hosted content. |