Upload 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 PublishQ API key sent as Authorization: Bearer pq_live_....
In: header
Query Parameters
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.
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
}
}
}Get media GET
Return one media file by ID, including its URL, source, and usage count.
Create media upload POST
Upload a file of up to 4 GB (500 MB on the Free plan) straight to storage: 1. Call this endpoint with `filename`, `contentType` and `fileSize`. You get back an `id` and an `uploadUrl`. 2. `PUT` the file to `uploadUrl` with the same `Content-Type` header. Storage answers `200`, or `403` if the file is not exactly `fileSize` bytes. 3. Optional: call Complete media upload to add the file to your media library now. 4. Put the `id` in `mediaIds` when you create or update a post.