0
# File Uploads
1

2
Handle file uploads to Notion including creation, sending, and completion of upload processes.
3

4
## Capabilities
5

6
### Create File Upload
7

8
Initialize a new file upload process.
9

10
```typescript { .api }
11
/**
12
 * Create a new file upload
13
 * @param args - File upload creation parameters
14
 * @returns Promise resolving to file upload object
15
 */
16
fileUploads.create(args: CreateFileUploadParameters): Promise<CreateFileUploadResponse>;
17

18
interface CreateFileUploadParameters {
19
  /** Name of the file */
20
  name: string;
21
  /** MIME type of the file */
22
  file_type: string;
23
  /** Size of the file in bytes */
24
  file_size: number;
25
  /** Parent page for the file */
26
  parent?: {
27
    type: "page_id";
28
    page_id: string;
29
  };
30
}
31

32
type CreateFileUploadResponse = FileUploadObjectResponse;
33
```
34

35
**Usage Examples:**
36

37
```typescript
38
// Create file upload for image
39
const fileUpload = await notion.fileUploads.create({
40
  name: "screenshot.png",
41
  file_type: "image/png",
42
  file_size: 1024768, // Size in bytes
43
  parent: { type: "page_id", page_id: "page-id" },
44
});
45

46
console.log(fileUpload.upload_url); // URL to upload file data
47
console.log(fileUpload.file.url); // Final file URL after upload
48
```
49

50
### Send File Upload
51

52
Upload the actual file data to the created upload.
53

54
```typescript { .api }
55
/**
56
 * Send file data to an upload
57
 * @param args - File upload send parameters
58
 * @returns Promise resolving to upload response
59
 */
60
fileUploads.send(args: SendFileUploadParameters): Promise<SendFileUploadResponse>;
61

62
interface SendFileUploadParameters {
63
  /** ID of the file upload */
64
  file_upload_id: string;
65
  /** File data to upload */
66
  file: Blob | Buffer | string;
67
}
68

69
type SendFileUploadResponse = {
70
  object: "file_upload";
71
  id: string;
72
  status: "pending" | "processing" | "complete" | "failed";
73
};
74
```
75

76
**Usage Examples:**
77

78
```typescript
79
// Send file data (browser)
80
const fileInput = document.getElementById('file') as HTMLInputElement;
81
const file = fileInput.files?.[0];
82

83
if (file) {
84
  const sendResponse = await notion.fileUploads.send({
85
    file_upload_id: fileUpload.id,
86
    file: file,
87
  });
88
}
89

90
// Send file data (Node.js)
91
import fs from 'fs';
92

93
const fileBuffer = fs.readFileSync('path/to/file.png');
94
const sendResponse = await notion.fileUploads.send({
95
  file_upload_id: fileUpload.id,
96
  file: fileBuffer,
97
});
98
```
99

100
### Complete File Upload
101

102
Mark a file upload as complete and finalize the process.
103

104
```typescript { .api }
105
/**
106
 * Complete a file upload
107
 * @param args - File upload completion parameters
108
 * @returns Promise resolving to completed upload
109
 */
110
fileUploads.complete(args: CompleteFileUploadParameters): Promise<CompleteFileUploadResponse>;
111

112
interface CompleteFileUploadParameters {
113
  /** ID of the file upload to complete */
114
  file_upload_id: string;
115
}
116

117
type CompleteFileUploadResponse = FileUploadObjectResponse;
118
```
119

120
**Usage Examples:**
121

122
```typescript
123
// Complete the upload process
124
const completedUpload = await notion.fileUploads.complete({
125
  file_upload_id: fileUpload.id,
126
});
127

128
console.log(completedUpload.status); // Should be "complete"
129
console.log(completedUpload.file.url); // Final accessible file URL
130
```
131

132
### Retrieve File Upload
133

134
Get the status and details of a file upload.
135

136
```typescript { .api }
137
/**
138
 * Retrieve a file upload by ID
139
 * @param args - File upload retrieval parameters
140
 * @returns Promise resolving to file upload object
141
 */
142
fileUploads.retrieve(args: GetFileUploadParameters): Promise<GetFileUploadResponse>;
143

144
interface GetFileUploadParameters {
145
  /** ID of the file upload to retrieve */
146
  file_upload_id: string;
147
}
148

149
type GetFileUploadResponse = FileUploadObjectResponse;
150
```
151

152
**Usage Examples:**
153

154
```typescript
155
// Check upload status
156
const uploadStatus = await notion.fileUploads.retrieve({
157
  file_upload_id: "upload-id",
158
});
159

160
console.log(uploadStatus.status); // "pending", "processing", "complete", or "failed"
161

162
if (uploadStatus.status === "complete") {
163
  console.log("File uploaded successfully:", uploadStatus.file.url);
164
} else if (uploadStatus.status === "failed") {
165
  console.log("Upload failed");
166
}
167
```
168

169
### List File Uploads
170

171
Retrieve a list of file uploads.
172

173
```typescript { .api }
174
/**
175
 * List file uploads
176
 * @param args - File upload list parameters
177
 * @returns Promise resolving to list of file uploads
178
 */
179
fileUploads.list(args: ListFileUploadsParameters): Promise<ListFileUploadsResponse>;
180

181
interface ListFileUploadsParameters {
182
  /** Pagination cursor */
183
  start_cursor?: string;
184
  /** Page size (max 100) */
185
  page_size?: number;
186
}
187

188
type ListFileUploadsResponse = {
189
  object: "list";
190
  results: FileUploadObjectResponse[];
191
  next_cursor: string | null;
192
  has_more: boolean;
193
  type: "file_upload";
194
  file_upload: Record<string, unknown>;
195
};
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
// List recent file uploads
202
const uploads = await notion.fileUploads.list({
203
  page_size: 50,
204
});
205

206
uploads.results.forEach(upload => {
207
  console.log(`${upload.name}: ${upload.status}`);
208
});
209

210
// Paginated listing
211
const uploadsPage = await notion.fileUploads.list({
212
  start_cursor: "cursor-token",
213
  page_size: 25,
214
});
215
```
216

217
## Complete Upload Workflow
218

219
```typescript
220
// Complete file upload workflow
221
async function uploadFile(file: File, pageId: string) {
222
  // 1. Create upload
223
  const fileUpload = await notion.fileUploads.create({
224
    name: file.name,
225
    file_type: file.type,
226
    file_size: file.size,
227
    parent: { type: "page_id", page_id: pageId },
228
  });
229

230
  // 2. Send file data
231
  await notion.fileUploads.send({
232
    file_upload_id: fileUpload.id,
233
    file: file,
234
  });
235

236
  // 3. Complete upload
237
  const completedUpload = await notion.fileUploads.complete({
238
    file_upload_id: fileUpload.id,
239
  });
240

241
  return completedUpload.file.url; // Final file URL
242
}
243
```
244

245
## Types
246

247
```typescript { .api }
248
interface FileUploadObjectResponse {
249
  object: "file_upload";
250
  id: string;
251
  created_time: string;
252
  name: string;
253
  file_type: string;
254
  file_size: number;
255
  status: "pending" | "processing" | "complete" | "failed";
256
  upload_url?: string;
257
  file: {
258
    url: string;
259
    expiry_time: string;
260
  };
261
  parent?: {
262
    type: "page_id";
263
    page_id: string;
264
  };
265
}
266
```