Media library

The media library is your workspace’s central store of images and videos. Anything you want to attach to a post — feed photo, Reel, YouTube video, carousel image — lives here first. Media files are scoped to the workspace, so any team member (and any post in that workspace) can use them. They’re stored on a CDN and served via the link field on each media object.

Anatomy of a media item

{
  "id": "media_2b8a9c4d...",
  "name": "hero-shot.jpg",
  "full_name": "hero-shot.jpg",
  "label": null,
  "link": "https://cdn.publishbuddy.com/...",
  "size": 184293,
  "width": 1080,
  "height": 1080,
  "time": null,
  "folder_id": "folder_4c5d..."
}

Field	Notes
`id`	UUID — pass this in `media_content_ids` when creating a post.
`link`	Public, signed CDN URL. You can download from this URL directly.
`size`	Bytes.
`width` / `height`	Pixels. Null for files where dimensions don’t apply.
`time`	Duration in seconds for video files; null for images.
`folder_id`	Folder the file lives in (or the workspace root, represented by the workspace’s default folder).
`label`	Optional text label (useful for tagging / filtering in your own tooling).

Uploading

Uploads go directly to storage in three steps — the file bytes never pass through the API:

Presign — POST /workspaces/{workspace}/media_contents/presign with the files’ name, mime, and size. You get back a pre-signed upload_url (and a temporary media id) for each file, up to 10 per request.
Upload — PUT each file’s bytes straight to its upload_url, replaying the returned upload_headers.
Confirm — POST /workspaces/{workspace}/media_contents/confirm with the uuids from step 1. The API verifies each object, moves it into the library, and returns the finalized media objects.

The old multipart POST /media_contents upload endpoint has been removed from the public API. Always use the presign → upload → confirm flow.

See Upload and manage media for the full flow with examples, size limits, supported formats, and bulk-upload patterns.

Folders

Folders are an organisational layer on top of the library — purely for your team’s sanity, never visible to the social network. A folder has a name, a parent (so they nest), and an order index.

Endpoint	Purpose
`GET /workspaces/{workspace}/media_library/folders`	List the workspace’s folder tree.
`POST /workspaces/{workspace}/media_library/folders`	Create a new folder, optionally nested under a parent.
`PATCH /media_library/folders/{folder}`	Rename or move a folder.
`DELETE /media_library/folders/{folder}`	Delete a folder (its contents move to the workspace root).

The root of a workspace’s library is the workspace itself — files with no explicit folder live there.

Filtering and listing

GET /workspaces/{workspace}/media_contents supports:

folder_id — restrict to one folder
page / per_page — pagination, see Pagination

Replacing or relabeling a file

PUT /media_contents/{mediaContent} updates editable metadata — currently label and folder_id. The underlying binary is immutable; to replace a file, upload a new one and update any posts that reference the old ID.

Deletion

DELETE /media_contents/{mediaContent} is a soft delete. The file is removed from listings and can no longer be attached to new posts, but posts that already reference it continue to work — they hold their own reference to the media at the time of attachment, so deleting the library record won’t unbreak a scheduled post.

Upload media

Concrete upload recipes, including bulk import.

Posts

How media is referenced from a post.

Getting started

Core concepts

How-to guides

API essentials

Anatomy of a media item

Uploading

Folders

Filtering and listing

Replacing or relabeling a file

Deletion

Next

Upload media

Posts

​Anatomy of a media item

​Uploading

​Folders

​Filtering and listing

​Replacing or relabeling a file

​Deletion

​Next

Upload media

Posts

Anatomy of a media item

Uploading

Folders

Filtering and listing

Replacing or relabeling a file

Deletion

Next