Skip to main content
POST
Upload media file
For attaching media from a public URL instead of uploading bytes, use POST /posts/{post}/media/from-url.

Path parameters

string
required
The UUID of the post to attach the file to.

Request

Send as multipart/form-data with a single media field.
file
required
The file to upload. Must be one of the allowed types:
Supported media types:
  • Images: image/jpeg, image/png, image/gif, image/webp - up to 10 MB
  • Videos: video/mp4, video/quicktime (MOV) - up to 1 GB

Behaviour

  • The post must belong to the caller’s current workspace; otherwise the response is 404.
  • The file’s MIME type is intersected with the platforms enabled on the post. For example, uploading an image to a TikTok-only post returns 422 unless the post targets tiktok_photo.
  • Per-type size caps are enforced after MIME detection. A video over 1 GB returns 422 even if the request’s overall cap allowed it.
  • PNG and WebP still images are normalized to JPEG (q100) at storage time for universal platform compatibility. GIF is preserved (animation kept for X / Bluesky / Mastodon). MP4 and MOV videos are stored as-is.
  • The new media is stored under medias/{uuid}.{ext} on the configured filesystem disk (local, s3, or r2) and appended to the post’s media[] array.

Response

Returns the updated post — same shape as GET /posts/{post}, with the newly-uploaded item in media[]. On validation failure (unsupported type, file too large, no enabled platform accepts the type) the response is 422 with errors.media[].