Skip to main content

​
Media API

Media endpoints manage the workspace media library. Each saved item has an id you can reference when you create or update a post, or in comment media. All routes require the posts ability (same token scope as post CRUD).
MethodPathPurpose
GET/mediaPaginated list (optional workspace_id, folder_id, or root_only)
GET/media/{media_id}One item by id
DELETE/media/{media_id}Delete library item and stored file
POST/media/upload/fileOne multipart request with file + workspace_id (optional folder_id); max 500MB per file (same as in-app standard upload)
POST/media/upload/urlJSON body: import one or more URLs (direct image/video links, supported social links, Unsplash, etc.)

​
Using media on posts

In content[].media, each element may be either:
  • Integer — library id from list, get, upload/file, or upload/url (must belong to the same workspace_id as the post).
  • String (URL) — public HTTPS link to an image or video; the API validates and processes it when the post is saved.
You can mix ids and URLs in the same media array. Typical flows:
  1. File on disk → POST /media/upload/file with the file → read media.id → include that id in POST /posts … content[].media.
  2. Already on the web → either paste the URL directly in content[].media, or call POST /media/upload/url first to store a copy in the library and then use the returned id.
  3. Browse library → GET /media?workspace_id=… to discover ids.

​
Limits and infrastructure

  • File upload is limited to 500MB per request.
  • URL import may return multiple media objects for a single input URL (e.g. some social posts). Check count_stored and each item’s id.

​
Folders

Create and list folders with Folders API, then pass folder_id on upload endpoints to file media into the right library folder. Use folder_id or root_only on List media to scope results.

​
See also

List media

Folders

Upload from file

Import from URL

Create post