---
title: "Create a file upload"
method: POST
path: "/v1/file_uploads"
tags: ["File uploads"]
---

# Create a file upload

`POST /v1/file_uploads`

## Headers

- `Notion-Version` '2026-03-11', required

## Request body

- object
  - `mode` 'single_part' | 'multi_part' | 'external_url' — 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`.
  - `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.
  - `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.
  - `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.
  - `external_url` string — When `mode` is `external_url`, provide the HTTPS URL of a publicly accessible file to import into your workspace.

## Response `200`

- FileUploadObjectResponse
  - `object` 'file_upload', required — Always `file_upload`
  - `id` string, uuid, required
  - `created_time` string, date-time, required
  - `created_by` object, required
    - `id` string, uuid, required
    - `type` 'person' | 'bot' | 'agent', required — One of: `person`, `bot`, `agent`
  - `last_edited_time` string, date-time, required
  - `in_trash` boolean, required
  - `expiry_time` string, date-time, nullable, required
  - `status` 'pending' | 'uploaded' | 'expired' | 'failed', required — One of: `pending`, `uploaded`, `expired`, `failed`
  - `filename` string, nullable, required
  - `content_type` string, nullable, required
  - `content_length` integer, nullable, required
  - `upload_url` string
  - `complete_url` string
  - `file_import_result` union
    - object
      - `imported_time` string, date-time, required — The time the file was imported into Notion. ISO 8601 format.
      - `type` 'success', required — Indicates a successful import.
      - `success` EmptyObject, required
    - object
      - `imported_time` string, date-time, required — The time the file was imported into Notion. ISO 8601 format.
      - `type` 'error', required — Indicates an error occurred during import.
      - `error` object, required — Details about the error that occurred during file import.
        - `type` 'validation_error' | 'internal_system_error' | 'download_error' | 'upload_error', required — The type of error that occurred during file import.
        - `code` string, required — A short string code representing the error.
        - `message` string, required — A human-readable message describing the error.
        - `parameter` string, nullable, required — The parameter related to the error, if applicable. Null if not applicable.
        - `status_code` integer, nullable, required — The HTTP status code associated with the error, if available. Null if not applicable.
  - `number_of_parts` object
    - `total` integer, required
    - `sent` integer, required

## Other responses

- `400`
- `401`
- `403`
- `404`
- `406`
- `409`
- `429`
- `500`
- `503`
- `504`
- `529`

---

[API](https://skmtc.net/notion/apis/notion-api.md) · [All operations](https://skmtc.net/notion/apis/notion-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/notion/notion-api/revisions/dee5763763b0/schema)