PublishQPublishQ

Upload media

POST
/media

Upload a file smaller than 100 MB in a single request. It is the simplest way to upload: one call returns a media ID you can attach to posts. For bigger files, use Create media upload. Add folderPath to the query string to put the file in a folder.

Authorization

ApiKeyAuth
AuthorizationBearer <token>

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

In: header

Query Parameters

folderPath?string

A folder path. Folder names are separated by /, for example Channel A/Shorts. Each name is trimmed, at most 100 characters, and cannot contain /; folders nest at most 10 levels deep. Puts the uploaded file in this folder. Leave it out for the top level.

Request Body

multipart/form-data

TypeScript Definitions

Use the request body type in TypeScript.

file*string

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://publishq.com/api/v1/media" \  -F file="string"
{
  "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"
}
{
  "error": {
    "title": "Bad Request",
    "status": 400,
    "code": "validation_failed",
    "message": "Request validation failed",
    "instance": "/api/v1/media",
    "details": {
      "errors": [
        {
          "path": "mediaTypes.0",
          "message": "Invalid option: expected one of \"IMAGE\"|\"VIDEO\"",
          "code": "invalid_value"
        }
      ]
    }
  }
}

{
  "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"
  }
}
{
  "error": {
    "title": "Conflict",
    "status": 409,
    "code": "media_folder_exists",
    "message": "A folder named \"Channel A\" already exists. Folder names ignore capitals, so use \"Channel A\" or pick another name.",
    "instance": "/api/v1/media"
  }
}
{
  "error": {
    "title": "Payload Too Large",
    "status": 413,
    "code": "file_too_large",
    "message": "File size too large. Maximum size is 500MB.",
    "instance": "/api/v1/media"
  }
}
{
  "error": {
    "title": "Unsupported Media Type",
    "status": 415,
    "code": "unsupported_file_type",
    "message": "Unsupported file type: the file content is audio/mpeg, even though it is labelled video/mp4. Renaming a file does not change its format. Supported types: image/jpeg, image/png, image/gif, image/webp, video/mp4, video/webm, video/quicktime, video/x-msvideo.",
    "instance": "/api/v1/media"
  }
}
{
  "error": {
    "title": "Too Many Requests",
    "status": 429,
    "code": "rate_limit_exceeded",
    "message": "Too Many Requests",
    "instance": "/api/v1/media",
    "details": {
      "retryAfter": 60
    }
  }
}