PublishQPublishQ

List media

GET
/media

Return your uploaded and generated media files. You can filter by ID, type, and source before reusing them in posts.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

PublishQ API key sent as Authorization: Bearer pq_live_....

In: header

Query Parameters

page?integer

Page number (starts from 1).

Default1
Range0 < value
limit?integer

Page size. Max 100.

Default20
Range0 < value <= 100
ids?array<>

Return only the specified media IDs. Repeat the parameter to apply OR logic, for example ?ids=id1&ids=id2.

mediaTypes?array<>

Return only media items of the specified types. Repeat the parameter to apply OR logic, for example ?mediaTypes=image&mediaTypes=video.

sources?array<>

Return only media items from the specified sources. Repeat the parameter to apply OR logic, for example ?sources=upload&sources=ai_generated.

folderPath?string

Return only files in this folder, for example Channel A/Shorts. Send it empty (?folderPath=) for files at the top level. Leave it out to list the whole library.

includeSubfolders?boolean

With folderPath, also return files in its subfolders at every level. With an empty folderPath it returns the whole library.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://publishq.com/api/v1/media"
{
  "media": [
    {
      "id": "f6370ca1-1f47-4f68-be72-c1206913b326",
      "type": "IMAGE",
      "url": "https://cdn.publishq.com/uploads/images/f6370ca1-1f47-4f68-be72-c1206913b326.png",
      "source": "UPLOAD",
      "created_at": "2026-03-28T16:25:41.000Z",
      "usageCount": 3,
      "folderPath": "Channel A/Shorts"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5,
    "hasNext": true,
    "hasPrev": false
  }
}
{
  "error": {
    "title": "Bad Request",
    "status": 400,
    "code": "validation_failed",
    "message": "Folder name cannot be empty",
    "instance": "/api/v1/media"
  }
}

{
  "error": {
    "title": "Unauthorized",
    "status": 401,
    "code": "missing_auth",
    "message": "Missing Authorization header",
    "instance": "/api/v1/posts"
  }
}

{
  "error": {
    "title": "Too Many Requests",
    "status": 429,
    "code": "rate_limit_exceeded",
    "message": "Too Many Requests",
    "instance": "/api/v1/media",
    "details": {
      "retryAfter": 60
    }
  }
}