Skip to content

Create Or Update Story#

Creates a new Story if no story exists with the given external ID, otherwise updates the existing Story and pages. Prefer this workflow when you want an idempotent story import path.

  • Workflow ID: create-or-update-story

Example Request#

{
  "workflows": ["create-or-update-story"],
  "mediaUrls": [
    "https://cdn.example.com/videos/story-ext-500-page-01.mp4",
    "https://cdn.example.com/videos/story-ext-500-page-02.mp4"
  ],
  "metadata": {
    "StoryExternalId": "story-ext-500",
    "StoryTitle": "Weekly Recap",
    "ShortDisplayTitle": "Weekly Recap",
    "LongDisplayTitle": "Weekly Sports Recap",
    "CategoryIds": ["recap", "top-stories"],
    "CategorySchedules": [
      { "ExternalId": "recap" },
      { "ExternalId": "top-stories", "PublishAt": "2025-10-02T09:00:00Z" }
    ],
    "ThumbnailUrl": "https://cdn.example.com/images/story-500-thumb.jpg",
    "IconUrl": "https://cdn.example.com/images/story-500-icon.png",
    "CustomSizeThumbnailUrl": "https://cdn.example.com/images/story-500-custom.png",

    "https://cdn.example.com/videos/story-ext-500-page-01.mp4": {
      "Duration": 12,
      "SortOrder": 1,
      "IsHidden": false,
      "SkipUpdatingAsset": false,
      "SkipProcessing": false,
      "ExternalId": "page-ext-500-01",
      "ActionLinkId": "11111111-1111-1111-1111-111111111111"
    },
    "https://cdn.example.com/videos/story-ext-500-page-02.mp4": {
      "Duration": 9,
      "SortOrder": 2,
      "IsHidden": false,
      "SkipUpdatingAsset": true,
      "SkipProcessing": false,
      "ExternalId": "page-ext-500-02"
    }
  }
}

Metadata#

Key Type Required Remarks
StoryExternalId string Yes Root-level. External ID used to find or create the story.
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.
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.
SkipUpdatingAsset boolean No Per-media. If true, do not update existing asset if present.
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.
ExternalId string No Per-media. External identifier for the page asset.
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-or-update-story"],
  "mediaUrls": ["https://cdn.example.com/videos/story-ext-500-page-01.mp4"],
  "metadata": {
    "StoryExternalId": "story-ext-500",
    "StoryTitle": "Weekly Recap",
    "https://cdn.example.com/videos/story-ext-500-page-01.mp4": {
      "Duration": 12,
      "SortOrder": 1
    }
  }
}
JSON