Skip to main content
POST
TypeScript SDK
For a successful request, the response is a File Upload object with a 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

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

Notion-Version
enum<string>
required

The API version to use for this request. The latest version is 2026-03-11.

Available options:
2026-03-11

Body

application/json
mode
enum<string>

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.

Available options:
single_part,
multi_part,
external_url
filename
string

The filename. Required for multi_part and external_url uploads. Include an extension or provide content_type so one can be inferred.

Example:

"business_summary.pdf"

content_type
string

The MIME type. It must match the uploaded file and any filename extension.

Example:

"application/pdf"

number_of_parts
integer

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.

Required range: 1 <= x <= 10000
external_url
string

A public HTTPS URL to import. Required only for external_url uploads.

Response

object
string
required

Always file_upload

Allowed value: "file_upload"
id
string<uuid>
required
created_time
string<date-time>
required
created_by
object
required
last_edited_time
string<date-time>
required
in_trash
boolean
required
expiry_time
string<date-time> | null
required
status
enum<string>
required

One of: pending, uploaded, expired, failed

Available options:
pending,
uploaded,
expired,
failed
filename
string | null
required
content_type
string | null
required
content_length
integer | null
required
Required range: x >= 0
upload_url
string
complete_url
string
file_import_result
Success · object
number_of_parts
object