# Workflows

[View original](https://ittybit.com/docs/workflows)

## 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](/docs/tasks) 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.

```json title="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:

1. Compress the video to MP4 (`video` task).
2. Generate subtitles.
3. Generate three thumbnails.
4. 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.

```json
{
  "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.

```js
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.