# Media

The Media API lets you list and filter items in your library. You can page through results, query by IDs, or apply filters such as type, usage status, source, and search terms.

### Requirements

* **Authentication**: Bearer API token
* **Scope**: `media`
* **Headers**:
  * `Authorization: Bearer-API YOUR_API_KEY`
  * `Publer-Workspace-Id: YOUR_WORKSPACE_ID`

### Endpoint

#### List Media

Retrieve all social media accounts in a workspace.

```http
GET /api/v1/media
```

#### Query Parameters

<table><thead><tr><th width="108.32867431640625">Parameter</th><th width="96.4034423828125">Type</th><th width="86.43267822265625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>ids[]</code></td><td>string[]</td><td>No</td><td>Specific media IDs (pagination and other filters ignored when set)</td></tr><tr><td><code>page</code></td><td>integer</td><td>No</td><td>Page number (0-based). Default: 0</td></tr><tr><td><code>types[]</code></td><td>string[]</td><td>Yes</td><td>Filter by media type: <code>photo</code>, <code>video</code>, <code>gif</code></td></tr><tr><td><code>used[]</code></td><td>boolean[]</td><td>Yes</td><td>Filter by usage status</td></tr><tr><td><code>source[]</code></td><td>string[]</td><td>No</td><td>Filter by source: <code>canva</code>, <code>vista</code>, <code>postnitro</code>, <code>contentdrips</code>, <code>openai</code>, <code>favorites</code>, <code>upload</code></td></tr><tr><td><code>search</code></td><td>string</td><td>No</td><td>Full-text search on name or caption</td></tr></tbody></table>

## List Media

> Retrieves a paginated list of media items from the user's library. The endpoint supports filtering by various parameters and can also retrieve specific media items by their IDs.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Media","description":"Endpoints for uploading and managing media files"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"BearerApiAuth":[]}],"components":{"securitySchemes":{"BearerApiAuth":{"type":"apiKey","name":"Authorization","in":"header","description":"API key authentication. Format: \"Bearer-API YOUR_API_KEY\""}},"schemas":{"401ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/media":{"get":{"summary":"List Media","description":"Retrieves a paginated list of media items from the user's library. The endpoint supports filtering by various parameters and can also retrieve specific media items by their IDs.","tags":["Media"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve media from","required":true},{"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"name":"ids","in":"query","description":"Specific media IDs to retrieve. If provided, pagination and other filters are ignored","required":false},{"schema":{"type":"integer"},"name":"page","in":"query","description":"Page number for pagination (0-based)","required":false},{"schema":{"type":"array","items":{"type":"string","enum":["photo","video","gif"]}},"style":"form","explode":false,"name":"types","in":"query","description":"Filter by media types","required":true},{"schema":{"type":"array","items":{"type":"boolean"}},"style":"form","explode":false,"name":"used","in":"query","description":"Filter by used status","required":true},{"schema":{"type":"array","items":{"type":"string","enum":["canva","vista","postnitro","contentdrips","openai","favorites"]}},"style":"form","explode":false,"name":"source","in":"query","description":"Filter by source","required":false},{"schema":{"type":"string"},"name":"search","in":"query","description":"Search term to filter media by name or caption","required":false}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"type":"object","properties":{"media":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the media"},"type":{"type":"string","description":"Type of media","enum":["photo","video","gif"]},"name":{"type":"string","description":"Name of the media"},"caption":{"type":"string","description":"Caption for the media"},"path":{"type":"string","description":"URL to the full media"},"thumbnails":{"type":"array","description":"Array of thumbnails objects associated with the media","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thumbnail"},"small":{"type":"string","description":"URL to the small thumbnail"},"real":{"type":"string","description":"URL to the real thumbnail"}}}},"created_at":{"type":"string","format":"date-time","description":"Creation timestamp"},"updated_at":{"type":"string","format":"date-time","description":"Last update timestamp"},"favorite":{"type":"boolean","description":"Whether the media is marked as favorite"},"in_library":{"type":"boolean","description":"Whether the media is saved in the library"}}}},"total":{"type":"integer","description":"Total count of media items matching the query (without pagination)"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}}
```

### Notes

* Free trial users see placeholder data unless they supply specific query filters.
* Paid accounts have full library access.

### Related Resources

* [Accounts API](https://publer.com/docs/api-reference/accounts) — Manage connected social accounts
* [Posts API](https://publer.com/docs/posting/create-posts) — Create and schedule posts
* [Media Upload](https://publer.com/docs/posting/create-posts/media-handling) — Upload new media files