Skip to main content

Media Uploads

PostBoost supports three upload methods. Choose based on file size and source:

MethodBest forAPI calls
Simple uploadFiles under 10 MB1
Chunked uploadFiles over 10 MB3+
Remote URLFiles hosted on the web2+

Simple upload​

Send the file directly as a multipart form upload:

curl -X POST https://postboost.co/app/api/{workspaceUuid}/media \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "file=@/path/to/image.jpg"

The response is a Media object containing the uuid to use when attaching media to a post.

PDF documents (LinkedIn)​

A PDF (up to 100 MB, 300 pages) uploads the same way, through this endpoint or the base64 one, and publishes as a LinkedIn document post: a swipeable carousel of its pages, titled after the file name. A post that attaches a PDF must have it as the only media item of that content item and may only go to LinkedIn profiles and pages; any other combination is refused with 422. The chunked upload accepts PDFs too (use it for anything over 10 MB); the remote-URL import accepts a PDF under 10 MB.

Base64 (JSON) upload​

Tools that cannot send multipart form data (agents, MCP clients) can send the file as base64 in JSON. The same type and size checks apply; the decoded file may be at most 20 MB.

curl -X POST https://postboost.co/app/api/{workspaceUuid}/media/base64 \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"filename": "cover.png", "content": "iVBORw0KGgo...", "alt_text": "Product shot"}'

Chunked upload​

Use for large files (video, high-res images). The server tells you the chunk size — you split the file and upload each piece in order.

Step 1 — Initiate​

curl -X POST https://postboost.co/app/api/{workspaceUuid}/media/chunked/initiate \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"filename": "video.mp4",
"mime_type": "video/mp4",
"total_size": 52428800
}'
{
"upload_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"chunk_size": 5242880,
"total_chunks": 10
}

Save upload_uuid, chunk_size, and total_chunks — you'll need all three.

Step 2 — Upload each chunk​

Split your file into chunk_size-byte pieces and upload them in order. chunk_index is zero-based:

curl -X POST https://postboost.co/app/api/{workspaceUuid}/media/chunked/{uploadUuid}/upload \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-F "chunk=@chunk_0.bin" \
-F "chunk_index=0"

Repeat for each chunk (chunk_index=1, chunk_index=2, …, up to total_chunks - 1). Each successful chunk returns 201.

Step 3 — Complete​

Once all chunks are uploaded, signal completion:

curl -X POST https://postboost.co/app/api/{workspaceUuid}/media/chunked/{uploadUuid}/complete \
-H "Authorization: Bearer YOUR_API_TOKEN"

Returns the final Media object. Use its uuid when attaching the file to a post.

Aborting​

If an error occurs mid-upload, clean up the session to free server storage:

curl -X DELETE https://postboost.co/app/api/{workspaceUuid}/media/chunked/{uploadUuid} \
-H "Authorization: Bearer YOUR_API_TOKEN"

Remote URL upload​

Import media directly from a public URL — no local download required.

Step 1 — Initiate​

curl -X POST https://postboost.co/app/api/{workspaceUuid}/media/remote/initiate \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"url": "https://example.com/photo.jpg"}'

The response is 200. A file under 10 MB is downloaded during the request, so no polling is needed: status is completed and media holds the new item (or status is failed with an error).

{
"status": "completed",
"media": {
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "photo.jpg"
}
}

A larger file downloads in the background and you receive a download ID instead:

{ "download_id": "8f14e45f-ceea-467f-a8c4-1c2d3e4f5a6b", "status": "pending" }

Step 2 — Poll for status​

curl https://postboost.co/app/api/{workspaceUuid}/media/remote/{downloadId}/status \
-H "Authorization: Bearer YOUR_API_TOKEN"

Poll every 2–3 seconds. Possible values for status: pending, downloading, processing, completed, failed. progress stays 0 until the file is stored, so decide on status.

{
"status": "completed",
"progress": 100,
"media": {
"uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "photo.jpg"
}
}

When status is completed, use media.uuid when attaching to a post. If status is failed, the response has an error; retry the initiate call. The final result is returned once: a later poll for the same ID returns 404, as does an ID older than one hour.

Next steps​