Skip to main content
POST
/
v1
/
file_uploads
TypeScript SDK
import { Client } from "@notionhq/client"

const notion = new Client({ auth: process.env.NOTION_API_KEY })

const response = await notion.fileUploads.create({
  mode: "single_part",
  filename: "document.pdf",
  content_type: "application/pdf"
})
{
  "object": "<string>",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_time": "2023-12-25",
  "created_by": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "type": "person"
  },
  "last_edited_time": "2023-12-25",
  "archived": true,
  "expiry_time": "2023-12-25",
  "status": "pending",
  "filename": "<string>",
  "content_type": "<string>",
  "content_length": 1,
  "upload_url": "<string>",
  "complete_url": "<string>",
  "file_import_result": {
    "imported_time": "2023-12-25",
    "type": "<string>",
    "success": {}
  },
  "number_of_parts": {
    "total": 1,
    "sent": 1
  }
}
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 2025-09-03.

Available options:
2025-09-03

Body

application/json
​
mode
enum<string>

How the file is being sent. Use multi_part for files larger than 20MB. Use external_url for files that are temporarily hosted publicly elsewhere. Default is single_part.

Available options:
single_part,
multi_part,
external_url
​
filename
string

Name of the file to be created. Required when mode is multi_part. Otherwise optional, and used to override the filename. Must include an extension, or have one inferred from the content_type parameter.

Example:

"business_summary.pdf"

​
content_type
string

MIME type of the file to be created. Recommended when sending the file in multiple parts. Must match the content type of the file that's sent, and the extension of the filename parameter if any.

Example:

"application/pdf"

​
number_of_parts
integer

When mode is multi_part, the number of parts you are uploading. This must match the number of parts as well as the final part_number you send.

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

When mode is external_url, provide the HTTPS URL of a publicly accessible file to import into your workspace.

Response

​
object
string
required

Always file_upload

Allowed value: "file_upload"
​
id
string<uuid>
required
​
created_time
string<date>
required
​
created_by
object
required
​
last_edited_time
string<date>
required
​
archived
boolean
required
​
expiry_time
string<date> | 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