> ## Documentation Index > Fetch the complete documentation index at: https://docs.convertly.sh/llms.txt > Use this file to discover all available pages before exploring further. # Workflows > Build reusable media workflows in the Convertly dashboard. Workflows let users chain common media operations into a reusable flow. They are useful for repeatable upload pipelines such as converting a file, compressing it, saving the result, and notifying another system when work is finished. ## Current workflow capabilities | Capability | Status | | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | | Visual workflow builder | Available in the dashboard. | | Test runs | Available with generated sample media. | | Convert, compress, resize, audio, storage, and webhook steps | Supported by the workflow engine. | | Saved workflow templates | Available on all plans. Free includes 1 saved workflow; see [Limits](/limits#workflows). | | Large production processing | Live workflow runs are queued through Convertly workers. | ## How to use workflows 1. Open **Dashboard > Workflows**. 2. Create a workflow. 3. Choose conversion, compression, storage, and webhook steps. 4. Run a test to validate the flow. 5. Save the workflow. Live runs are processed asynchronously. ## Production guidance Live workflow runs return immediately with a run ID and continue in the worker queue. For programmatic batch workloads, use `POST /api/jobs` with webhooks when you need idempotency keys, archive delivery, and direct API-level control. ## Workflow API Workflows can be authored and executed without ever opening the dashboard. The endpoints accept either a Convertly dashboard session or a Bearer-token API key. WordPress site-scoped keys are not allowed. Workflows belong to the workspace owner. Full request and response shapes are in the [Workflows API reference](/api-reference/workflows/list-workflows). | Method | Endpoint | Use | | -------- | ------------------------- | ------------------------------------------------------------------------------------------------ | | `GET` | `/api/workflows` | List every workflow on the account, including the saved definition. | | `POST` | `/api/workflows` | Create a new workflow (no `id`) or replace an existing one (`id` set). | | `PATCH` | `/api/workflows/{id}` | Pause or resume a workflow (`{ "isActive": false }`). | | `DELETE` | `/api/workflows/{id}` | Remove a workflow. Past runs are kept. | | `POST` | `/api/workflows/{id}/run` | Multipart upload (`file=@...`). Runs the saved definition end-to-end and returns the run record. | | `GET` | `/api/workflows/{id}/run` | List the 50 most recent runs for a workflow. | The `POST /api/workflows` payload mirrors the dashboard builder's schema: ```json theme={"system"} { "name": "Convert + compress for the web", "template": "convert-compress-post", "outputFormat": "webp", "compressionMode": "balanced", "isActive": true, "definition": { "outputFormat": "webp", "compressionLevel": 75, "audioOutputFormat": "mp3", "nodes": [ { "id": "upload", "data": { "kind": "upload" } }, { "id": "convert", "data": { "kind": "convert" } }, { "id": "compress", "data": { "kind": "compress" } }, { "id": "storage", "data": { "kind": "storage" } } ], "edges": [ { "source": "upload", "target": "convert" }, { "source": "convert", "target": "compress" }, { "source": "compress", "target": "storage" } ], "uploadSource": "api", "uploadLogicGate": "and", "uploadConditions": [], "storageDestination": "convertly-storage", "renamePattern": "{original}-{format}", "resizeWidth": "1920" } } ``` Running the workflow against a local file: ```bash theme={"system"} curl -X POST "https://convertly.sh/api/workflows//run" \ -H "Authorization: Bearer $CONVERTLY_API_KEY" \ -F "file=@./hero.png" ``` ## AI agents (MCP) The Convertly MCP server exposes the same workflow surface to Claude, Cursor, Codex, and any MCP-compatible client. Once `@convertly-sh/mcp` is connected, an agent can be told things like *"create a workflow that converts incoming images to AVIF, compresses them, and saves the output to my main storage"*. The agent will pick the right tool, build the definition, and confirm with you before destructive actions. | Tool | Use | | --------------------- | ---------------------------------------------------------------- | | `list_workflows` | Read every saved workflow. | | `create_workflow` | Create a new pipeline. The schema mirrors `POST /api/workflows`. | | `update_workflow` | Replace the full definition of an existing workflow. | | `set_workflow_active` | Pause or resume. | | `delete_workflow` | Remove a workflow (requires `confirm: true`). | | `run_workflow` | Upload a local file and execute the workflow end-to-end. | | `list_workflow_runs` | Pull the 50 most recent runs for a workflow. | See [MCP for AI agents](/docs/mcp-agents) for client setup. ## Step types Workflows are built from typed nodes. Every node has a `kind` and an optional `config` bag. The engine's per-node executor reads whichever config keys it cares about and ignores the rest. | Category | Kind | What it does | Example `config` | | -------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | Trigger | `upload` | Entry point. The file you upload (or post via `/api/workflows/{id}/run`) lands here. | | | Encoding | `convert` | Transcode to a target format. | `{ "outputFormat": "webp", "compressionLevel": 80 }` | | Encoding | `compress` | Re-encode at lower quality without changing the format. | `{ "compressionLevel": 60 }` | | Encoding | `resize` | Scale via sharp. | `{ "width": 1600, "fit": "inside" }` | | Encoding | `audio` | Audio re-encode. | `{ "outputFormat": "m4a", "compressionLevel": 80 }` | | Image | `background_remove` | Remove image background via the bundled model. | `{ "outputFormat": "png", "model": "small" }` | | Image | `adjust` | Brightness / saturation / contrast / hue / grayscale / sharpen / invert. | `{ "brightness": 1.2, "saturation": 1.05, "grayscale": true }` | | Image | `strip_metadata` | Drop EXIF / XMP / ICC and other non-image metadata. | | | Utility | `rename` | Rewrite the filename. Pattern tokens: `{original}`, `{format}`, `{ext}`, `{timestamp}`. | `{ "pattern": "{original}-w" }` | | Logic | `branch` | Evaluate a condition group. The matching path continues, the other is skipped. The branch's two outgoing edges must have `kind: "true"` and `kind: "false"`. | (set `branchConditions` on the definition) | | Delivery | `storage` | Persist the current buffer to Convertly Storage. | | | Delivery | `webhook` | Fire `workflow.completed` to your registered webhook endpoints. | | | Delivery | `publish` / `platform` | Queue a social publish for `selectedPlatforms`. | | The following kinds round-trip through the API and the dashboard but don't have an executor wired yet: `transform`, `watermark`, `trim`, `thumbnail`, `poster_frame`, `storyboard`, `extract_audio`, `gif`, `image_to_pdf`, `pdf_preview`, `inspect`. They'll execute as soon as their executors land. The schema is stable now so you can author against it. ## Related docs Queue larger media workloads and track progress.