Skip to content

Workflows Overview#

Workflows are the core concept of the Storyteller Integration API. They encapsulate the processing steps that Storyteller performs on the media you send, ensuring that your content is routed to the correct place within Storyteller with minimal effort on your part.

What is a Workflow?#

A Workflow is a predefined set of processing steps that handle your media according to your specific requirements. When you send content to Storyteller through the Integration API, you specify which workflows should be applied to that content.

Workflows use the metadata associated with your request to:

  • Route media to the correct destination within Storyteller
  • Apply appropriate processing steps
  • Set up content categorization and organization
  • Handle format conversions and optimizations

How Workflows Work#

graph LR
    A[Send Media URL] --> B[Select Workflow]
    B --> C[Provide Metadata]
    C --> D[Execute Workflow]
    D --> E[Monitor Progress]
    E --> F[Content Available in Storyteller]

The Workflow Process#

  1. Discovery - Call the GET /api/workflows endpoint to see available workflows
  2. Selection - Choose the appropriate workflow(s) for your content
  3. Execution - Send your media URL and metadata to POST /api/workflows/execute
  4. Tracking - Monitor progress using the returned correlation ID
  5. Completion - Receive webhook notifications or check status for completion

Workflow Types#

Different workflows are designed for different types of content and use cases:

Common Workflows#

  • add-media - Add media to the media library for general content
  • add-clip - Create clips from media assets
  • create-story - Create new stories with content
  • add-to-story - Add pages to existing stories
  • create-sheet - Create interactive sheets
  • create-cards - Create card-based content
  • add-to-content-bank - Add media assets to the content bank for future use

Custom Workflows#

If your integration requires specialized processing, custom workflows can be developed. These are tailored to your specific requirements and will have unique workflow codes provided by Storyteller.

Workflow Availability

The specific workflows available to you depend on your Storyteller account configuration. Use the Getting Workflows endpoint to see your available options.

Workflow Metadata#

Each workflow defines two types of metadata:

Required Metadata#

Metadata fields that must be provided for the workflow to execute successfully. Common required fields include:

  • Title - Human-readable title for the content
  • Source - Origin or source of the content

Optional Metadata#

Metadata fields that can influence workflow execution but are not strictly required. If not provided, default values or inferred values will be used:

  • Description - Content description
  • Tags - Content categorization tags
  • Category - Content category
  • PublishDate - When the content should be published

Example Workflow Response#

When you call GET /api/workflows, you'll receive a response like this:

{
  "workflows": [
    {
      "id": "add-media",
      "name": "Add Media",
      "description": "Basic workflow for adding media content to Storyteller",
      "requiredMetadata": [
        {
          "key": "Title",
          "fieldLabel": "Content Title",
          "description": "The title or name of the content"
        }
      ],
      "optionalMetadata": [
        {
          "key": "Description",
          "fieldLabel": "Content Description",
          "description": "Optional description of the content"
        },
        {
          "key": "Tags",
          "fieldLabel": "Content Tags",
          "description": "Comma-separated tags for categorization"
        }
      ]
    }
  ]
}

Workflow Execution#

To execute a workflow:

{
  "workflows": ["add-media"],
  "mediaUrls": ["https://example.com/video.mp4"],
  "metadata": {
    "https://example.com/video.mp4": {
      "Title": "My Amazing Video",
      "Description": "A great piece of content",
      "Tags": "entertainment,viral"
    }
  }
}

Error Handling#

Workflows can fail for various reasons:

  • Missing Required Metadata - Required fields not provided
  • Invalid Media URL - URL not accessible or invalid format
  • Processing Errors - Issues during content processing
  • Quota Limits - Account limits exceeded

See our Troubleshooting guide for common issues and solutions.

Workflow Pages#

Learn more about working with workflows:

Best Practices#

Workflow Selection#

  • Always call GET /api/workflows to get current available workflows
  • Choose the most specific workflow for your content type
  • Test workflows with sample content before production use

Metadata Management#

  • Provide all required metadata to avoid failures
  • Use meaningful, descriptive titles and metadata
  • Validate metadata format before sending requests

Error Handling#

  • Implement retry logic for transient failures
  • Monitor workflow status for completion or errors
  • Set up webhook handlers for real-time notifications

Ready to start working with workflows? Begin with Getting Workflows to see what's available for your account.