Skip to main content

​
Overview

You have two ways to upload files.
  1. Simple Upload: Quick, easy, for small stuff.
  2. Resumable Upload: Robust, 3-step process, for big videos.
Recommendation: Always use the Resumable Upload for videos. It’s more reliable. If a 1GB upload fails at 99% with the Simple method, you start over. With Resumable, you don’t.

​
Method 1: Resumable Upload (The Pro Way)

Ideal for videos or anything >25MB.

​
Step 1: Initialize

Tell us what you’re planning to upload. Endpoint: POST /upload/init 
// Request
{
  "fileName": "viral-video.mp4",
  "mimeType": "video/mp4",
  "teamId": "..." // optional
}
Response: We give you a magic url (Pre-signed URL) and a path. Keep them safe. 
{
  "url": "https://storage.googleapis.com/...",
  "path": "uploads/123/viral-video.mp4"
}
The pre-signed URL expires after 10 minutes. If you don’t start uploading within that window, you’ll need to initialize again. Don’t go make coffee between Step 1 and Step 2.

​
Step 2: Push the Bytes

Send the raw binary file to the url we gave you. Use PUT.
Important: Do not wrap this in JSON or Multipart form. Just send the raw bytes.
curl -X PUT "https://storage.googleapis.com/..." \
  --upload-file ./viral-video.mp4

​
Step 3: Finalize

Tell us you’re done so we can register the file in our system. Endpoint: POST /upload/finalize 
// Request
{
  "path": "uploads/123/viral-video.mp4", // from Step 1
  "teamId": "..."
}
Response: You get an id (e.g., upload_abc123). This is the ID you use when creating a post.

​
Method 2: Simple Upload (The Lazy Way)

Good for images or small clips. Uses standard multipart/form-data. Endpoint: POST /upload/create 
curl -X POST "https://api.bundle.social/upload/create" \
  -H "x-api-key: YOUR_KEY" \
  -F "file=@./meme.jpg" \
  -F "teamId=YOUR_TEAM_ID"
Response: Returns the id immediately.

​
Supported Formats & Limits

TypeFormatsMax Size
ImagesJPG, PNG, GIF, WebP25 MB
VideosMP4Platform-dependent (see Limits)
The max video size depends on the platform you’re posting to. TikTok allows up to 4 GB, YouTube up to 256 GB, while Discord caps at 25 MB. Check Platform Limits for the exact numbers per platform.
Tip: If you are uploading a picture of your cat (or your mom, we don’t judge), Simple Upload is fine. For a 4K podcast clip, use Resumable.

​
Video Compression

You can enable automatic video compression on your organization. When enabled, we’ll compress videos larger than 10 MB before they’re stored and posted.

​
How to enable

Video compression is an organization-level setting. You can toggle it from your dashboard or contact us to enable it. Once on, it applies to all uploads across all teams in your org.

​
What happens

SettingValue
ThresholdVideos > 10 MB
Output formatMP4 (H.264 + AAC)
QualityCRF 30 (good balance of quality and size)
PresetMedium
We’re smart about it - if the compressed file ends up larger than the original (rare, but it happens with already-compressed videos), we keep the original and toss the compressed version. You always get the smaller file.
This is great if your users upload raw or minimally compressed videos. A 500 MB screen recording can often shrink to under 100 MB with no visible quality loss. Your storage costs will thank you - and so will the upload speeds.