Skip to main content
POST
import media

Authorizations

Authorization
string
header
required

An API key (es_live_…) from Settings, under API keys, or an OAuth access token.

Headers

Idempotency-Key
string

Retry a paid dispatch safely: the same key returns the job already dispatched instead of charging again.

x-workspace-id
string

The workspace this one call acts in, when it is not the key's own.

Body

application/json
mode
enum<string>
required

url (hosted media), file (bytes in the call), link (the user has the file), presign (the caller PUTs up to 5 GB; larger by link), confirm (after the presign PUT), local (paths on the computer running the desktop app).

Available options:
url,
file,
link,
presign,
confirm,
local
items
object[]

mode url: the media to save.

Required array length: 1 - 20 elements
file
object

mode file: the bytes, up to 6MB decoded.

files
object[]

mode presign: one entry per file. The URL is signed for exactly the size declared; a PUT of any other length is refused.

Required array length: 1 - 20 elements
upload_ids
string[]

mode confirm: the upload_id values presign returned, up to 20 a call.

Required array length: 1 - 20 elements
provenance
object[]

mode confirm: per-upload knowledge, matched by upload_id.

from
string

mode link: your name, as the user knows you ("Claude"). The page tells them who to go back to once the files are up.

Maximum string length: 40
timeline
string

mode link: timeline id; each file is also added to it as a clip, after the last one.

folder
string

Folder path or id to land in. Without one, files go to the workspace's Uploads folder.

context
string

Optional: one sentence shown to the user beside this action.

Maximum string length: 600

Response

Done, or a job started for work that runs longer (follow it with get_jobs).

ok
any
required
data
object
required
meta
object
required
media
object[]