Media

Media items are images, videos, documents, or audio files in your workspace library. Attach them to posts via their id.

The media object

{
  "id": "med_2Xa9kQ1mB3cD4eF5gH6iJ7kL8m",
  "file_name": "med_2Xa9kQ1mB3cD4eF5gH6iJ7kL8m.png",
  "original_name": "launch.png",
  "mime_type": "image/png",
  "size": 184320,
  "public_url": "https://api.socialit.com/uploads/ws_.../med_....png",
  "type": "image",
  "thumbnail_url": null,
  "preview_url": null,
  "width": 1200,
  "height": 630,
  "duration": null,
  "alt_text": null,
  "caption": null,
  "created_at": "2026-06-25T08:00:00.000Z",
  "updated_at": "2026-06-25T08:00:00.000Z"
}

Upload media

POST /v1/media/upload

Upload a file as multipart/form-data with a single file field. Videos kick off thumbnail generation asynchronously.

curl -X POST https://api.socialit.com/v1/media/upload \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@./launch.png"

Returns 201 with { "media": { ... } }. Files over the per-type size cap return 413 FileTooLarge.

List media

GET /v1/media

curl https://api.socialit.com/v1/media \
  -H "Authorization: Bearer sk_live_..."

{ "media": [ { "id": "med_...", "type": "image", "...": "..." } ] }

Get media

GET /v1/media/:id

curl https://api.socialit.com/v1/media/med_2Xa... \
  -H "Authorization: Bearer sk_live_..."

{ "media": { "id": "med_...", "...": "..." } }

Update media

PATCH /v1/media/:id

Update metadata: alt_text, caption, public_url, thumbnail_url.

curl -X PATCH https://api.socialit.com/v1/media/med_2Xa... \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "alt_text": "Product launch banner" }'

Delete media

DELETE /v1/media/:id

Soft-deletes the media item.

curl -X DELETE https://api.socialit.com/v1/media/med_2Xa... \
  -H "Authorization: Bearer sk_live_..."

{ "ok": true }