Workflows

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.
Large production processing	Live workflow runs are queued through Convertly workers.

How to use workflows

Open Dashboard > Workflows.
Create a workflow.
Choose conversion, compression, storage, and webhook steps.
Run a test to validate the flow.
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 and remain available to its owners if the billing owner changes. Full request and response shapes are in the Workflows API reference.

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:

{
  "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:

curl -X POST "https://convertly.sh/api/workflows/<workflow-id>/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 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.

Async jobs

Queue larger media workloads and track progress.

Getting Started

Image CDN

Media Platform

SDKs & Integrations

Resources

Current workflow capabilities

How to use workflows

Production guidance

Workflow API

AI agents (MCP)

Step types

Async jobs

​Current workflow capabilities

​How to use workflows

​Production guidance

​Workflow API

​AI agents (MCP)

​Step types

​Related docs

Async jobs

Current workflow capabilities

How to use workflows

Production guidance

Workflow API

AI agents (MCP)

Step types

Related docs