> For the complete documentation index, see [llms.txt](https://publer.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://publer.com/docs/api-reference/media.md). # 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
ParameterTypeRequiredDescription
ids[]string[]NoSpecific media IDs (pagination and other filters ignored when set)
pageintegerNoPage number (0-based). Default: 0
types[]string[]YesFilter by media type: photo, video, gif
used[]boolean[]YesFilter by usage status
source[]string[]NoFilter by source: canva, vista, postnitro, contentdrips, openai, favorites, upload
searchstringNoFull-text search on name or caption
folder_idstringNoRestrict results to one folder. Omit for items not in any folder.
## 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. * `page` is **zero-based** and the page size is fixed at **20**. There is no `per_page` parameter. * When `ids[]` is supplied, pagination and all other filters are ignored. {% hint style="warning" %} This endpoint lists **library items only**. Media uploaded without `in_library: true` will never appear here, no matter how long you wait — see Uploading media. {% endhint %} ### Get Media Item Retrieve a single media item. ```http GET /api/v1/media/{id} ``` > Retrieves a single media item including its per-network compatibility matrix. ## Get Media Item > Retrieves a single media item including its per-network compatibility matrix. ```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":{"MediaLibraryItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier"},"name":{"type":"string","description":"Display name, used by library search"},"caption":{"type":"string","description":"Caption, also searchable"},"type":{"type":"string","description":"Media type","enum":["photo","video","gif"]},"path":{"type":"string","description":"URL of the media. While an upload is still processing this is a temporary path; it becomes the permanent URL once processing finishes."},"favorite":{"type":"boolean"},"in_library":{"type":"boolean"},"width":{"type":"number"},"height":{"type":"number"},"size":{"type":"number"},"source":{"type":"string"},"folder_id":{"type":"string"},"created_at":{"type":"string"},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"}}}},"thumbnail":{"type":"string","description":"Photos and GIFs only"},"thumbnails":{"type":"array","description":"Videos only","items":{"type":"object","properties":{"id":{"type":"string"},"small":{"type":"string"},"real":{"type":"string"}}}},"validity":{"type":"object","description":"Per-network compatibility for this item, derived from size, dimensions, format and duration"}}},"401ErrorResponseWithWorkspace":{"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/{id}":{"get":{"summary":"Get Media Item","tags":["Media"],"description":"Retrieves a single media item including its per-network compatibility matrix.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the resource"},{"schema":{"type":"string"},"name":"id","in":"path","required":true,"description":"ID of the media item"}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaLibraryItem"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Permission denied or missing required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}} ``` The `validity` object reports whether this item can be published on each network and format, derived from its size, dimensions, type and duration: ```json { "validity": { "instagram": { "post": true, "reel": true, "story": false }, "twitter": true, "tiktok": false } } ``` {% hint style="info" %} **Checking whether an upload has finished.** This endpoint does not return an explicit processing status. While an upload is still being processed `path` holds a temporary location, and it becomes the permanent URL once processing completes. For a reliable signal, use the `job_id` returned by `POST /api/v1/media/from-url` and poll Job Status instead of polling this endpoint. {% endhint %} *** ### Update Media Item Change a media item's metadata. ```http PUT /api/v1/media/{id} ``` ## Update Media Item > Updates the editable metadata of a media item: name, caption, favourite flag, folder and labels. ```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":{"MediaLibraryItem":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier"},"name":{"type":"string","description":"Display name, used by library search"},"caption":{"type":"string","description":"Caption, also searchable"},"type":{"type":"string","description":"Media type","enum":["photo","video","gif"]},"path":{"type":"string","description":"URL of the media. While an upload is still processing this is a temporary path; it becomes the permanent URL once processing finishes."},"favorite":{"type":"boolean"},"in_library":{"type":"boolean"},"width":{"type":"number"},"height":{"type":"number"},"size":{"type":"number"},"source":{"type":"string"},"folder_id":{"type":"string"},"created_at":{"type":"string"},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"}}}},"thumbnail":{"type":"string","description":"Photos and GIFs only"},"thumbnails":{"type":"array","description":"Videos only","items":{"type":"object","properties":{"id":{"type":"string"},"small":{"type":"string"},"real":{"type":"string"}}}},"validity":{"type":"object","description":"Per-network compatibility for this item, derived from size, dimensions, format and duration"}}},"401ErrorResponseWithWorkspace":{"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/{id}":{"put":{"summary":"Update Media Item","tags":["Media"],"description":"Updates the editable metadata of a media item: name, caption, favourite flag, folder and labels.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the resource"},{"schema":{"type":"string"},"name":"id","in":"path","required":true,"description":"ID of the media item"}],"responses":{"200":{"description":"Media updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaLibraryItem"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Forbidden - you did not upload this item and are not a workspace owner or admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"media":{"type":"object","properties":{"name":{"type":"string","description":"Display name, used by library search"},"caption":{"type":"string","description":"Caption, also searchable"},"favorite":{"type":"boolean"},"folder_id":{"type":"string","description":"Move the item to this folder"},"labels":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"}}}}}}}}}},"required":true,"description":"Media metadata"}}}}} ``` ```json { "media": { "name": "Q4 launch hero", "caption": "Product shot, dark background" } } ``` {% hint style="info" %} Library search matches on `name` and `caption`. Uploads that arrive without a meaningful name are effectively unfindable, so setting one here is worth doing right after upload. {% endhint %} Only the item's uploader, the workspace owner, or a workspace admin may update an item. Anyone else receives **403**. ### Related Resources * [Accounts API](/docs/api-reference/accounts.md) — Manage connected social accounts * [Posts API](/docs/posting/create-posts.md) — Create and schedule posts * [Media Upload](/docs/posting/create-posts/media-handling.md) — Upload new media files --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://publer.com/docs/api-reference/media.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.