Skip to main content
Creates a file upload object and returns an upload URL. This is the first step in the file upload lifecycle.

​
Method

client.fileUploads.create({
  mode: "single_part",
  filename: "document.pdf",
  content_type: "application/pdf"
})

​
Parameters

​
mode
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.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.
​
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.Examples: "application/pdf", "image/png", "video/mp4"
​
number_of_parts
number
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

Returns a FileUpload object with:
​
object
string
Always "file_upload"
​
id
string
Unique identifier for the file upload. Use this in subsequent send and complete calls.
​
status
string
Current status of the file upload: "pending", "uploaded", "expired", or "failed"
​
upload_url
string
URL to use for sending file data. Present when status is "pending".
​
complete_url
string
URL for completing a multi-part upload.
​
expiry_time
string
ISO 8601 timestamp when the upload URL expires.
​
number_of_parts
object
For multi-part uploads, contains total and sent part counts.

​
Examples

​
Single-part upload

For files under 20MB: 
const fileUpload = await client.fileUploads.create({
  mode: "single_part",
  filename: "report.pdf",
  content_type: "application/pdf"
})

console.log(fileUpload.id) // Use this ID in the next step
console.log(fileUpload.upload_url) // URL to send file data to

​
Multi-part upload

For files larger than 20MB, split into parts: 
const totalParts = 5

const fileUpload = await client.fileUploads.create({
  mode: "multi_part",
  filename: "large-video.mp4",
  content_type: "video/mp4",
  number_of_parts: totalParts
})

console.log(fileUpload.id)
console.log(fileUpload.number_of_parts) // { total: 5, sent: 0 }

​
External URL import

Import a file from an external URL: 
const fileUpload = await client.fileUploads.create({
  mode: "external_url",
  external_url: "https://example.com/document.pdf",
  filename: "imported-document.pdf"
})

console.log(fileUpload.status) // Check import status

Build docs developers (and LLMs) love

Get started for freeTalk to us