Upload Files to Notion

Overview

This reference file describes the uploadFileToNotion() function from Upload File to Notion, which uploads local files to Notion using Notion's three-step file upload API. The function handles the upload process and returns a Notion-hosted URL that you can then use in API calls to add the file to pages or databases.

Supported File Types

The function automatically detects and properly handles the following file types supported by Notion's API:

Images (Display inline in Notion)

• GIF (.gif)
• HEIC (.heic)
• JPEG (.jpeg, .jpg)
• PNG (.png)
• SVG (.svg)
• TIFF (.tif, .tiff)
• WebP (.webp)
• Icon (.ico)

Documents

• PDF (.pdf)
• Plain text (.txt)
• JSON (.json)
• Microsoft Word (.doc, .dot, .docx, .dotx)
• Microsoft Excel (.xls, .xlt, .xla, .xlsx, .xltx)
• Microsoft PowerPoint (.ppt, .pot, .pps, .ppa, .pptx, .potx)

Video

• AMV (.amv)
• ASF/WMV (.asf, .wmv)
• AVI (.avi)
• F4V (.f4v)
• FLV (.flv)
• GIF Video (.gifv)
• M4V (.m4v)
• MP4 (.mp4)
• Matroska (.mkv)
• WebM (.webm)
• QuickTime (.mov, .qt)
• MPEG (.mpeg)

Audio

• AAC (.aac, .adts)
• MIDI (.mid, .midi)
• MP3 (.mp3, .mpga)
• M4A/M4B (.m4a, .m4b)
• MP4 Audio (.mp4)
• OGG (.oga, .ogg)
• WAV (.wav)
• WMA (.wma)

⚠️ Important: Only the file types listed above are supported by Notion's file upload API. Other file types (such as archives, code files without document extensions, etc.) will be rejected by Notion.

Parameters

The function requires two parameters:

1. filePath (string, required)

   • The local filesystem path to the file you want to upload
   • Can be absolute or relative path (e.g., 'session/attachments/document.pdf')
   • Note: This function is for uploading local files only. If you have an external URL, use it directly in Notion API calls (see examples in SKILL.md)

2. notionToken (string, required)

   • Your Notion API authentication token
   • Must have file upload permissions

Automatic Upload Mode Selection

The function automatically determines the best upload method based on file size:

• Files ≤ 20MB: Uses single-part upload (one request)
• Files > 20MB: Automatically uses multi-part upload (10MB chunks)

How to Run the Code

Basic Usage - Upload File

IMPORTANT: Do NOT generate or define the uploadFileToNotion function. The function already exists in Upload File to Notion and must be imported.

Step 1: Upload the file to get Notion-hosted URL

import { uploadFileToNotion } from 'Upload File to Notion';

const result = await uploadFileToNotion(
  'session/attachments/document.pdf',      // File path
  process.env.NOTION_TOKEN                 // Notion token
);

console.log('File uploaded:', result);
// Output: {
//   success: true,
//   fileUploadId: 'abc123-def456-...',
//   fileName: 'document.pdf',
//   url: 'https://prod-files-secure.s3...',
//   expiryTime: '2025-11-13T10:00:00.000Z',
//   contentType: 'application/pdf',
//   fileSize: 12345
// }

Step 2: Use the file upload ID to add file to a page or database

After getting the file upload ID, use it with type: "file_upload" in Notion API calls to add the file to pages or databases. See examples below and in SKILL.md for how to create image, video, PDF, and file blocks, or how to add files to database properties.

Upload and Add to Page (Complete Example)

import { uploadFileToNotion } from 'Upload File to Notion';

// Step 1: Upload file
const uploadResult = await uploadFileToNotion(
  'images/team-photo.jpg',
  process.env.NOTION_TOKEN
);

// Step 2: Add to page as image block using the file upload ID
const imageBlock = {
  object: "block",
  type: "image",
  image: {
    type: "file_upload",
    file_upload: {
      id: uploadResult.fileUploadId
    },
    caption: [
      {
        text: {
          content: "Team photo from annual retreat 2025"
        }
      }
    ]
  }
};

const response = await fetch(`https://api.notion.com/v1/blocks/${pageId}/children`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${process.env.NOTION_TOKEN}`,
    'Content-Type': 'application/json',
    'Notion-Version': '2022-06-28'
  },
  body: JSON.stringify({
    children: [imageBlock]
  })
});

console.log('Image added to page!');

Return Value

The function returns a Promise that resolves to an object with the following structure:

{
  success: true,                           // Boolean - indicates successful upload
  fileUploadId: 'abc123-def456-...',       // String - File upload ID (use this in API calls)
  fileName: 'document.pdf',                // String - name of the uploaded file
  url: 'https://prod-files-secure...',     // String - Notion-hosted file URL
  expiryTime: '2025-11-13T10:00:00.000Z', // String - when the signed URL expires
  contentType: 'application/pdf',          // String - MIME type of the file
  fileSize: 12345                          // Number - file size in bytes
}

Important: Use the fileUploadId in subsequent Notion API calls to add the file to pages or databases with type: "file_upload".

Block Types

After uploading, use the file upload ID with type: "file_upload":

Image Block

For images (JPG, PNG, GIF, SVG, WebP):

{
  type: "image",
  image: {
    type: "file_upload",
    file_upload: {
      id: "your-file-upload-id"
    },
    caption: [
      {
        text: {
          content: "Optional caption"
        }
      }
    ]
  }
}

Video Block

For video files:

{
  type: "video",
  video: {
    type: "file_upload",
    file_upload: {
      id: "your-file-upload-id"
    },
    caption: [
      {
        text: {
          content: "Optional caption"
        }
      }
    ]
  }
}

PDF Block

For PDF documents (displays inline preview):

{
  type: "pdf",
  pdf: {
    type: "file_upload",
    file_upload: {
      id: "your-file-upload-id"
    },
    caption: [
      {
        text: {
          content: "Optional caption"
        }
      }
    ]
  }
}

File Block

For general files (documents, archives, code files, etc.):

{
  type: "file",
  file: {
    type: "file_upload",
    file_upload: {
      id: "your-file-upload-id"
    },
    caption: [
      {
        text: {
          content: "Optional caption"
        }
      }
    ]
  }
}

Database File Properties

When adding uploaded files to database properties, use the file upload ID:

{
  properties: {
    "Attachments": {
      files: [
        {
          name: "document.pdf",
          type: "file_upload",
          file_upload: {
            id: "your-file-upload-id"
          }
        }
      ]
    }
  }
}

Note: For external URLs, use type: "external" instead (see SKILL.md for examples).

File Size Limits

• Check Notion's current file upload limits
• The API may have size restrictions based on your workspace plan (free plans have a limit of 5 MiB per file while Paid plans have 5 GiB per file)
• Maximum filename length: 900 bytes (recommended: shorter names)