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.

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

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

AuthorizationstringRequired

API key authentication. Format: "Bearer-API YOUR_API_KEY"

Query parameters

idsstring[]Optional

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

pageintegerOptional

Page number for pagination (0-based)

usedboolean[]Required

Filter by used status

searchstringOptional

Search term to filter media by name or caption

Header parameters

Publer-Workspace-IdstringRequired

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

/media

HTTPcURLJavaScriptPython

GET /api/v1/media?types=photo&used=true HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "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.

Related Resources

• Accounts API — Manage connected social accounts

• Posts API — Create and schedule posts

• Media Upload — Upload new media files