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.

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

#### Query Parameters

| Parameter     | Type            | Required | Description                                                    |
|---------------|-----------------|----------|----------------------------------------------------------------|
| `ids[]`      | string[]        | No       | Specific media IDs (pagination and other filters ignored when set) |
| `page`       | integer         | No       | Page number (0-based). Default: 0                            |
| `types[]`    | string[]        | Yes      | Filter by media type: `photo`, `video`, `gif`                |
| `used[]`     | boolean[]       | Yes      | Filter by usage status                                        |
| `source[]`   | string[]        | No       | Filter by source: `canva`, `vista`, `postnitro`, `contentdrips`, `openai`, `favorites`, `upload` |
| `search`     | string          | No       | Full-text search on name or caption                             |

### List Media

get

https://app.publer.com/api/v1/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.

**Authorizations**

- **BearerApiAuth**  
  - **Authorization**: string **Required**  
    API key authentication. Format: "Bearer-API YOUR_API_KEY"

**Query parameters**

- **ids**: string[] Optional  
  Specific media IDs to retrieve. If provided, pagination and other filters are ignored
- **page**: integer Optional  
  Page number for pagination (0-based)
- **types**: string · enum[] Required  
  Filter by media types
- **used**: boolean[] Required  
  Filter by used status
- **source**: string · enum[] Optional  
  Filter by source
- **search**: string Optional  
  Search term to filter media by name or caption

**Header parameters**

- **Publer-Workspace-Id**: string **Required**  
  ID of the workspace to retrieve media from

**Responses**

- **200**  
  Successful operation
- **application/json**
  media object[] Optional
  total integer Optional
  Total count of media items matching the query (without pagination)
  Example: `10`
- **401**  
  Unauthorized
- **403**  
  Permission denied or missing required scope

Example:
```json
{
  "media": [
    {
      "id": "5f5fe854421aa9792e762b70",
      "type": "photo",
      "name": "Beach sunset",
      "caption": "Beautiful sunset at the beach",
      "path": "https://cdn.publer.com/uploads/photos/5f5fe854421aa9792e762b70.jpg",
      "thumbnails": [
        {
          "id": "5f6a1234421aa9792e762b71",
          "small": "text",
          "real": "text"
        }
      ],
      "created_at": "2023-05-15T10:30:00Z",
      "updated_at": "2023-05-15T10:30:00Z",
      "favorite": true,
      "in_library": false
    }
  ],
  "total": 10
}
```

### Notes

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