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.

GET /api/v1/media/folders

Query Parameters

Parameter	Type	Required	Description
parent_folder_id	string	No	Return the direct children of this folder. Omit to return root-level folders.

List Media Folders

get

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.

Authorizations

AuthorizationstringRequired

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

Query parameters

parent_folder_idstringOptional

Return the direct children of this folder. Omit to return root-level folders.

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace containing the resource

Responses

200

Successful operation

application/json

401

Unauthorized

application/json

403

Permission denied or missing required scope

application/json

422

Unprocessable Entity - no folder with that ID in this workspace

application/json

get/media/folders

GET /api/v1/media/folders HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "folders": [
    {
      "id": "text",
      "name": "text",
      "parent_folder_id": "text",
      "created_at": "text"
    }
  ],
  "previous_folders": [
    {
      "id": "text",
      "name": "text"
    }
  ]
}

Create Media Folder

Creates a folder in the media library.

POST /api/v1/media/folders

Create Media Folder

post

Creates a folder in the media library.

Authorizations

AuthorizationstringRequired

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

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace containing the resource

Body

namestringRequired

Folder name, 1 to 150 characters

parent_folder_idstringOptional

Create inside this folder. Omit for a root-level folder.

Responses

201

Folder created

application/json

idstringOptional

namestringOptional

parent_folder_idstringOptional

null for a root-level folder

created_atstringOptional

401

Unauthorized

application/json

422

Unprocessable Entity - invalid name or parent

application/json

post/media/folders

POST /api/v1/media/folders HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "name": "text",
  "parent_folder_id": "text"
}

{
  "id": "text",
  "name": "text",
  "parent_folder_id": "text",
  "created_at": "text"
}

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.

---

Update Media Folder

Rename a folder or moves it under a different parent.

PUT /api/v1/media/folders/{id}

Update Media Folder

put

Renames a folder or moves it under a different parent.

Authorizations

AuthorizationstringRequired

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

Path parameters

idstringRequired

ID of the folder

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace containing the resource

Body

namestringOptional

parent_folder_idstringOptional

New parent folder

Responses

200

Folder updated

application/json

idstringOptional

namestringOptional

parent_folder_idstringOptional

null for a root-level folder

created_atstringOptional

401

Unauthorized

application/json

403

Forbidden - invalid parent folder, or you are not the folder creator, owner or an admin

application/json

422

Unprocessable Entity - the move would create a circular reference

application/json

put/media/folders/{id}

PUT /api/v1/media/folders/{id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "name": "text",
  "parent_folder_id": "text"
}

{
  "id": "text",
  "name": "text",
  "parent_folder_id": "text",
  "created_at": "text"
}

A folder cannot be moved into itself or into one of its own descendants; either returns 422.

---

Delete Media Folder

Deletes an empty folder.

DELETE /api/v1/media/folders/{id}

Delete Media Folder

delete

Deletes an empty folder.

Authorizations

AuthorizationstringRequired

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

Path parameters

idstringRequired

ID of the folder

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace containing the resource

Responses

204

Folder deleted

No content

401

Unauthorized

application/json

403

Forbidden - the folder still contains media or sub-folders, or you lack permission

application/json

delete/media/folders/{id}

DELETE /api/v1/media/folders/{id} HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

No content

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.

PUT /api/v1/media/folders/move_to_folder

Move Media Between Folders

put

Moves a set of media items into a folder, or to the library root.

Authorizations

AuthorizationstringRequired

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

Query parameters

idstringOptional

Destination folder ID. Pass a non-ID value (or omit) to move items to the library root.

media_idsstring[]Required

IDs of the media items to move

Header parameters

Publer-Workspace-IdstringRequired

ID of the workspace containing the resource

Responses

200

Move completed

application/json

updated_idsstring[]Optional

IDs actually moved. Items you lack permission on are skipped silently.

folder_idstringOptional

Destination folder, or null for the library root

401

Unauthorized

application/json

put/media/folders/move_to_folder

PUT /api/v1/media/folders/move_to_folder?media_ids=text HTTP/1.1
Host: app.publer.com
Authorization: YOUR_API_KEY
Publer-Workspace-Id: text
Accept: */*

{
  "updated_ids": [
    "text"
  ],
  "folder_id": "text"
}

{ "updated_ids": ["665f...", "665e..."], "folder_id": "664a..." }

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.

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.