Create an interaction

post

https://api.mindstamp.com/api/v1/interactions/create

Create a new annotation for a specified video. Supports visible interaction annotations (button, image, text, hotspot) and timed action annotations (redirect, jump, switch, pause, resourceTray, variable, reset_viewer, reset_interactions).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Query Params

video_id

string

required

The video_id or token of the video you want to add the interaction to.

type

string

enum

required

Annotation type. Visible types require layout and click action fields. Timed action types use their type-specific fields. Supported values: button, image, text, hotspot, redirect, jump, switch, pause, resourceTray, variable, reset_viewer, reset_interactions.

time

float

required

When the interaction should appear on the screen

finish

float

When a visible interaction should leave the screen. Optional for timed action annotations.

top

float

Visible interaction layout percentage persisted to pos_top. Required for button, image, text, and hotspot creates.

left

float

Visible interaction layout percentage persisted to pos_left. Required for button, image, text, and hotspot creates.

height

float

Visible interaction layout percentage persisted to pos_height. Required for button, image, text, and hotspot creates.

width

float

Visible interaction layout percentage persisted to pos_width. Required for button, image, text, and hotspot creates.

click_action

string

enum

Visible interaction click action. Required for button, image, text, and hotspot creates. Supported values: track, link, jump, video, back, message, view, genie, cart, openai, clip, audio, email, phone, modal, collect, download, resourceTray, show_card, get, post, redirect, pause, article, copy, none. Timed action annotations choose the matching action automatically.

click_value

string

Action value. For redirect this can be the URL; for jump this can be the target timestamp; for switch this can be Video Title ---TOKEN.

content

string

A button's text, a text's content, an image source URL, or empty for hotspot

tooltip

string

pause_amount

integer

Pause duration in seconds for type=pause or visible interactions that pause on click. Use -1 to pause until the viewer resumes.

click_required

boolean

text_color

string

Visible interaction text color. Defaults to the video design when omitted.

background_color

string

Visible interaction background color. Defaults to the video design when omitted.

border_color

string

Visible interaction border color. Defaults to the video design when omitted.

border_radius

string

Visible interaction border radius. Defaults to the video design when omitted.

font_size

string

Visible interaction font size persisted to font_size.

redirect_url

string

Redirect destination URL for type=redirect. Alias for click_value on redirect annotations.

target_time

float

Target timestamp in seconds for type=jump. Alias for click_value on jump annotations.

target_video_id

string

Target video ID for type=switch. The API stores it as Video Title ---TOKEN in click_value.

target_video_token

string

Target video token for type=switch. The API stores it as Video Title ---TOKEN in click_value.

click_time

float

Start time in the target video for type=switch.

timer

integer

Pause duration in seconds for type=pause. Use -1 to pause until the viewer resumes. Alias for pause_amount.

variable

string

Variable name for type=variable.

value

string

Variable value for type=variable.

tooltip_text

string

pause

boolean

Whether to pause video playback while this interaction is active.

must_click

boolean

Alias for click_required. Requires the viewer to click this interaction.

hidden

boolean

Hide this interaction by default.

hide_mobile

boolean

Hide this interaction on mobile devices.

hide_desktop

boolean

Hide this interaction on desktop devices.

border_width

string

Interaction border width.

text_align

string

Interaction text alignment.

transition

string

Interaction entrance transition.

animation

string

Interaction animation.

caption

string

Caption for image and hotspot interactions.

show_caption

boolean

Whether to show the caption for image and hotspot interactions.

background_image

string

Hotspot background image URL.

points

string

Hotspot polygon points as a JSON string or persisted string value.

hotspot_show_ring

boolean

Whether to show the hotspot ring.

hotspot_ring_width

integer

Hotspot ring width.

hotspot_alignment

integer

Hotspot alignment value.

hotspot_radius

integer

Hotspot radius.

hotspot_hover

boolean

Whether to enable hotspot hover behavior.

force_lead_capture

boolean

Require lead capture before running the interaction action.

do_spotlight

boolean

Spotlight the interaction.

post_click_state

string

Post-click state for the interaction.

post_click_color

string

Post-click background color.

post_click_text_color

string

Post-click text color.

internal_label

string

Internal label for organization use.

is_conditional

boolean

Enable conditional display logic.

conditional_show

boolean

Show the interaction when the condition matches.

conditional_variable

string

Conditional variable name.

conditional_assertion

string

Conditional comparison operator.

conditional_value

string

Conditional comparison value.

conditional_operator

integer

Operator used when combining two conditions.

is_conditional_2

boolean

Enable a second conditional rule.

conditional_variable_2

string

Second conditional variable name.

conditional_assertion_2

string

Second conditional comparison operator.

conditional_value_2

string

Second conditional comparison value.

tray

boolean

Include the interaction in a tray.

tray_type

string

Tray type, such as magic_menu or end_menu.

hubspot_field

string

HubSpot field name.

hubspot_value

string

HubSpot field value.

question_map_hubspot

boolean

Map the interaction value to HubSpot.

clickfunnels_active

boolean

Enable ClickFunnels integration.

clickfunnels_tag

string

ClickFunnels tag.

clickfunnels_custom_attribute_name

string

ClickFunnels custom attribute name.

clickfunnels_custom_attribute_value

string

ClickFunnels custom attribute value.

Responses

401

Not Authorized

404

Not Found

422

Unprocessable Entity

500

Error

503

Rate Limit Exceeded

200Success

201Created