> ## Documentation Index
> Fetch the complete documentation index at: https://docs.publishbuddy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Media library

> Upload, organise, and reuse images and videos across all your posts.

The **media library** is your workspace's central store of images and videos. Anything you want to attach to a [post](/concepts/posts) — 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

```jsonc theme={null}
{
  "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:

1. **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.
2. **Upload** — `PUT` each file's bytes straight to its `upload_url`, replaying the returned `upload_headers`.
3. **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.

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

See [Upload and manage media](/guides/upload-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](/api-essentials/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.

## Next

<CardGroup cols={2}>
  <Card title="Upload media" icon="upload" href="/guides/upload-media">
    Concrete upload recipes, including bulk import.
  </Card>

  <Card title="Posts" icon="paper-plane" href="/concepts/posts">
    How media is referenced from a post.
  </Card>
</CardGroup>