File uploads

Create a file upload

Changed on
post/v1/file_uploads

Request

  • Base URL
    https://api.notion.com
  • URL
    https://api.notion.com/v1/file_uploads
  • Auth
    HTTP bearer

Headers

Notion-Version'2026-03-11' required

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

Request body

mode'single_part' | 'multi_part' | 'external_url'

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.

filenamestring

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

content_typestring

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

number_of_partsinteger

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.

external_urlstring

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

Example request

{
  "filename": "business_summary.pdf",
  "content_type": "application/pdf"
}

Response

object'file_upload' required

Always file_upload

idstring uuid required
created_timestring date-time required
last_edited_timestring date-time required
in_trashboolean required
expiry_timestring date-time nullable required
status'pending' | 'uploaded' | 'expired' | 'failed' required

One of: pending, uploaded, expired, failed

filenamestring nullable required
content_typestring nullable required
content_lengthinteger nullable required
upload_urlstring
complete_urlstring

Changes

  • c90a4587bc95Revision changes
    • warning

      added the new idempotency_key_reused enum value to the / response property for the response status

  • ae20477af71bRevision changes
    • breaking

      added subschema #1 subschema #2 subschema #3 to the response body oneOf list for the response status

    • info

      removed subschema #2 from the response body allOf list for the response status