Create a file upload
Use this API to initiate the process of uploading a file to your Notion workspace.
status of "pending".
If you pass application/octet-stream as the content_type along with a filename, the API treats the content type as unspecified and resolves it from the filename extension instead. The same applies to the Content-Type header returned by an external_url. The request fails if the extension isn’t a supported file type.
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