Media Uploads
Upload images, videos and PDF documents to use in your scheduled posts via the SocialRails API.
Upload images, videos and PDF documents 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 for images, 100MB for videos and PDF documents.
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, PDFs → document).
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.
PDF document posts (LinkedIn carousels)
Upload a PDF with type=document and attach it to a LinkedIn post. It renders as a native swipeable carousel:
# Step 1: Upload the PDF
DOC=$(curl -s -X POST https://socialrails.com/api/v1/media/upload \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-F "file=@report.pdf" \
-F "type=document")
DOC_KEY=$(echo $DOC | jq -r '.data.key')
# Step 2: Create the LinkedIn post
curl -X POST https://socialrails.com/api/v1/posts \
-H "Authorization: Bearer sr_live_YOUR_KEY" \
-H "Content-Type: application/json" \
-d "{
\"content\": \"Swipe through our latest report 👇\",
\"platform\": \"linkedin\",
\"media\": [\"$DOC_KEY\"],
\"scheduled_for\": \"2026-06-10T08:30:00Z\"
}"PDF documents are LinkedIn-only: one PDF per post, no other media alongside it, max 100MB / 300 pages. Set platform_settings.linkedin.document_title to control the title shown above the carousel (defaults to the PDF's filename).
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 for images, 100MB for videos and PDF documents
- 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