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, labels, 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
labels[]	string[]	No	Filter by label IDs
source[]	string[]	No	Filter by source: canva, vista, postnitro, contentdrips, openai, favorites, upload
search	string	No	Full-text search on name or caption
embedded	boolean	No	Set true when calling from an embedded view

List Media

get

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

Query parameters

idsanyOptional

Specific media IDs to retrieve. If provided, pagination and other filters are ignored

pageanyOptional

Page number for pagination (0-based)

typesanyRequired

Filter by media types

usedanyRequired

Filter by used status

labelsanyOptional

Filter by label IDs

sourceanyOptional

Filter by source

searchanyOptional

Search term to filter media by name or caption

embeddedanyOptional

Indicates if the request is from an embedded view

Header parameters

Publer-Workspace-IdanyRequired

ID of the workspace to retrieve media from

Responses

200

Successful operation

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

get

HTTPcURLJavaScriptPython

GET /api/v1/media HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Accept: */*

{
  "media": [
    {
      "id": "5f5fe854421aa9792e762b70",
      "type": "photo",
      "name": "Beach sunset",
      "caption": "Beautiful sunset at the beach",
      "url": "https://cdn.publer.com/uploads/photos/5f5fe854421aa9792e762b70.jpg",
      "thumbnail": "https://cdn.publer.com/uploads/photos/thumb_5f5fe854421aa9792e762b70.jpg",
      "created_at": "2023-05-15T10:30:00Z",
      "updated_at": "2023-05-15T10:30:00Z",
      "favorite": true,
      "used": false,
      "source": "upload",
      "labels": [
        {
          "id": "5f6a1234421aa9792e762b71",
          "name": "Vacation",
          "color": "#FF5733"
        }
      ]
    }
  ],
  "total": 10
}

Notes

• Free trial users see placeholder data unless they supply specific query filters.

• Paid accounts have full library access.

Related Resources

• Accounts API — Manage connected social accounts

• Posts API — Create and schedule posts

• Media Upload — Upload new media files