Submits a batch of up to 1000 create, update, delete, and move actions to be
processed asynchronously. Returns a background job status whose Show
endpoint reports aggregate progress and per-action results, including the
hashed IDs of created records.
Supported resource types are media, folder, subfolder, channel,
channel_episode, captions, and the ten customization_* concerns. A
folder is a top-level folder (previously called a project); a subfolder
is nested inside one and requires folder_id and name when created. A
captions action operates on one caption track -- one media in one
language.
Because caption actions carry SRT contents inline, they are the resource
type most likely to reach the request body limit before the action cap.
Purchasing captions is not available here -- it has its own endpoint.
A move action targets one media and accepts a destination folder_id and
optional subfolder_id. Bulk moves can use different destinations and are
not subject to the Move Media endpoint's 100-item limit or separate throttle.
Player customizations are addressed one concern at a time
(customization_appearance, customization_playback, and so on), matching
the Update Customizations endpoints; each accepts update only, takes the
media's hashed ID as its id, and takes the same payload as its
corresponding endpoint. There is no batch equivalent of the broad customize
endpoint, so a batch always states which slice of the player it is changing.
A media update payload can also carry a custom_metadata object mapping
field keys to the values to set (null clears a field; omitted fields are
left untouched). Values are validated against each field's type exactly as
the Set Custom Metadata Field Value endpoint validates them, and each write
is recorded with its actor and source. Requires the custom metadata feature
on the account; without it actions carrying custom_metadata fail
individually.
Deleting a folder or subfolder also soft-deletes its media. An account owner
or manager can restore that media from the trash until it purges. To keep the
media when deleting a subfolder, use the Delete Subfolder endpoint; it moves
the media to the folder's root level instead.
Each action in the batch is authorized and processed independently:
failures (including authorization failures) are reported per action and do
not prevent other actions from completing. Media creation is not supported
-- uploads and URL imports have their own endpoints.
Requires api token with one of the following permissions
Read, update & delete anything
Tokens with the "Act with a team member's permissions" permission
(all:delegate_to_contact_permissions scope) can also be used. Requests
made with such a token are authorized using the permissions of the
contact assigned to the token.
Expiring access tokens
with authorizations cannot use this endpoint: each action is authorized
later, in a background job, as the persisted contact that submitted it,
and a token's authorizations are not carried into that job. Such requests
are forbidden.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests⦠| |||