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 are stored on a CDN and served via the link field on each media object. The media library endpoints are available on the Pro and Business plans. On a workspace whose owner is on Free they return 402.

Anatomy of a media item

{
  "id": "9b1f2c3d-5a6e-7f8a-9b0c-1d2e3f4a5b6c",
  "name": "hero-shot.jpg",
  "full_name": "library/9b1f.../hero-shot.jpg",
  "label": null,
  "link": "https://cdn.publishbuddy.com/...",
  "status": "active",
  "error_message": null,
  "size": 184293,
  "width": 1080,
  "height": 1080,
  "time": null,
  "thumbnail": null,
  "folder_id": "8c2d3e4f-6b7a-8c9d-0e1f-2a3b4c5d6e7f"
}

Field	Notes
`id`	UUID. Pass this in `media_ids` when creating a post.
`name` / `full_name`	The stored file name and its full storage key.
`link`	Public URL. You can download from this URL directly. Final once `status` is `active`; while an item is `processing`, `name`, `full_name`, and `link` can still change.
`status`	`active`, `processing`, `failed`, or `temporary`. See Media status.
`error_message`	Why a URL import failed. `null` unless `status` is `failed`.
`size`	Bytes.
`width` / `height`	Pixels. `null` for files where dimensions do not apply.
`time`	Duration in seconds for video files; `null` for images.
`thumbnail`	For videos, a nested media object for the cover image; `null` for images.
`folder_id`	Folder the file lives in, or `null` when it sits at the root of the library.
`label`	Optional text label (useful for tagging and filtering in your own tooling).

Uploading

POST /workspaces/{workspace}/media_contents is the one way to add media. Give it a URL or a file:

A URL: a JSON body with url (plus optional name, label, folder_id). Images of up to 50 MB come back ready: 201 with the item active. Videos, and files larger than 50 MB, come back processing with 202: poll GET /media_contents/{mediaContent} until the item is active or failed. A URL that announces more than 2 GB is refused with 413.
Files: a multipart/form-data body with 1 to 10 files in files[] (plus optional label and folder_id), up to 200 MB each. Every file is stored during the request: 201 with each item active. A larger file is refused with 413.

The type of every file is read from its bytes: JPEG, PNG, GIF, WebP, MP4, and QuickTime are accepted. For a file over the 200 MB request-body limit (up to 2 GB), upload it directly to storage in three steps instead. The file bytes never pass through the API:

Presign: POST /workspaces/{workspace}/media_contents/presign with each file’s 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 IDs from step 1 as media_ids. The API verifies each object, moves it into the library, and returns the finalized media objects. Confirming is all or nothing: if any file hasn’t been uploaded, nothing is confirmed and the response is a 422 naming those IDs.

See Upload and manage media for both bodies with examples, polling, errors, size limits, and bulk-upload patterns.

Media status

Every media response carries status, and error_message when an import failed:

`status`	Meaning	Usable in a post
`active`	The file is in the library.	Yes
`processing`	A URL import is still downloading. Poll `GET /media_contents/{mediaContent}`.	No, `422`
`failed`	A URL import failed. `error_message` says why; import or upload the file again.	No, `422`
`temporary`	A presigned upload that is not confirmed yet.	Only once its file is in storage; before that, `422`

A post that references a processing or failed item gets a 422 that names the item and tells you to poll it or to import it again.

Folders

Folders are an organisational layer on top of the library, purely for your team, and never visible to the social network. A folder has an id, a name, a parent_id (so folders nest; null at the top level), and an is_system flag. System folders are created by PublishBuddy and cannot be renamed or deleted; trying either returns 422.

Endpoint	Purpose
`GET /workspaces/{workspace}/media_library/folders`	List folders one level at a time. Omit `parent_id` (or pass `root`) for top-level folders, or pass a folder UUID for its children.
`POST /workspaces/{workspace}/media_library/folders`	Create a folder with a `name`, optionally nested under `parent_id`.
`GET /media_library/folders/{folder}`	Show one folder.
`PATCH /media_library/folders/{folder}`	Rename a folder, or move it by changing `parent_id` (`null` moves it to the top level).
`DELETE /media_library/folders/{folder}`	Delete the folder together with its subfolders and the files inside them. Move files out first if you want to keep them.

Files with no folder live at the root of the library.

Filtering and listing

GET /workspaces/{workspace}/media_contents supports:

folder_id: a folder UUID to list one folder, or root for files that are not in any folder. Omit it to list everything.
status: active (the default), processing, failed, or temporary. Without it the list hides URL imports still downloading, imports that failed, and presigned uploads not confirmed yet.
page / per_page: pagination, default 20 per page. See Pagination.

Relabeling or moving a file

PUT /media_contents/{mediaContent} updates editable metadata: label and folder_id (set folder_id to null to move the file back to the root). 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 does not break 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

Media status

Folders

Filtering and listing

Relabeling or moving a file

Deletion

Next

Upload media

Posts

​Anatomy of a media item

​Uploading

​Media status

​Folders

​Filtering and listing

​Relabeling or moving a file

​Deletion

​Next

Upload media

Posts

Anatomy of a media item

Uploading

Media status

Folders

Filtering and listing

Relabeling or moving a file

Deletion

Next