Ittybit

Overview

A workflow defines the sequence of tasks that an Automation will run when its trigger event occurs.

Each step in the workflow represents a task — such as creating a video, generating subtitles, or analyzing content.

Workflows are defined as an ordered array of task objects inside the automation.

Structure

A workflow is an array of task definitions that describe what should happen and in what order.

Each task in the workflow includes:

Property	Description
`kind`	The kind of task to create (e.g. `video`, `image`, `description`, `subtitles`, `thumbnails`, `chapters`, etc.).
`ref`	An optional reference name for the task, used to link outputs or identify specific results.
Additional props	Any valid Task parameters supported by the given `kind`, such as `format`, `width`, `height`, or `quality`.

Example — Sequential Workflow

This example creates a workflow that converts videos to MP4 format, then generates subtitles, thumbnails, and chapters.

Example Automation

{
  "name": "Video Compression Pipeline",
  "description": "Convert videos to MP4, generate subtitles, thumbnails, and chapters.",
  "trigger": {
    "kind": "event",
    "event": "media.created"
  },
  "workflow": [
    {
      "kind": "video",
      "format": "mp4",
      "quality": 75,
      "ref": "compressed-video"
    },
    {
      "kind": "subtitles",
      "ref": "video-subtitles"
    },
    {
      "kind": "thumbnails",
      "count": 3,
      "ref": "video-thumbnails"
    },
    {
      "kind": "chapters",
      "ref": "video-chapters"
    }
  ],
  "status": "active"
}

When a new media object is created (media.created), this automation will:

Compress the video to MP4 (video task).
Generate subtitles.
Generate three thumbnails.
Generate a chapter track.

Each task runs automatically in order.

Example — Conditional Workflow

Workflows can include conditions to control which tasks run next, based on properties of the input.

{
  "workflow": [
    {
      "kind": "description"
    },
    {
      "kind": "image",
      "width": 320,
      "format": "png",
      "ref": "thumbnail"
    },
    {
      "kind": "conditions",
      "conditions": [
        { "prop": "kind", "value": "video" }
      ],
      "next": [
        {
          "kind": "subtitle",
          "ref": "subtitle"
        }
      ]
    }
  ]
}

In this example, the workflow runs an image and description step for all inputs, but only adds subtitles when the file’s kind is video.

Creating Workflows via API

You can define the workflow when creating or updating automations via the /automations endpoint.

const automation = await ittybit.automations.create({
  name: "Video Processing Workflow",
  trigger: {
    kind: "event",
    event: "media.created"
  },
  workflow: [
    { kind: "video", format: "mp4", quality: 75 },
    { kind: "subtitles" },
    { kind: "thumbnails", count: 3 }
  ],
  status: "active"
});

Workflow Execution

Tasks run in order from top to bottom.
Each task’s output becomes available for subsequent steps.
Conditional branches (conditions → next) allow you to run tasks only for certain inputs.
A workflow belongs to an Automation — it is not run independently.

Summary

Workflows define how your automations process media — the sequence, logic, and structure of all the tasks that run when a trigger event occurs.

They make it easy to chain together multiple Ittybit tasks, ensuring each step runs automatically in response to new files, events, or media in your project.

Workflows