Create a story

post

https://partner-api.join-stories.com/v1/v1/stories

Creates a story and attaches it to one or more widgets. Aliases are slugified (special characters stripped, case preserved). The response alias is the primary widget; aliases lists every widget the story was attached to. Generation and widget publish run in the background after 201. Create can take up to 360s.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Omit elements in a template

Only elements explicitly provided in pages[].elements (by keyName matching the template element’s name) are instantiated. If an element is omitted, it is not added to the final page.

widgets vs widgetAlias

Send either widgets (one or more aliases) or the deprecated widgetAlias, never both (400). Only title and pages (min. 1) are required.

Root widgetAlias, widgetPresetAlias, widgetCoverMediaId, order, productPages, and schedule are defaults applied to each widget. Prefer per-entry fields under widgets.

Body Params

title

string

required

This is the title of the story. It won't be displayed to the end user, but will be used for managing your stories.

pages

array of objects

required

At least one page. Each page requires templateId (UUID) and elements (array). pages[].elements[].value is required when type=text. fontSize is a number. pages[].interaction supports type shopping with productIds (min 1), buttonType, buttonLabel, shoppingIcon.

pages*

widgets

object

Object keyed by alias. Same shape as PUT widgets. First key is the primary widget. Empty object → 400. Converging keys after slugify → 400. Mutually exclusive with widgetAlias. Missing widgets are created from widgetPresetAlias (entry or root default). Each entry may include audiences, productPages, widgetOrder, order, schedule, widgetCoverMediaId, widgetPresetAlias, widgetLabel.

widgetAlias

string

Deprecated single-widget form. Mutually exclusive with widgets. Must be a string if sent (not null). Aliases are slugified (special characters stripped, case preserved).

widgetPresetAlias

string

Deprecated. Default preset for every widget without its own. Required only when creating a widget that does not exist yet.

widgetLabel

string

Optional default label for widgets that omit their own. Displayed beneath the story bubble.

widgetCoverMediaId

string

Optional default cover. Pass the encoded fileKey from upload as-is. A video cover uses the video thumbnail as the Studio story card; the mp4 stays on the widget cover.

widgetPresetKeepStories

boolean

Defaults to false

Primary widget only. Widgets created via widgets never keep preset stories.

order

int32

Deprecated. Maps to widgets[alias].widgetOrder. Ignored when productPages is set.

schedule

object

Optional default schedule (when the story is added or removed from the widget).

audiences

array of objects

Root audiences apply to the primary widget only. Use widgets[alias].audiences for the others. Destination widget must already exist. Contact JOIN for audience IDs.

audiences

productPages

array of objects

Default product-page associations for widgets that omit their own. Min 1 entry when sent. Forbidden on non–product-matcher widgets.

productPages

Responses

Omit elements in a template

widgets vs widgetAlias

201201

400400