1
Create a file upload object
2
Send the file content to Notion
3
Attach the file to content in your workspace
Before you begin
You need an integration token. Creating and sending a file upload needs either the Insert content or the Update content capability. Adding a block needs Insert content, setting a page cover orfiles property needs Update content, and checking the result needs Read content. Keep the token on your server. Don’t put it in browser page source, client bundles, or public repositories.
The examples upload a PNG image named logo.png from your working directory. They read your token and the ID of an existing page that’s shared with the integration from your shell:
requests package. The JavaScript example needs Node.js 20 or later and no extra packages. Save it as an .mjs file.
Step 1 - Create a File Upload object
Before uploading any content, start by creating a File Upload object. This returns a uniqueid and upload_url used to send the file.
Example requests
This snippet sends aPOST request to create the upload object.
id from the response, or the ID that the Python example prints, in your shell. The JavaScript and cURL examples read it from there:
Example Response
Step 2 - Upload file contents
Next, use theupload_url or File Upload object id from Step 1 to send the binary file contents to Notion.
Example requests
This uploads the file directly from your local system.Example response
Reminder:Files must be attached within 1 hour of creating the file upload or they’ll be automatically moved to an
expired status.Step 3 - Attach the file to a page or block
Once the file’sstatus is uploaded, it can be attached to any location that supports file objects using the File Upload object id.
This step uses standard Notion API endpoints; there’s no special upload-specific API for attaching. Just pass a file object with a type of file_upload and include the id that you received earlier in Step 1.
You can use the file upload id with the following APIs:
1
Create a page
- Attach files to a database property with the
filestype - Include uploaded files in
childrenblocks (e.g., file/image blocks inside a new page)
2
Update page
- Update existing
filesproperties on a database page - Set page
iconorcover
3
Append block children
- Add a new block to a page — like a file, image, audio, video, or PDF block that uses an uploaded file
4
Update a block
- Change the file attached to an existing file block (e.g., convert an image with an external URL to one that uses a file uploaded via the API)
Example: add an image block to a page
This example uses the Append block children API to create a new image block in a page and attach the uploaded file.Example: add a file block to a page
example uses the Append block children API to create a new file block in a page and attach the uploaded file.Example: attach a file property to a page in a database
This example uses the Update page API to add the uploaded file to afiles property on a page that lives in a Notion database. Set DATABASE_PAGE_ID to a page in a database with a files property named Attachments.
Example: Set a page cover
This example uses the Update page API to add the uploaded file as a page cover.Check the attachment
Retrieve the file upload. After the first attachment, itsstatus stays uploaded and its expiry_time is null.
id as BLOCK_ID and retrieve the block. An image block has an image.type of file and a temporary download URL in image.file.url.
You’ve successfully uploaded and attached a file using Notion’s Direct Upload method.
File lifecycle and reuse
When a file is first uploaded, it has anexpiry_time, one hour from the time of creation, during which it must be attached.
Once attached to any page, block, or database in your workspace:
- The
expiry_timebecomesnull. - The file becomes a permanent part of your workspace.
- The
statusremainsuploaded.
file_upload ID remains valid and can be reused to attach the file again.
Currently, there is no way to delete or revoke a file upload after it has been created.
Downloading an uploaded file
Attaching a file upload gives you access to a temporary download URL via the Notion API. These URLs expire after 1 hour. To refresh access, re-fetch the page, block, or database where the file is attached.Tips and troubleshooting
- URL expiration: Notion-hosted files expire after 1 hour. Always re-fetch file objects to refresh links.
- Attachment deadline: Files must be attached within 1 hour of upload, or they’ll expire.
- Size limit: This guide only supports files up to 20 MB. Larger files require a multi-part upload.
- Block type compatibility: Files can be attached to image, file, video, audio, or pdf blocks — and to
filesproperties on pages.