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

# Media overview

> List, get, delete, upload files, or import URLs into your workspace library, then attach media by id or URL when creating posts

## Media API

Media endpoints manage the **workspace media library**. Each saved item has an **`id`** you can reference when you [create](/api-reference/posts/create) or [update](/api-reference/posts/update) a post, or in [comment `media`](/api-reference/comments/create).

All routes require the **`posts`** ability (same token scope as post CRUD).

| Method | Path                                                     | Purpose                                                                                                                                                                                                                                                              |
| ------ | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | [`/media`](/api-reference/media/list)                    | **Paginated list** (optional `workspace_id`, `folder_id`, or `root_only`)                                                                                                                                                                                            |
| GET    | [`/media/{media_id}`](/api-reference/media/get)          | **One item** by id                                                                                                                                                                                                                                                   |
| DELETE | [`/media/{media_id}`](/api-reference/media/delete)       | **Delete** library item and stored file                                                                                                                                                                                                                              |
| POST   | [`/media/upload/file`](/api-reference/media/upload-file) | **One multipart request** with `file` + `workspace_id` (optional `folder_id`); max **500MB** per file (same as in-app standard upload). **Host:** `https://upload.postsyncer.com/api/v1` (not `postsyncer.com`) - see that page for details and playground behavior. |
| POST   | [`/media/upload/url`](/api-reference/media/upload-url)   | **JSON** 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**](/api-reference/folders/list), then pass **`folder_id`** on upload endpoints to file media into the right library folder. Use **`folder_id`** or **`root_only`** on [List media](/api-reference/media/list) to scope results.

### See also

<CardGroup cols={2}>
  <Card title="List media" icon="list" href="/api-reference/media/list" />

  <Card title="Folders" icon="folder" href="/api-reference/folders/list" />

  <Card title="Upload from file" icon="upload" href="/api-reference/media/upload-file" />

  <Card title="Import from URL" icon="link" href="/api-reference/media/upload-url" />

  <Card title="Create post" icon="file-text" href="/api-reference/posts/create" />
</CardGroup>