Move media

PUT https://api.json2video.com/v2/media/file

Moves a single file from one folder to another within the authenticated account. The file is copied server-side in S3, the database record is rewritten, and the source is deleted. Moves to temp/ mark the file as temporary (auto-deleted by lifecycle rules).

Request

Headers

Header	Required	Value
`x-api-key`	yes	API key issued from the dashboard. Requires role `render`, `editor`, `manager`, or `admin`.
`Content-Type`	yes	`application/json`

Body

{
    "name": "clip.mp4",
    "folder": "videos",
    "destination": "videos/raw"
}

Field	Type	Required	Description
`name`	string	yes	Filename.
`folder`	string	no	Source folder. Empty means root.
`destination`	string	yes	Destination folder. Empty string moves to root. The special folder `temp` flags the file as temporary.

Response

200 OK

{
    "success": true,
    "timestamp": "2026-05-12T10:49:52.924Z"
}

Errors

Status	Message	Cause
`400`	`name is required`	Missing `name`.
`400`	`destination is required`	Missing `destination`.
`403`	`Insufficient permissions`	API key role is below `render`.
`404`	`File not found`	Source path does not exist.
`409`	`A file with this name already exists in the destination folder`	Destination collision.

Examples

Move a file

curl --location --request PUT 'https://api.json2video.com/v2/media/file' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "clip.mp4",
    "folder": "videos",
    "destination": "videos/raw"
  }'

Move to root

curl --location --request PUT 'https://api.json2video.com/v2/media/file' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{"name": "clip.mp4", "folder": "videos", "destination": ""}'

Move media#

Request#

Headers#

Body#

Response#

200 OK#

Errors#

Examples#

Move a file#

Move to root#