---
title: "Media library"
description: "Browse a social set's media library via the Pallyy API, filter by folder, type, or name, and reference items when creating posts."
category: "endpoints"
emoji: "🖼️"
order: 3
datePublished: "2026-08-20"
dateUpdated: "2026-08-20"
---

Each social set has its own media library holding the images and videos you post. Posts created via the API reference library items by id, so browsing the library is how you find the `mediaLibraryId` values that [post sets](/docs/api/post-sets) need.

The library is read-only over the API. To add files, use [media uploads](/docs/api/media-uploads).

## List media

```
GET /v1/media
```

| Parameter | Required | Meaning |
| --- | --- | --- |
| `socialSetId` | Yes | The social set whose library to list |
| `page`, `size` | No | See [pagination](/docs/api/pagination) |
| `filters[folderId]` | No | Only items in this folder |
| `filters[type]` | No | `image` or `video` |
| `filters[name]` | No | Name search |
| `filters[withScheduledPosts]` | No | `true` or `false`, whether the item is used by scheduled posts |
| `sort[name]`, `sort[timestamp]` | No | `ASC` or `DESC` |

```bash
curl "https://app.pallyy.com/api/v1/media?socialSetId=SET_ID&filters[type]=image&sort[timestamp]=DESC" \
  -H "Authorization: Bearer pallyy_your_api_key"
```

## Get a media item

```
GET /v1/media/{id}
```

Returns a single item, or a `404` if it does not exist or is outside the key's access.

## The media object

```json
{
  "id": "665f1c2ab7e2a4d1f0a1b2c5",
  "socialSetId": "665f1c2ab7e2a4d1f0a1b2c3",
  "type": "image",
  "name": "latte.jpg",
  "fileName": "latte.jpg",
  "mimeType": "image/jpeg",
  "size": 245133,
  "width": 1080,
  "height": 1350,
  "url": "https://...",
  "thumbnailUrl": "https://...",
  "usage": { "scheduledPosts": 2 },
  "timestamp": "2026-08-01T10:00:00.000Z"
}
```

| Field | Type | Meaning |
| --- | --- | --- |
| `id` | string | The media id, used as `mediaLibraryId` in post sets |
| `socialSetId` | string | The social set the item belongs to |
| `type` | string | `image` or `video` |
| `name`, `fileName` | string | Display name and original file name |
| `mimeType` | string | The file's MIME type |
| `size` | number | File size in bytes |
| `width`, `height` | number | Dimensions in pixels |
| `duration` | number | Video duration in seconds, videos only |
| `videoBitrate`, `audioBitrate` | number | Bitrates, videos only |
| `folderId` | string | The library folder, if the item is in one |
| `caption` | string | A saved caption, if set in Pallyy |
| `url`, `thumbnailUrl` | string | URLs to the file and its thumbnail |
| `usage.scheduledPosts` | number | How many scheduled posts use this item |
| `timestamp` | string | ISO 8601 time the item was added |