> 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/folders.md). # Folders ### Requirements * **Authentication**: Bearer API token * **Scope**: `posts` * **Headers**: * `Authorization: Bearer-API YOUR_API_KEY` * `Publer-Workspace-Id: YOUR_WORKSPACE_ID` ### Endpoint ### List Media Folders Retrieve the folders in a workspace's media library. ```http GET /api/v1/media/folders ``` **Query Parameters**
ParameterTypeRequiredDescription
parent_folder_idstringNoReturn the direct children of this folder. Omit to return root-level folders.
## List Media Folders > Retrieves media library folders for a workspace. Returns root-level folders by default, or the direct children of a folder when parent\_folder\_id is supplied. ```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":{"MediaFolderList":{"type":"object","properties":{"folders":{"type":"array","description":"Folders at the requested level, newest first","items":{"$ref":"#/components/schemas/MediaFolder"}},"previous_folders":{"type":"array","description":"Breadcrumb trail from the root down to and including the requested folder. Empty when listing root-level folders.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}},"MediaFolder":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"parent_folder_id":{"type":"string","description":"null for a root-level folder"},"created_at":{"type":"string"}}},"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"}}}},"422ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/media/folders":{"get":{"summary":"List Media Folders","tags":["Media"],"description":"Retrieves media library folders for a workspace. Returns root-level folders by default, or the direct children of a folder when parent_folder_id is supplied.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the resource"},{"schema":{"type":"string"},"name":"parent_folder_id","in":"query","required":false,"description":"Return the direct children of this folder. Omit to return root-level folders."}],"responses":{"200":{"description":"Successful operation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFolderList"}}}},"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"}}}},"422":{"description":"Unprocessable Entity - no folder with that ID in this workspace","content":{"application/json":{"schema":{"$ref":"#/components/schemas/422ErrorResponse"}}}}}}}}} ``` ### Create Media Folder Creates a folder in the media library. ```http POST /api/v1/media/folders ``` ## Create Media Folder > Creates a folder in the media library. ```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":{"MediaFolder":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"parent_folder_id":{"type":"string","description":"null for a root-level folder"},"created_at":{"type":"string"}}},"401ErrorResponseWithWorkspace":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"422ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/media/folders":{"post":{"summary":"Create Media Folder","tags":["Media"],"description":"Creates a folder in the media library.","parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","required":true,"description":"ID of the workspace containing the resource"}],"responses":{"201":{"description":"Folder created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFolder"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"422":{"description":"Unprocessable Entity - invalid name or parent","content":{"application/json":{"schema":{"$ref":"#/components/schemas/422ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Folder name, 1 to 150 characters"},"parent_folder_id":{"type":"string","description":"Create inside this folder. Omit for a root-level folder."}}}}},"required":true,"description":"Folder attributes"}}}}} ``` {% hint style="info" %} Folder names are unique within a parent. Creating `Campaigns` when one already exists produces `Campaigns (1)` rather than an error, so the name you send is not always the name you get — read it back from the response. {% endhint %} *** ### Update Media Folder Rename a folder or moves it under a different parent. ```http PUT /api/v1/media/folders/{id} ``` ## Update Media Folder > Renames a folder or moves it under a different parent. ```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":{"MediaFolder":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"parent_folder_id":{"type":"string","description":"null for a root-level folder"},"created_at":{"type":"string"}}},"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"}}}},"422ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/media/folders/{id}":{"put":{"summary":"Update Media Folder","tags":["Media"],"description":"Renames a folder or moves it under a different parent.","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 folder"}],"responses":{"200":{"description":"Folder updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MediaFolder"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Forbidden - invalid parent folder, or you are not the folder creator, owner or an admin","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}},"422":{"description":"Unprocessable Entity - the move would create a circular reference","content":{"application/json":{"schema":{"$ref":"#/components/schemas/422ErrorResponse"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"parent_folder_id":{"type":"string","description":"New parent folder"}}}}},"required":true,"description":"Folder attributes"}}}}} ``` A folder cannot be moved into itself or into one of its own descendants; either returns **422**. *** ### Delete Media Folder Deletes an empty folder. ```http DELETE /api/v1/media/folders/{id} ``` ## Delete Media Folder > Deletes an empty folder. ```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":{"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/folders/{id}":{"delete":{"summary":"Delete Media Folder","tags":["Media"],"description":"Deletes an empty folder.","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 folder"}],"responses":{"204":{"description":"Folder deleted"},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}},"403":{"description":"Forbidden - the folder still contains media or sub-folders, or you lack permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}} ``` Returns **204 No Content** on success. A folder that still contains library media or sub-folders returns **403** — empty it first, using the move endpoint below. *** ### Move Media Between Folders Moves a set of media items into a folder, or to the library root. ```http PUT /api/v1/media/folders/move_to_folder ``` ## Move Media Between Folders > Moves a set of media items into a folder, or to the library root. ```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":{"MoveMediaResponse":{"type":"object","properties":{"updated_ids":{"type":"array","description":"IDs actually moved. Items you lack permission on are skipped silently.","items":{"type":"string"}},"folder_id":{"type":"string","description":"Destination folder, or null for the library root"}}},"401ErrorResponseWithWorkspace":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/media/folders/move_to_folder":{"put":{"summary":"Move Media Between Folders","tags":["Media"],"description":"Moves a set of media items into a folder, or to the library root.","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":"query","required":false,"description":"Destination folder ID. Pass a non-ID value (or omit) to move items to the library root."},{"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":true,"name":"media_ids","in":"query","required":true,"description":"IDs of the media items to move"}],"responses":{"200":{"description":"Move completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoveMediaResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponseWithWorkspace"}}}}}}}}} ``` ```json { "updated_ids": ["665f...", "665e..."], "folder_id": "664a..." } ``` {% hint style="warning" %} Items you lack permission on are **skipped silently** rather than causing an error. Always compare `updated_ids` against the IDs you sent to confirm every item moved. {% endhint %} Omit `id` to move items back to the library root. #### Notes * Folders are returned newest first. * `previous_folders` is the breadcrumb trail from the root down to and including the requested folder, so you can render or walk the current location. It is empty when listing root-level folders. * Listing is scoped to one level at a time. To walk a tree, call the endpoint again with the `id` of each folder you want to descend into. * Folder names are unique per level. Creating a folder whose name already exists in the same parent appends a counter, for example `Campaigns (1)`. * A `parent_folder_id` that does not exist in this workspace returns **422 Unprocessable Entity**. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://publer.com/docs/api-reference/media/folders.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.