> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vturb.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update a video
## Merge-patch by feature
The request body is grouped by player feature — **controls**, **playback**,
**turbo**, **smart\_autoplay**, **pixels**, and more. It is a merge-patch: send
only the groups you want to change, and within a group only the keys you touch;
everything else keeps its stored value. Each group is collapsed below — expand
the ones you need.
New here? [How merge-patch works](/guides/merge-patch) covers the rules in a
page; every feature also has a focused guide under the **Guides** tab.
## OpenAPI
````yaml /openapi.yaml patch /v1/videos/{id}
openapi: 3.1.0
info:
title: VTurb API
version: v1
description: |
Public REST API for VTurb. Dev-first and agents-first: every documented
response is recorded from the API's real behavior.
contact:
name: VTurb API
url: https://vturb.com
servers:
- url: https://api.vturb.com
security:
- bearerAuth: []
paths:
/v1/videos/{id}:
patch:
tags:
- Videos
summary: Update a video
parameters:
- name: id
in: path
required: true
schema:
type: string
example: 652f2b1e8f1b2c3d4e5f6a7b
requestBody:
content:
application/json:
schema:
type: object
properties:
controls:
type: object
properties:
backward:
type: boolean
big_play:
type: boolean
forward:
type: boolean
fullscreen:
type: boolean
play_pause:
type: boolean
seekbar:
type: boolean
time:
type: boolean
volume:
type: boolean
fake_bar:
type: boolean
speed:
type: boolean
description: >
Player chrome toggles — each key shows or hides one
on-screen control. See the [Update
controls](/guides/patch-controls) guide for a focused
example.
x-mint:
playground:
expand: false
alternative_video:
type: object
properties:
enabled:
type: boolean
id:
type: string
description: >
Fallback video for viewers who can't play the main one. See
the [Update alternative
video](/guides/patch-alternative-video) guide.
x-mint:
playground:
expand: false
immersive_mode:
type: object
properties:
desktop:
type: boolean
disable_scrolling:
type: boolean
expand_on_play:
type: boolean
minimize_on_pause:
type: boolean
mobile:
type: boolean
enabled:
type: boolean
description: >
The fullscreen takeover — where it runs and when it expands.
See the [Update immersive
mode](/guides/patch-immersive-mode) guide.
x-mint:
playground:
expand: false
traffic_filter:
type: object
properties:
fallback_video_id:
type: string
token:
type: string
languages:
type: array
items:
type: string
countries:
type: array
items:
type: string
devices:
type: array
items:
type: string
query_params:
type: array
items:
type: string
block_proxy:
type: boolean
enabled:
type: boolean
description: >
Routes unwanted traffic — wrong country, wrong device,
proxies — to a fallback video. See the [Update traffic
filter](/guides/patch-traffic-filter) guide.
x-mint:
playground:
expand: false
playback:
type: object
properties:
disable_pause:
type: boolean
description: Stop the viewer pausing by clicking the video.
smart_pause:
type: boolean
description: Pause automatically when the viewer leaves the tab.
scroll_to_action_in:
type: integer
description: >-
Seconds into the video when the page scrolls to the call
to action (0 to the video duration).
minimum: 0
example: 30
action_after_finish:
type: object
properties:
type:
type: string
description: What the player does when the video ends.
enum:
- loop
start:
type: integer
description: >-
Second to restart from when the video ends (0 to the
video duration).
minimum: 0
example: 5
enabled:
type: boolean
description: Master switch for the playback feature.
description: >
Pause behavior, the scroll-to-action moment, and what
happens when the video ends. See the [Update
playback](/guides/patch-playback) guide.
x-mint:
playground:
expand: false
progress_bar:
type: object
properties:
height:
type: integer
use_base_color:
type: boolean
color:
type: string
enabled:
type: boolean
description: >
The decoy progress bar — height, color, and whether it
borrows the player's palette. See the [Update progress
bar](/guides/patch-progress-bar) guide.
x-mint:
playground:
expand: false
subtitle:
type: object
properties:
control:
type: boolean
style:
type: object
properties:
font_size:
type: string
color:
type: string
background_color:
type: string
text_align:
type: string
enum:
- center
- left
- right
show_by_default:
type: boolean
enabled:
type: boolean
track:
type: object
properties:
file_id:
type: string
description: >
Caption toggle and styling; the track file itself is
read-only. See the [Update subtitle](/guides/patch-subtitle)
guide.
x-mint:
playground:
expand: false
resume:
type: object
properties:
disable_pause:
type: boolean
styles:
type: object
properties:
background_color:
type: string
foreground_color:
type: string
texts:
type: object
properties:
play:
type: string
replay:
type: string
title:
type: string
enabled:
type: boolean
description: >
The keep-watching prompt returning viewers see — its copy
and colors. See the [Update resume](/guides/patch-resume)
guide.
x-mint:
playground:
expand: false
call_actions:
type: object
items:
type: object
properties:
base:
type:
- object
- 'null'
properties:
name:
type: string
type:
type: string
active:
type: boolean
window:
type:
- object
- 'null'
properties:
start:
type: integer
end:
type: integer
persist_on_video_end:
type: boolean
action:
type:
- object
- 'null'
properties:
as_html:
type:
- boolean
- 'null'
html:
type: string
id:
type:
- string
- 'null'
_destroy:
type:
- boolean
- 'null'
properties:
enabled:
type: boolean
items:
type: array
items:
type: object
properties:
base:
type:
- object
- 'null'
properties:
name:
type: string
type:
type: string
active:
type: boolean
window:
type:
- object
- 'null'
properties:
start:
type: integer
end:
type: integer
persist_on_video_end:
type: boolean
action:
type:
- object
- 'null'
properties:
as_html:
type:
- boolean
- 'null'
html:
type: string
content:
type: string
url:
type: string
open_in_new_tab:
type: boolean
id:
type:
- string
- 'null'
_destroy:
type:
- boolean
- 'null'
design:
type: object
properties:
typography:
type: object
properties:
family:
type: string
letter_spacing:
type: integer
line_height:
type: number
format: float
size:
type: integer
weight:
type: integer
styles:
type: object
properties:
background_color:
type: string
background_hover_color:
type: string
text_color:
type: string
text_hover_color:
type: string
border_radius:
type: integer
shadow_enabled:
type: boolean
shadow:
type: object
properties:
blur:
type: integer
color:
type: string
horizontal:
type: integer
vertical:
type: integer
spread:
type: integer
padding:
type: object
properties:
binding:
type: boolean
values:
type: array
items:
type: integer
description: >
CTA collection — an item with an `id` patches that CTA,
without one creates it, with `_destroy: true` deletes it.
See the [Update call actions](/guides/patch-call-actions)
guide.
x-mint:
playground:
expand: false
smart_autoplay:
type: object
properties:
enabled:
type: boolean
variants:
type: array
items:
type: object
properties:
template_name:
type: string
description: >-
The template to render. `fullscreen` ignores
`template_position`.
enum:
- default
- discrete
- modern
- sightcare
- fullscreen
template_position:
type: string
description: The nine-area grid slot to anchor the template on.
enum:
- top-left
- top-center
- top-right
- middle-left
- middle-center
- middle-right
- bottom-left
- bottom-center
- bottom-right
description: >
Muted-autoplay overlay — pick a template and a grid
position. See the [Update smart
autoplay](/guides/patch-smart-autoplay) guide.
x-mint:
playground:
expand: false
pixels:
type: object
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
base:
type:
- object
- 'null'
properties:
name:
type: string
type:
type: string
enum:
- facebook
- google
- custom
tag:
type:
- object
- 'null'
properties:
html:
type: string
dispatch:
type:
- object
- 'null'
properties:
active:
type: boolean
threshold:
type: integer
mode:
type: string
enum:
- percent
- time
_destroy:
type:
- boolean
- 'null'
enabled:
type: boolean
description: >
Tracking pixels and when in playback they fire — same
id/`_destroy` collection semantics as CTAs. See the [Update
pixels](/guides/patch-pixels) guide.
x-mint:
playground:
expand: false
turbo:
type: object
properties:
enabled:
type: boolean
speed:
type: number
format: float
description: >
Accelerated playback — the toggle and its rate; experiment
leaves are read-only. See the [Update
turbo](/guides/patch-turbo) guide.
x-mint:
playground:
expand: false
headline:
type: object
properties:
variants:
type: array
items:
type: object
properties:
id:
type:
- string
- 'null'
base:
type:
- object
- 'null'
properties:
name:
type:
- string
- 'null'
number:
type:
- integer
- 'null'
content:
type:
- object
- 'null'
properties:
kind:
type: string
html:
type: string
_destroy:
type:
- boolean
- 'null'
description: >
The headline variants drawn above the player — same
id/`_destroy` collection semantics as CTAs. Configure at
least two, then start the A/B test from the Experiments
endpoint.
x-mint:
playground:
expand: false
name:
type: string
description:
type: string
folder_id:
type: string
mini_hooks:
type: object
properties:
elements:
type: array
items:
type: object
properties:
id:
type: string
content:
type: object
properties:
src_file_id:
type: string
thumbsniper:
type: object
properties:
images:
type: object
properties:
start_file_id:
type: string
pause_file_id:
type: string
finish_file_id:
type: string
cards:
type: array
items:
type: object
properties:
base:
type: object
properties:
image_file_id:
type: string
example:
controls:
backward: true
big_play: false
forward: true
fullscreen: true
play_pause: true
seekbar: true
time: true
volume: true
fake_bar: false
speed: true
alternative_video:
enabled: true
id: 507f191e810c19729de860ea
immersive_mode:
desktop: true
disable_scrolling: false
expand_on_play: true
minimize_on_pause: false
mobile: true
enabled: true
traffic_filter:
fallback_video_id: 507f191e810c19729de860ea
token: gate_7f3c1a
languages:
- pt
- en
countries:
- BR
- US
devices:
- desktop
- mobile
query_params:
- utm_source
block_proxy: true
enabled: true
playback:
disable_pause: false
smart_pause: true
scroll_to_action_in: 30
action_after_finish:
type: loop
start: 5
enabled: true
progress_bar:
height: 12
use_base_color: false
color: '#0000FF'
enabled: true
subtitle:
control: true
style:
font_size: 16px
color: '#FFFFFF'
background_color: '#000000'
text_align: center
show_by_default: true
enabled: true
track:
file_id: 0190a0b0-2222-7222-8222-222222222222
resume:
disable_pause: false
styles:
background_color: '#1890FF'
foreground_color: '#FFFFFF'
texts:
play: Keep watching
replay: Replay
title: You already started
enabled: true
call_actions:
enabled: true
items:
- base:
type: outside_video
active: true
window:
start: 5
end: 30
action:
content: Buy now
url: https://example.com/checkout
open_in_new_tab: true
design:
typography:
family: Inter
letter_spacing: 0
line_height: 1.2
size: 16
weight: 600
styles:
background_color: '#1890FF'
background_hover_color: '#096DD9'
text_color: '#FFFFFF'
text_hover_color: '#F0F0F0'
border_radius: 8
shadow_enabled: true
shadow:
blur: 12
color: '#00000040'
horizontal: 0
vertical: 4
spread: 2
padding:
binding: true
values:
- 12
- 24
- 12
- 24
smart_autoplay:
enabled: true
variants:
- template_name: discrete
template_position: top-left
pixels:
items:
- base:
name: Fresh
type: custom
tag:
html: tag
dispatch:
active: true
threshold: 50
mode: percent
enabled: true
turbo:
enabled: true
speed: 1.5
headline:
variants:
- id: 652f2b1e8f1b2c3d4e5f0201
base:
name: Renamed
- base:
number: 3
content:
kind: html
html: New
- id: 652f2b1e8f1b2c3d4e5f0202
_destroy: true
name: Renamed
description: New copy
folder_id: 652f2b1e8f1b2c3d4e5f00aa
mini_hooks:
elements:
- id: 652f2b1e8f1b2c3d4e5f0016
content:
src_file_id: 0190a0b0-3333-7333-8333-333333333333
thumbsniper:
images:
start_file_id: 0190a0b0-1111-7111-8111-111111111111
pause_file_id: 0190a0b0-1111-7111-8111-111111111111
finish_file_id: 0190a0b0-1111-7111-8111-111111111111
cards:
- base:
image_file_id: 0190a0b0-1111-7111-8111-111111111111
responses:
'200':
description: >-
Send `_file_id` with an uploaded file's id and the video
stores that file's public url.
content:
application/json:
schema:
type: object
properties:
id:
type: string
name:
type: string
description:
type:
- string
- 'null'
folder_id:
type:
- string
- 'null'
status:
type: string
controls:
type: object
properties:
backward:
type:
- boolean
- 'null'
big_play:
type:
- boolean
- 'null'
forward:
type:
- boolean
- 'null'
fullscreen:
type:
- boolean
- 'null'
play_pause:
type:
- boolean
- 'null'
seekbar:
type:
- boolean
- 'null'
time:
type:
- boolean
- 'null'
volume:
type:
- boolean
- 'null'
fake_bar:
type:
- boolean
- 'null'
speed:
type:
- boolean
- 'null'
required:
- backward
- big_play
- forward
- fullscreen
- play_pause
- seekbar
- time
- volume
- fake_bar
- speed
call_actions:
type: object
items:
type: object
properties:
base:
type: object
properties:
name:
type: string
type:
type: string
active:
type: boolean
required:
- name
- type
- active
window:
type: object
properties:
start:
type: integer
end:
type: integer
persist_on_video_end:
type: 'null'
show_to_returning_viewer:
type: 'null'
required:
- start
- end
- persist_on_video_end
- show_to_returning_viewer
action:
type: object
properties:
content:
type: 'null'
url:
type: 'null'
open_in_new_tab:
type: 'null'
html:
type: string
as_html:
type: boolean
required:
- content
- url
- open_in_new_tab
- html
- as_html
scroll:
type: object
properties:
scroll_enabled:
type: 'null'
scroll_type:
type: 'null'
scroll_offset:
type: 'null'
required:
- scroll_enabled
- scroll_type
- scroll_offset
image:
type: object
properties:
image_as_button:
type: 'null'
image_url:
type: 'null'
image_styles:
type: 'null'
required:
- image_as_button
- image_url
- image_styles
delay:
type: object
properties:
delay:
type: 'null'
delay_options:
type: 'null'
required:
- delay
- delay_options
design:
type: object
properties:
typography:
type: 'null'
styles:
type: 'null'
animation:
type: 'null'
rich_element:
type: 'null'
required:
- typography
- styles
- animation
- rich_element
id:
type: string
required:
- base
- window
- action
- scroll
- image
- delay
- design
- id
properties:
enabled:
type: boolean
items:
type: array
items:
type: object
properties:
base:
type: object
properties:
name:
type:
- string
- 'null'
type:
type: string
active:
type: boolean
required:
- name
- type
- active
window:
type: object
properties:
start:
type: integer
end:
type: integer
persist_on_video_end:
type: 'null'
show_to_returning_viewer:
type: 'null'
required:
- start
- end
- persist_on_video_end
- show_to_returning_viewer
action:
type: object
properties:
content:
type:
- string
- 'null'
url:
type:
- string
- 'null'
open_in_new_tab:
type:
- boolean
- 'null'
html:
type:
- string
- 'null'
as_html:
type:
- boolean
- 'null'
required:
- content
- url
- open_in_new_tab
- html
- as_html
scroll:
type: object
properties:
scroll_enabled:
type: 'null'
scroll_type:
type: 'null'
scroll_offset:
type: 'null'
required:
- scroll_enabled
- scroll_type
- scroll_offset
image:
type: object
properties:
image_as_button:
type: 'null'
image_url:
type: 'null'
image_styles:
type: 'null'
required:
- image_as_button
- image_url
- image_styles
delay:
type: object
properties:
delay:
type: 'null'
delay_options:
type: 'null'
required:
- delay
- delay_options
design:
type: object
properties:
typography:
type:
- object
- 'null'
properties:
family:
type: string
letter_spacing:
type: integer
line_height:
type: number
format: float
size:
type: integer
weight:
type: integer
required:
- family
- letter_spacing
- line_height
- size
- weight
styles:
type:
- object
- 'null'
properties:
background_color:
type: string
border_radius:
type: integer
required:
- background_color
- border_radius
animation:
type: 'null'
rich_element:
type: 'null'
required:
- typography
- styles
- animation
- rich_element
id:
type: string
required:
- base
- window
- action
- scroll
- image
- delay
- design
- id
required:
- enabled
- items
alternative_video:
type: object
properties:
enabled:
type:
- boolean
- 'null'
id:
type:
- string
- 'null'
required:
- enabled
- id
traffic_filter:
type: object
properties:
fallback_video_id:
type:
- string
- 'null'
token:
type:
- string
- 'null'
languages:
type:
- array
- 'null'
items:
type: string
countries:
type:
- array
- 'null'
items:
type: string
devices:
type:
- array
- 'null'
items:
type: string
query_params:
type:
- array
- 'null'
items:
type: string
block_proxy:
type:
- boolean
- 'null'
enabled:
type:
- boolean
- 'null'
required:
- fallback_video_id
- token
- languages
- countries
- devices
- query_params
- block_proxy
styles:
type: object
properties:
background_color:
type: 'null'
foreground_color:
type: 'null'
border_radius:
type: 'null'
linear_gradient:
type: object
properties:
angle:
type: 'null'
primary_color:
type: 'null'
primary_stop:
type: 'null'
secondary_color:
type: 'null'
secondary_stop:
type: 'null'
enabled:
type: 'null'
required:
- angle
- primary_color
- primary_stop
- secondary_color
- secondary_stop
required:
- background_color
- foreground_color
- border_radius
- linear_gradient
general:
type: object
properties:
currency:
type: 'null'
pitch_time:
type: 'null'
preload_type:
type: 'null'
start_quality:
type: 'null'
required:
- currency
- pitch_time
- preload_type
- start_quality
immersive_mode:
type: object
properties:
desktop:
type:
- boolean
- 'null'
disable_scrolling:
type:
- boolean
- 'null'
expand_on_play:
type:
- boolean
- 'null'
minimize_on_pause:
type:
- boolean
- 'null'
mobile:
type:
- boolean
- 'null'
enabled:
type:
- boolean
- 'null'
required:
- desktop
- disable_scrolling
- expand_on_play
- minimize_on_pause
- mobile
mini_hooks:
type: object
properties:
elements:
type: array
items:
type: object
properties:
base:
type: object
properties:
name:
type: string
type:
type: string
active:
type: 'null'
required:
- name
- type
- active
window:
type: object
properties:
start:
type: integer
end:
type: integer
required:
- start
- end
layout:
type: object
properties:
x:
type: number
format: float
'y':
type: number
format: float
width:
type: number
format: float
height:
type: number
format: float
rotation:
type: 'null'
opacity:
type: 'null'
order:
type: integer
required:
- x
- 'y'
- width
- height
- rotation
- opacity
- order
content:
type: object
properties:
src:
type: string
alt:
type: 'null'
value:
type: 'null'
required:
- src
- alt
- value
style:
type: object
properties:
align:
type: 'null'
background_color:
type: 'null'
border_radius:
type: 'null'
padding:
type: 'null'
text_color:
type: 'null'
required:
- align
- background_color
- border_radius
- padding
- text_color
typography:
type: object
properties:
family:
type: 'null'
size:
type: 'null'
weight:
type: 'null'
required:
- family
- size
- weight
counter:
type: object
properties:
color:
type: 'null'
font_size:
type: 'null'
font_weight:
type: 'null'
required:
- color
- font_size
- font_weight
id:
type: string
required:
- base
- window
- layout
- content
- style
- typography
- counter
- id
enabled:
type: 'null'
required:
- elements
pixels:
type: object
properties:
items:
type: array
items:
type: object
properties:
base:
type: object
properties:
name:
type: string
type:
type: string
required:
- name
- type
tag:
type: object
properties:
id:
type: 'null'
value:
type: 'null'
html:
type: string
required:
- id
- value
- html
dispatch:
type: object
properties:
active:
type: boolean
threshold:
type: integer
mode:
type: string
required:
- active
- threshold
- mode
id:
type: string
required:
- base
- tag
- dispatch
- id
enabled:
type:
- boolean
- 'null'
required:
- items
playback:
type: object
properties:
disable_pause:
type:
- boolean
- 'null'
scroll_to_action_in:
type:
- integer
- 'null'
smart_pause:
type:
- boolean
- 'null'
action_after_finish:
type: object
properties:
type:
type:
- string
- 'null'
start:
type:
- integer
- 'null'
required:
- type
- start
enabled:
type:
- boolean
- 'null'
required:
- disable_pause
- scroll_to_action_in
- smart_pause
- action_after_finish
subtitle:
type: object
properties:
control:
type:
- boolean
- 'null'
track:
type: object
properties:
name:
type: 'null'
url:
type:
- string
- 'null'
required:
- name
- url
style:
type: object
properties:
font_size:
type:
- string
- 'null'
color:
type:
- string
- 'null'
background_color:
type:
- string
- 'null'
text_align:
type:
- string
- 'null'
bottom:
type: 'null'
max_width:
type: 'null'
show_by_default:
type:
- boolean
- 'null'
required:
- font_size
- color
- background_color
- text_align
- bottom
- max_width
- show_by_default
enabled:
type:
- boolean
- 'null'
required:
- control
- track
- style
thumbsniper:
type: object
properties:
background_color:
type: 'null'
images:
type: object
properties:
start:
type:
- string
- 'null'
pause:
type:
- string
- 'null'
finish:
type:
- string
- 'null'
required:
- start
- pause
- finish
cards:
type: array
items: {}
enabled:
type: 'null'
required:
- background_color
- images
- cards
turbo:
type: object
properties:
enabled:
type:
- boolean
- 'null'
mode:
type: string
speed:
type:
- number
- 'null'
format: float
required:
- enabled
- mode
- speed
headline:
type: object
properties:
enabled:
type: 'null'
mode:
type: string
active_number:
type: 'null'
variants:
type: array
items:
type: object
properties:
base:
type: object
properties:
name:
type:
- string
- 'null'
number:
type: integer
active:
type: 'null'
required:
- name
- number
- active
content:
type: object
properties:
kind:
type: string
responsive:
type: 'null'
url_desktop:
type: 'null'
url_mobile:
type: 'null'
html:
type:
- string
- 'null'
css:
type: 'null'
required:
- kind
- responsive
- url_desktop
- url_mobile
- html
- css
style:
type: object
properties:
typography:
type: 'null'
layout:
type: 'null'
required:
- typography
- layout
id:
type: string
required:
- base
- content
- style
- id
required:
- enabled
- mode
- active_number
- variants
progress_bar:
type: object
properties:
height:
type:
- integer
- 'null'
use_base_color:
type:
- boolean
- 'null'
current_color:
type:
- string
- 'null'
color:
type:
- string
- 'null'
enabled:
type:
- boolean
- 'null'
required:
- height
- use_base_color
- current_color
- color
resume:
type: object
properties:
disable_pause:
type:
- boolean
- 'null'
styles:
type: object
properties:
background_color:
type:
- string
- 'null'
foreground_color:
type:
- string
- 'null'
required:
- background_color
- foreground_color
texts:
type: object
properties:
play:
type:
- string
- 'null'
replay:
type:
- string
- 'null'
title:
type:
- string
- 'null'
required:
- play
- replay
- title
enabled:
type:
- boolean
- 'null'
required:
- disable_pause
- styles
- texts
smart_autoplay:
type: object
properties:
enabled:
type:
- boolean
- 'null'
mode:
type: string
active_number:
type: 'null'
variants:
type: array
items:
type: object
properties:
template_name:
type: string
template_position:
type: string
id:
type: string
required:
- template_name
- template_position
- id
required:
- enabled
- mode
- active_number
- variants
required:
- id
- status
- controls
- call_actions
- alternative_video
- traffic_filter
- name
- description
- folder_id
- styles
- general
- immersive_mode
- mini_hooks
- pixels
- playback
- subtitle
- thumbsniper
- turbo
- headline
- progress_bar
- resume
- smart_autoplay
example:
id: 652f2b1e8f1b2c3d4e5f6a7b
name: Landing hero
description: null
folder_id: null
status: processing
controls:
backward: null
big_play: null
forward: null
fullscreen: null
play_pause: null
seekbar: null
time: null
volume: null
fake_bar: null
speed: null
call_actions:
enabled: false
items: []
alternative_video:
enabled: null
id: null
traffic_filter:
fallback_video_id: null
token: null
languages: null
countries: null
devices: null
query_params: null
block_proxy: null
enabled: null
styles:
background_color: null
foreground_color: null
border_radius: null
linear_gradient:
angle: null
primary_color: null
primary_stop: null
secondary_color: null
secondary_stop: null
enabled: null
general:
currency: null
pitch_time: null
preload_type: null
start_quality: null
immersive_mode:
desktop: null
disable_scrolling: null
expand_on_play: null
minimize_on_pause: null
mobile: null
enabled: null
mini_hooks:
elements: []
enabled: null
pixels:
items: []
enabled: null
playback:
disable_pause: null
scroll_to_action_in: null
smart_pause: null
action_after_finish:
type: null
start: null
enabled: null
subtitle:
control: null
track:
name: null
url: >-
https://static.vturb.com/assets/org_123/2026/08/12/0190a0b0-2222-7222-8222-222222222222/original.vtt
style:
font_size: null
color: null
background_color: null
text_align: null
bottom: null
max_width: null
show_by_default: null
enabled: null
thumbsniper:
background_color: null
images:
start: null
pause: null
finish: null
cards: []
enabled: null
turbo:
enabled: null
mode: single
speed: null
headline:
enabled: null
mode: single
active_number: null
variants: []
progress_bar:
height: null
use_base_color: null
current_color: null
color: null
enabled: null
resume:
disable_pause: null
styles:
background_color: null
foreground_color: null
texts:
play: null
replay: null
title: null
enabled: null
smart_autoplay:
enabled: null
mode: single
active_number: null
variants: []
'400':
description: An unrecognized field is a 400 naming it — never a silent no-op.
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
code:
type: string
message:
type: string
field:
type: string
request_id:
type: string
required:
- type
- code
- message
- field
- request_id
example:
type: https://docs.vturb.com/errors/bad_request
code: bad_request
message: The request includes fields this endpoint does not accept.
field: unknown
request_id: 00000000-0000-0000-0000-000000000000
'401':
description: Missing API credential.
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
code:
type: string
message:
type: string
request_id:
type: string
required:
- type
- code
- message
- request_id
example:
type: https://docs.vturb.com/errors/unauthorized
code: unauthorized
message: >-
Missing or invalid API credential. Send a vt_ token in the
Authorization header.
request_id: 00000000-0000-0000-0000-000000000000
'403':
description: The credential is missing the videos:write scope.
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
code:
type: string
message:
type: string
request_id:
type: string
required:
- type
- code
- message
- request_id
example:
type: https://docs.vturb.com/errors/forbidden
code: forbidden
message: The credential is missing the scope this action requires.
request_id: 00000000-0000-0000-0000-000000000000
'404':
description: No video matches that id for the authenticated caller.
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
code:
type: string
message:
type: string
request_id:
type: string
required:
- type
- code
- message
- request_id
example:
type: https://docs.vturb.com/errors/not_found
code: not_found
message: Resource not found.
request_id: 00000000-0000-0000-0000-000000000000
'422':
description: >-
A v3 call-to-action is validated as it would be stored; each failure
is named `call_actions.items[].`.
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
code:
type: string
message:
type: string
request_id:
type: string
errors:
type: array
items:
type: object
properties:
field:
type: string
message:
type: string
required:
- field
- message
required:
- type
- code
- message
- request_id
- errors
example:
type: https://docs.vturb.com/errors/unprocessable_content
code: unprocessable_content
message: The request is invalid. See errors for the fields that failed.
request_id: 00000000-0000-0000-0000-000000000000
errors:
- field: call_actions.items[0].window.start
message: must be less than the end time
- field: call_actions.items[0].action.url
message: must be present
- field: call_actions.items[0].action.content
message: must be present
- field: call_actions.items[0].design.typography
message: must be present
- field: call_actions.items[0].design.styles
message: must be present
'503':
description: The update could not be persisted right now; retry shortly.
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
code:
type: string
message:
type: string
request_id:
type: string
required:
- type
- code
- message
- request_id
example:
type: https://docs.vturb.com/errors/service_unavailable
code: service_unavailable
message: The service is temporarily unavailable. Retry shortly.
request_id: 00000000-0000-0000-0000-000000000000
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Paste your VTurb API token (vt_...). Sent as `Authorization: Bearer
`.
````