PublishQPublishQ

Delete media folder

POST
/media/folders/delete

Delete a folder with every file in it and in its subfolders, from the media library and from storage. This cannot be undone. Files a draft or scheduled post still uses are kept, so that post can still publish. Call Preview media folder deletion first and send its fileCount as expectedFileCount: if the folder changed since, nothing is deleted and the response is 409 with the new counts.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://publishq.com/api/v1/media/folders/delete" \  -H "Content-Type: application/json" \  -d '{    "path": "Channel A",    "expectedFileCount": 12  }'
{
  "deletedIds": [
    "f6370ca1-1f47-4f68-be72-c1206913b326"
  ],
  "keptCount": 0
}
{
  "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": "Forbidden",
    "status": 403,
    "code": "insufficient_scope",
    "message": "Missing required scope: media:write",
    "instance": "/api/v1/media/folders/delete"
  }
}
{
  "error": {
    "title": "Not Found",
    "status": 404,
    "code": "media_folder_not_found",
    "message": "There is no folder \"Channel A/Shorts\"",
    "instance": "/api/v1/media"
  }
}
{
  "error": {
    "title": "Conflict",
    "status": 409,
    "code": "media_folder_changed",
    "message": "This folder now holds 13 files, not 12. Check the new count before deleting.",
    "instance": "/api/v1/media",
    "details": {
      "fileCount": 13,
      "subfolderCount": 2,
      "keptCount": 1
    }
  }
}
{
  "error": {
    "title": "Too Many Requests",
    "status": 429,
    "code": "rate_limit_exceeded",
    "message": "Too Many Requests",
    "instance": "/api/v1/media/folders/delete",
    "details": {
      "retryAfter": 60
    }
  }
}

Preview media folder deletion GET

Count what deleting a folder would remove: its files and subfolders at every level, and the files that are kept because a draft or scheduled post still uses them. Show these numbers to the user, then send `fileCount` to Delete media folder. Answers 404 when no folder has that path.

Complete media upload POST

Optional. Adds a file uploaded through Create media upload to your media library now and returns it. Without this call the file is added the first time you use its id in a post, and an upload nobody completes or uses within 1 day expires. Send `folderPath` to put the file in a folder; calling it again with another `folderPath` moves the file.