Media Uploads
Upload images and videos to use in your scheduled posts via the SocialRails API.
Upload images and videos to attach to your social media posts. Media is stored securely in cloud storage and can be referenced by the key field when creating posts.
Upload a File
POST /api/v1/media/upload
Upload a file using multipart form data. Maximum file size is 10MB.
Supported formats:
Optional type parameter
You can specify the media type via a form field or query parameter. This controls how the file is stored and processed by the publishing system.
If omitted, the type is auto-detected from the content type (images → image, videos → video).
Example: Upload an image
curl -X POST https://socialrails.com/api/v1/media/upload \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-F "file=@my-photo.jpg"Example: Upload a video thumbnail
curl -X POST https://socialrails.com/api/v1/media/upload \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-F "file=@thumbnail.jpg" \
-F "type=thumbnail"Response
{
"data": {
"media_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"key": "workspace-id/api-uploads/images/a1b2c3d4-e5f6-7890-abcd-ef1234567890.jpg",
"type": "image",
"url": "https://media.socialrails.com/workspace-id/api-uploads/images/a1b2c3d4.jpg",
"content_type": "image/jpeg",
"size": 245760
}
}The key field is the storage key, use this when attaching media to posts.
Upload from URL
POST /api/v1/media/upload-url
Provide a URL and SocialRails will fetch and store the media for you.
Request Body
{
"url": "https://example.com/my-image.png",
"type": "image"
}The type field is optional, same values as the file upload (image, video, thumbnail).
Example
curl -X POST https://socialrails.com/api/v1/media/upload-url \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/my-image.png"}'Response
Same format as the direct upload response (includes media_id, key, type, url, content_type, and size).
Using Media in Posts
Image posts
Upload the image, then pass its key in the media array:
curl -X POST https://socialrails.com/api/v1/posts \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Check out this photo!",
"platform": "twitter",
"media": ["workspace-id/api-uploads/images/a1b2c3d4.jpg"],
"scheduled_for": "2026-03-05T10:00:00Z"
}'Video posts
For video posts, upload both the video and a thumbnail image. Include both keys in the media array:
# Step 1: Upload the video
VIDEO=$(curl -s -X POST https://socialrails.com/api/v1/media/upload \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-F "file=@my-video.mp4")
VIDEO_KEY=$(echo $VIDEO | jq -r '.data.key')
# Step 2: Upload the thumbnail
THUMB=$(curl -s -X POST https://socialrails.com/api/v1/media/upload \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-F "file=@thumbnail.jpg" \
-F "type=thumbnail")
THUMB_KEY=$(echo $THUMB | jq -r '.data.key')
# Step 3: Create the post with both
curl -X POST https://socialrails.com/api/v1/posts \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d "{
\"content\": \"Watch our latest video!\",
\"platform\": \"tiktok\",
\"media\": [\"$VIDEO_KEY\", \"$THUMB_KEY\"],
\"scheduled_for\": \"2026-03-05T10:00:00Z\"
}"The thumbnail is used as a cover image on platforms that support it (e.g. Pinterest, YouTube) and is automatically excluded from regular media processing on other platforms.
Multiple images (carousel)
Upload multiple images and pass all keys in the media array. Platform limits apply (e.g. Twitter allows up to 4 images, Instagram up to 10):
curl -X POST https://socialrails.com/api/v1/posts \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Check out our new product line!",
"platform": "instagram",
"media": ["key1.jpg", "key2.jpg", "key3.jpg"],
"scheduled_for": "2026-03-05T10:00:00Z"
}'Platform Media Requirements
Limits
- File size: 10MB maximum per upload
- Scope required:
write - Standard rate limits apply (media uploads count as 1 request each)
- URL uploads must be HTTPS and return a supported content type