POST/media/upload
Upload images and video with the PostEverywhere API
TWO modes, selected by the request Content-Type. **DIRECT mode (images only, recommended for API clients).** Send `multipart/form-data` with the file in a field named `file` (optional `filename` field to override the name). The upload completes in this single request and the response returns `media_status: "ready"` with `upload_required: false`, no `upload_url`, no `/complete` call. Max 25 MB. Videos sent this way get `415` with instructions. **PRESIGNED mode (all types).** Send file METADATA as JSON. Returns an `upload_url` plus `upload_method` describing how to send the bytes: - images → POST `multipart/form-data`, field name `file` (Cloudflare Images direct upload) - videos (MP4 only) and PDFs → PUT with the declared `Content-Type` (R2 presigned URL) Then you MUST call `POST /media/{media_id}/complete`, or the media stays `uploading` forever otherwise. `expires_at` is authoritative (image URLs last 6 hours, video/PDF URLs 1 hour). Size caps: 20 MB images/PDFs, 500 MB video. Upload quota is only consumed at `/complete`, so retries here are free. **Presigned image caveat**: the image upload host runs an edge bot filter outside our control. Send any custom `User-Agent` header; Python stdlib's default (`Python-urllib/x`) is rejected with HTTP 403 error 1010. `python-requests`, `curl`, node, Go and empty User-Agents all pass. DIRECT mode has no such restriction from any client. Error codes: `validation_error`, `unsupported_media_type`, `file_too_large` (413), `length_required` (411, direct mode), `storage_quota_exceeded` (403), `rate_limit_exceeded`, `service_unavailable`.
Guide: Media requirements by platform
This endpoint accepts a JSON request body. See the media guide for a worked example.
Responses
- 201Presigned mode: an upload ticket (`upload_url` + `upload_method`, then call `/complete`). Direct mode: the finished media, `media_status: "ready"`, `upload_required: false`, `url` set; attach `media_ids` to a post immediately.
- 400
- 401
- 402
- 403
- 429
- 500