Update the Workflow name or replace its rules. Replacing rules requires the current revision. A changed definition creates a new revision; unchanged rules and name-only edits preserve it. Existing Assets and Uploads keep their selected revision until a ready Asset explicitly updates to the latest revision. Archived Workflows cannot be updated.
PATCH
/workflows/{workflowId}
Authorization
Authorization
header
string
required
Enter the project access token with the Bearer prefix, e.g. "Bearer project_access_token"
Path Parameters
workflowId
string
required
ID of the Workflow.
Bodyapplication/json
expected_revision
integer
ExpectedRevision specifies the current Workflow revision when replacing rules. The update returns a conflict if it no longer matches.
Required when rules is provided. Must be at least 1.
Required range: x >= 1
name
string
Name specifies the Workflow name.
Use 1 to 128 characters.
rules
object[]
Rules specifies the event subscriptions and actions in this definition.
Provide exactly one asset.ready rule and up to 15 connected rules, with at most 32 actions and 65536 encoded bytes across all rules. Array order affects display only.
Replaces the complete definition and requires schema_version and expected_revision. Existing Assets and Uploads keep their pinned revision.
actions
object[]
required
Actions specifies the work to start when the rule matches. Actions can run concurrently; array order does not define execution order.
Provide 1 to 32 actions per rule, with at most 32 across the definition.
Creates or reuses one static rendition for the Asset.
id
string
required
Id specifies a stable action key, unique within its rule.
Use 1 to 64 characters, starting with a letter and containing only letters, digits, or underscores.
Pattern:
^[A-Za-z][A-Za-z0-9_]*$
params
object
required
Params specifies the static rendition resolution.
resolution
string
required
Resolution specifies the H.264 MP4 output resolution. highest selects the largest supported output without upscaling.
Hobby supports up to 1080p; other plans support up to 2160p. Streaming resolution limits do not apply.
Available options:
highest240p360p480p540p720p1080p1440p2160p
type
"create_static_rendition"
string
required
Type specifies the action to perform. Must be create_static_rendition.
Generates or reuses original captions and their transcript from the Asset's speech.
id
string
required
Id specifies a stable action key, unique within its rule.
Use 1 to 64 characters, starting with a letter and containing only letters, digits, or underscores.
Pattern:
^[A-Za-z][A-Za-z0-9_]*$
params
object
required
Params specifies caption generation settings. Pass an empty object.
type
"create_caption"
string
required
Type specifies the action to perform. Must be create_caption.
transcript_id
object
TranscriptId binds caption publication to the transcript in the triggering event. Use it only when connected to create_transcript. When omitted, creates or reuses the Asset’s original transcript.
from
string
required
From specifies where to read the input output ID. Use event.output.id to consume the output in the triggering asset.output.ready event.
Available options:
event.output.id
Translates or reuses an original caption in one target language. Requires an asset.output.ready rule connected to an original caption creation action.
caption_id
object
required
CaptionId specifies the binding to the original caption in the triggering event.
from
string
required
From specifies where to read the input output ID. Use event.output.id to consume the output in the triggering asset.output.ready event.
Available options:
event.output.id
id
string
required
Id specifies a stable action key, unique within its rule.
Use 1 to 64 characters, starting with a letter and containing only letters, digits, or underscores.
Pattern:
^[A-Za-z][A-Za-z0-9_]*$
params
object
required
Params specifies the target language.
language_code
string
required
LanguageCode specifies the target language for the translated subtitle track, such as en or fr. The same code appears in the caption and HLS manifest.
Available options:
enfresdeitptnljakozharhirutrplsv
type
"translate_caption"
string
required
Type specifies the action to perform. Must be translate_caption.
Creates an independent thumbnail request after asset.ready. Replaying this action uses its accepted request; separate actions create separate requests.
id
string
required
Id specifies a stable action key, unique within its rule.
Pattern:
^[A-Za-z][A-Za-z0-9_]*$
params
object
required
Params specifies sampling and image settings. Outputs use the Asset folder and Storage.
timestamps
number[]
required
Timestamps specifies 1 to 100 Source-relative target times in seconds. Times outside the selected range are skipped when the action runs. If none remain, the action is skipped without a charge. Repeated targets produce separate outputs.
count
integer
Count specifies 1 to 100 thumbnails at the middle of equal sections of the selected range.
Required range: 1 <= x <= 100
format
default: "jpeg"
string
Format specifies the image encoding.
Available options:
jpegwebp
metadata
object
Metadata attaches string values to this request. The serialized object may contain at most 2048 bytes.
output
default: "images"
string
Output specifies individual images or automatically arranged sprite sheets.
Available options:
imagessprites
range
object
Range limits sampling to part of the Source. Defaults to the whole Source duration.
end
number
End specifies the exclusive upper bound in seconds. Defaults to the Source duration.
start
number
Start specifies the inclusive lower bound in seconds. Defaults to zero.
Required range: x >= 0
size
default: 320
integer
Size specifies the maximum image or tile edge in pixels, from 64 to 1920. Defaults to 320. Odd sizes are supported. Preserves display aspect ratio without cropping or upscaling.
Required range: 64 <= x <= 1920
count
integer
required
Count specifies 1 to 100 thumbnails at the middle of equal sections of the selected range.
Required range: 1 <= x <= 100
format
default: "jpeg"
string
Format specifies the image encoding.
Available options:
jpegwebp
metadata
object
Metadata attaches string values to this request. The serialized object may contain at most 2048 bytes.
output
default: "images"
string
Output specifies individual images or automatically arranged sprite sheets.
Available options:
imagessprites
range
object
Range limits sampling to part of the Source. Defaults to the whole Source duration.
end
number
End specifies the exclusive upper bound in seconds. Defaults to the Source duration.
start
number
Start specifies the inclusive lower bound in seconds. Defaults to zero.
Required range: x >= 0
size
default: 320
integer
Size specifies the maximum image or tile edge in pixels, from 64 to 1920. Defaults to 320. Odd sizes are supported. Preserves display aspect ratio without cropping or upscaling.
Required range: 64 <= x <= 1920
timestamps
number[]
Timestamps specifies 1 to 100 Source-relative target times in seconds. Times outside the selected range are skipped when the action runs. If none remain, the action is skipped without a charge. Repeated targets produce separate outputs.
type
"create_thumbnails"
string
required
Type specifies the action to perform. Must be create_thumbnails.
Creates or reuses the original-language transcript. Can run alongside caption generation in the same asset.ready rule.
id
string
required
Id specifies a stable action key, unique within its rule.
Use 1 to 64 characters, starting with a letter and containing only letters, digits, or underscores.
Pattern:
^[A-Za-z][A-Za-z0-9_]*$
params
object
required
Params specifies transcript settings. Pass an empty object.
type
"create_transcript"
string
required
Type specifies the action to perform. Must be create_transcript.
event
string
required
Event specifies when this rule starts. Use asset.ready for the single starting rule. Output ready events require an origin caption or static rendition action in this Workflow.
Available options:
asset.readyasset.output.ready
id
string
required
Id specifies a stable rule key, unique within this Workflow definition.
Use 1 to 64 characters, starting with a letter and containing only letters, digits, or underscores.
Pattern:
^[A-Za-z][A-Za-z0-9_]*$
origin
object
Origin specifies the action whose ready output starts this rule. Required for asset.output.ready; omit it for asset.ready. Translation steps must connect to a create_caption action.
References must point to a compatible action in this definition and must not form a cycle.
action_id
string
required
ActionId specifies the ID of the producing action within that rule.
Use 1 to 64 characters, starting with a letter and containing only letters, digits, or underscores.
Pattern:
^[A-Za-z][A-Za-z0-9_]*$
rule_id
string
required
RuleId specifies the ID of the rule containing the producing action.
Use 1 to 64 characters, starting with a letter and containing only letters, digits, or underscores.
Pattern:
^[A-Za-z][A-Za-z0-9_]*$
schema_version
integer
SchemaVersion specifies the Workflow definition format. The supported version is 1. Required when rules is provided.
Available options:
1
Responses
Update Workflow
application/json
error
object
required
code
400
integer
required
Code is the HTTP status code
Examples:
400
message
string
required
Message is a human-readable error description
Examples:
Invalid request parameters
type
"ValidationError"
string
required
Type indicates the error category
Available options:
ValidationError
status
"error"
string
required
Status indicates the response status "error"
Validation error
application/json
error
object
required
Error response details
code
401
integer
required
Code is the HTTP status code
Examples:
401
message
string
required
Message is a human-readable error description
Examples:
Authentication error: invalid token or subscription inactive
type
"AuthenticationError"
string
required
Type indicates the error category
Available options:
AuthenticationError
status
"error"
string
required
Status indicates the response status "error"
Authentication error
application/json
error
object
required
Error response details
code
403
integer
required
Code is the HTTP status code
Examples:
403
message
string
required
Message is a human-readable error description
Examples:
Unauthorized to perform this action
type
"ForbiddenError"
string
required
Type indicates the error category
Available options:
ForbiddenError
status
"error"
string
required
Status indicates the response status "error"
Forbidden error
application/json
error
object
required
Error response details
code
404
integer
required
Code is the HTTP status code
Examples:
404
message
string
required
Message is a human-readable error description
Examples:
Ressource not found
type
"NotFoundError"
string
required
Type indicates the error category
Available options:
NotFoundError
status
"error"
string
required
Status indicates the response status "error"
NotFound error
application/json
error
object
required
Error response details
code
409
integer
required
Code is the HTTP status code
Examples:
409
message
string
required
Message is a human-readable error description
Examples:
source_unavailable: the original video is no longer accessible
type
"ConflictError"
string
required
Type indicates the error category
Available options:
ConflictError
status
"error"
string
required
Status indicates the response status "error"
Conflict error
application/json
error
object
required
Error response details
code
429
integer
required
Code is the HTTP status code
Examples:
429
message
string
required
Message is a human-readable error description
Examples:
Rate limit exceeded
type
"TooManyRequestsError"
string
required
Type indicates the error category
Available options:
TooManyRequestsError
status
"error"
string
required
Status indicates the response status "error"
TooManyRequests error
application/json
error
object
required
Error response details
code
503
integer
required
Code is the HTTP status code
Examples:
503
message
string
required
Message is a human-readable error description
Examples:
The service is temporarily unavailable; retry the request