API & MCP reference / REST API

Media

Uploads are three steps: reserve a signed URL, PUT the raw bytes to it, then confirm. If your file is already reachable at a public URL, skip all of this and pass media_urls when creating the post — we fetch it server-side.

POST/v1/media/create-upload-url

Reserve a signed upload URL.

Parameter	Type	Description
`mime_type`req	string	e.g. video/mp4, image/jpeg.
`size_bytes`req	integer	Exact byte length. Must match the upload.
`name`	string	Original filename, used for the library listing.

Request body

{ "mime_type": "video/mp4", "size_bytes": 1048576, "name": "launch.mp4" }

Response

201 → {
  "media_id": "mid_abc123",
  "upload_url": "https://…signed…",
  "complete_url": "https://…"
}

Steps 2 and 3

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: video/mp4" \
  --data-binary @launch.mp4

curl -X POST "$COMPLETE_URL" \
  -H "Authorization: Bearer pt_live_…"

GET/v1/media

List uploaded media in the workspace.

DELETE/v1/media/{media_id}

Delete a media item. Media still referenced by a scheduled post is kept.