Skip to main content
The Direct Upload method lets you securely upload private files to Notion-managed storage via the API. Once uploaded, these files can be reused and attached to pages, blocks, or database properties. This guide walks you through the upload lifecycle:
1
Create a file upload object
2
Send the file content to Notion
3
Attach the file to content in your workspace
Tip:Upload once, attach many times. You can reuse the same file_upload ID across multiple blocks or pages.

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 or files 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:
The Python examples run in order as one script and use the 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 unique id and upload_url used to send the file.
Tip:Save the id — You’ll need it to upload the file in Step 2 and attach it in Step 3.

Example requests

This snippet sends a POST request to create the upload object.
Save the 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 the upload_url or File Upload object id from Step 1 to send the binary file contents to Notion.
Tips:
  • The only required field is the file contents under the file key.
  • Unlike other Notion APIs, the Send File Upload endpoint expects a Content-Type of multipart/form-data, not application/json.
  • Include a boundary in the Content-Type header [for the Send File Upload API] as described in RFC 2388 and RFC 1341. Most HTTP clients (e.g. fetch, ky) handle this automatically if you include FormData with your file and don’t pass an explicit Content-Type header.

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’s status 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 files type
  • Include uploaded files in children blocks (e.g., file/image blocks inside a new page)
2
Update page
  • Update existing files properties on a database page
  • Set page icon or cover
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 a files 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, its status stays uploaded and its expiry_time is null.
The append response lists the new block, and the Python example prints its ID. Save that 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 an expiry_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_time becomes null.
  • The file becomes a permanent part of your workspace.
  • The status remains uploaded.
Even if the original content is deleted, the 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.
Tip:A file becomes persistent and reusable after the first successful attachment — no need to re-upload.

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 files properties on pages.
What’s Next Now that you know how to upload a file, let’s walk through how to retrieve a file via the API: