Media Uploads
PostBoost supports three upload methods. Choose based on file size and source:
| Method | Best for | API calls |
|---|---|---|
| Simple upload | Files under 10 MB | 1 |
| Chunked upload | Files over 10 MB | 3+ |
| Remote URL | Files hosted on the web | 2+ |
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
- Authentication — manage API tokens
- Webhooks — get notified when posts publish
- API Reference — full media endpoint reference