Add Story

Creates a new Story and one or more Pages in a single workflow.

• Workflow ID: create-story

Example Request

{
  "workflows": ["create-story"],
  "mediaUrls": [
    "https://cdn.example.com/videos/story-new-page-01.mp4",
    "https://cdn.example.com/videos/story-new-page-02.mp4"
  ],
  "metadata": {
    "ExternalId": "story-ext-001",
    "StoryTitle": "Matchday Wrap-Up",
    "ShortDisplayTitle": "Matchday Wrap",
    "LongDisplayTitle": "Matchday Wrap-Up — All the Action",
    "CategoryIds": ["football", "featured"],
    "CategorySchedules": [
      { "ExternalId": "football" },
      { "ExternalId": "featured", "PublishAt": "2025-10-01T18:00:00Z" }
    ],
    "ThumbnailUrl": "https://cdn.example.com/images/story-thumb.jpg",
    "IconUrl": "https://cdn.example.com/images/story-icon.png",
    "CustomSizeThumbnailUrl": "https://cdn.example.com/images/story-custom-thumb.png",

    "https://cdn.example.com/videos/story-new-page-01.mp4": {
      "Duration": 10,
      "SortOrder": 1,
      "IsHidden": false,
      "PageExternalId": "page-ext-001",
      "SkipProcessing": false,
      "ActionLinkId": "11111111-1111-1111-1111-111111111111",
      "TemplateMetadata": { "lowerThird": "enabled" }
    },
    "https://cdn.example.com/videos/story-new-page-02.mp4": {
      "Duration": 8,
      "SortOrder": 2,
      "IsHidden": false,
      "PageExternalId": "page-ext-002",
      "SkipProcessing": false
    }
  }
}

Metadata

Key	Type	Required	Remarks
ExternalId	string	No	Root-level. Your external ID for the story (recommended).
StoryTitle	string	No	Root-level. Story title.
ShortDisplayTitle	string	No	Root-level. Short display title.
LongDisplayTitle	string	No	Root-level. Long display title.
CategoryIds	ArrayOf(string)	No	Root-level. Category external IDs to associate with the story.
CategorySchedules	ArrayOf(object)	No	Root-level. Rich category schedule entries with ExternalId and optional schedule fields.
ThumbnailUrl	string	No	Root-level. Story thumbnail image URL.
IconUrl	string	No	Root-level. Story icon/round image URL.
CustomSizeThumbnailUrl	string	No	Root-level. Alternate thumbnail image URL.
Duration	integer	No	Per-media. Page duration in seconds.
SortOrder	integer	No	Per-media. Page order within the story.
IsHidden	boolean	No	Per-media. Whether the page is hidden.
PageExternalId	string	No	Per-media. External ID for the page.
SkipProcessing	boolean	No	Per-media. If true, skip media processing for this page.
ActionLinkId	Guid	No	Per-media. Associate an action link with the page.
TemplateMetadata	object	No	Per-media. Template-specific values when using templates.

cURL Example

curl -X POST "https://integrations.usestoryteller.com/api/workflows/execute" \
  -H "x-storyteller-api-key: $ST_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "workflows": ["create-story"],
  "mediaUrls": ["https://cdn.example.com/videos/story-new-page-01.mp4"],
  "metadata": {
    "ExternalId": "story-ext-001",
    "StoryTitle": "Matchday Wrap-Up",
    "https://cdn.example.com/videos/story-new-page-01.mp4": {
      "Duration": 10,
      "SortOrder": 1
    }
  }
}
JSON