Media

Upload files once to Onepostly, then reuse the returned CDN url in POST /v1/posts as mediaUrls[]. Platforms that need media will use that URL when publishing (X also requires media.write).

Supported types

Content-Type	Extensions	Notes
`image/jpeg`	`.jpg`, `.jpeg`
`image/png`	`.png`
`image/gif`	`.gif`	Animated OK; X treats as single media
`image/webp`	`.webp`
`video/mp4`	`.mp4`
`video/quicktime`	`.mov`
`video/webm`	`.webm`

Limit	Value
Max file size	100 MB (Onepostly upload)
Field name	`file` (multipart)

Platforms may enforce stricter limits at publish (see X → Posts, YouTube → Posts for the 256 MB YouTube publish cap).

Upload

curl -X POST https://api.onepostly.com/v1/media \
  -H "x-api-key: op_YOUR_KEY" \
  -F "file=@./photo.jpg"

Response 201:

{
  "media": {
    "id": "MEDIA_ID",
    "url": "https://cdn.onepostly.com/media/WORKSPACE_ID/MEDIA_ID.jpg",
    "contentType": "image/jpeg",
    "byteSize": 245760,
    "originalFilename": "photo.jpg",
    "createdAt": "2026-07-15T12:00:00.000Z"
  }
}

Attach to a post

{
  "text": "Ship day",
  "mediaUrls": ["https://cdn.onepostly.com/media/WORKSPACE_ID/MEDIA_ID.jpg"],
  "mediaKind": "image",
  "destinations": [{ "connectionId": "YOUR_CONNECTION_ID" }]
}

mediaUrls accepts one or more CDN URLs (max 10 on create; platforms may allow fewer)
mediaKind: text | image | multi-image | video | stories (see platform docs for what each supports)

List

curl "https://api.onepostly.com/v1/media?limit=20&offset=0" \
  -H "x-api-key: op_YOUR_KEY"

{
  "media": [ { "id": "…", "url": "…", "contentType": "…", "byteSize": 0, "originalFilename": null, "createdAt": "…" } ],
  "total": 42
}

Query	Default	Max
`limit`	`20`	`100`
`offset`	`0`	—

Delete

curl -X DELETE https://api.onepostly.com/v1/media/MEDIA_ID \
  -H "x-api-key: op_YOUR_KEY"

Returns 204 on success. Removes the CDN object and the workspace’s media record. Already-published posts that referenced the URL are not rewritten.

Errors

Code	HTTP	Meaning
`VALIDATION_ERROR`	400	Missing `file` or not multipart
`UNSUPPORTED_MEDIA_TYPE`	400	Type not in the allow-list above
`MEDIA_TOO_LARGE`	400	Over 100 MB
`NOT_CONFIGURED`	503	Media storage not configured
`NOT_FOUND`	404	Unknown `MEDIA_ID` on delete
`FORBIDDEN`	403	Read-only API key on upload/delete
`UNAUTHORIZED`	401	Missing/invalid API key

Flow

POST /v1/media → CDN url
POST /v1/posts with mediaUrls: [url] (+ mediaKind)
Destination publishes using that URL