Create a file upload
Use this API to initiate the process of uploading a file to your Notion workspace.
status of "pending".
The maximum allowed length of filename string is 900 bytes, including any file extension included in the file name or inferred based on the content_type. However, we recommend using shorter names for performance and easier file management and lookup using the List file uploads API.Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
The API version to use for this request. The latest version is 2026-03-11.
2026-03-11 Body
How the file is sent. Defaults to single_part. Use multi_part for files larger than 20 MiB or external_url for a temporary public HTTPS URL.
single_part, multi_part, external_url The filename. Required for multi_part and external_url uploads. Include an extension or provide content_type so one can be inferred.
"business_summary.pdf"
The MIME type. It must match the uploaded file and any filename extension.
"application/pdf"
The number of parts in a multi_part upload. Required only for multi_part uploads. This must match the number of uploaded parts and the final part_number sent.
1 <= x <= 10000A public HTTPS URL to import. Required only for external_url uploads.
Response
Always file_upload
"file_upload"One of: pending, uploaded, expired, failed
pending, uploaded, expired, failed x >= 0- Success
- Error