Upload 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"
}

POST/v1/media/upload

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

{
  "media": {
    "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"
  }
}

Files over the per-type size cap return 413 FileTooLarge.

List Media

GET/v1/media

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

Get Media

GET/v1/media/:id

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

Update Media

PATCH/v1/media/:id

Update metadata: alt_text, caption, public_url, thumbnail_url.

PATCH /v1/media/:id

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" }'

{
  "media": {
    "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"
  }
}

Delete Media

DELETE/v1/media/:id

Soft-deletes the media item.

{ "ok": true }