Uploading Media to FlowCMS

📅 Updated: Oct 12, 2025 👤 FlowCMS Engineering Media API Dashboard

Overview

FlowCMS provides multiple secure, high-performance methods for uploading media assets. Whether you're a content editor using the dashboard, a developer integrating via API, or an engineer automating deployments via CLI, our media pipeline handles optimization, CDN distribution, and metadata extraction automatically.

💡 Pro Tip

All uploaded media is automatically optimized for web delivery. We generate responsive breakpoints, convert images to WebP/AVIF, and compress videos using modern codecs without manual intervention.

Dashboard Upload

The quickest way to add media is through the FlowCMS Dashboard. Follow these steps:

Navigate to Media Library in the left sidebar.
Click the "Upload Files" button or drag and drop files directly onto the canvas.
Fill in optional metadata: title, description, alt text, and tags.
Click "Save & Publish". Your asset is instantly available via CDN.

Bulk uploads are supported. You can add up to 50 files at once, with automatic folder organization based on your content type structure.

REST API Upload

For programmatic workflows, use our multipart/form-data endpoint. Authentication requires a valid API token with media.write scope.

# Upload an image via cURL
curl -X POST https://api.flowcms.io/v1/media \\
  -H "Authorization: Bearer YOUR_API_TOKEN" \\
  -H "Content-Type: multipart/form-data" \\
  -F "file=@./hero-banner.jpg" \\
  -F "metadata={\"title\":\"Product Launch\",\"alt\":\"Marketing banner\",\"tags\":[\"campaign\",\"q4\"]}"
                    

// JavaScript / Node.js Example
const FormData = require('form-data');
const fs = require('fs');

const formData = new FormData();
formData.append('file', fs.createReadStream('./product.mp4'));
formData.append('metadata', JSON.stringify({
  title: 'Product Demo',
  type: 'video'
}));

const res = await fetch('https://api.flowcms.io/v1/media', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.FLOW_TOKEN}` },
  body: formData
});
                    

Supported Formats & Limits

Type	Formats	Max Size (Pro)	Auto-Optimization
Images	JPEG, PNG, WebP, SVG, AVIF, GIF	50 MB	✅ Responsive breakpoints + WebP/AVIF
Videos	MP4, WebM, MOV	2 GB	✅ H.264/H.265 encoding + thumbnails
Documents	PDF, DOCX, XLSX, PPTX	25 MB	⚠️ Preview generation + metadata extraction
Fonts	WOFF2, TTF, OTF	10 MB	✅ Subsetting + minification

Enterprise plans support custom format allowances and unlimited storage with dedicated CDN buckets.

Best Practices

Use descriptive filenames before upload. FlowCMS preserves them in URLs unless you enable SEO slugs.
Add alt text during upload for accessibility and SEO scoring.
Batch by campaign using tags. This makes future filtering and bulk operations significantly faster.
Leverage versioning. Every upload creates an immutable version. Use the API to manage rollbacks safely.
Monitor storage usage via the Dashboard analytics. We auto-archive assets older than 2 years on free tiers.

Troubleshooting

Common Errors

❌ 413 Payload Too Large

Occurs when exceeding your plan's file size limit. Upgrade your tier or compress the asset before uploading.

❌ 403 Forbidden (Scope Missing)

Your API token lacks the media.write permission. Regenerate the token in Settings → API Keys.

❌ 422 Unprocessable Entity

Invalid metadata JSON or unsupported file extension. Validate your payload structure against the schema.

For additional help, visit our Community Forum or contact Priority Support.