Skip to main content
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

CapabilityStatus
Visual workflow builderAvailable in the dashboard.
Test runsAvailable with generated sample media.
Convert, compress, resize, audio, storage, and webhook stepsSupported by the workflow engine.
Saved workflow templatesAvailable on all plans. Free includes 1 saved workflow; see Limits.
Large production processingLive 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.
MethodEndpointUse
GET/api/workflowsList every workflow on the account, including the saved definition.
POST/api/workflowsCreate 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}/runMultipart upload (file=@...). Runs the saved definition end-to-end and returns the run record.
GET/api/workflows/{id}/runList 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.
ToolUse
list_workflowsRead every saved workflow.
create_workflowCreate a new pipeline. The schema mirrors POST /api/workflows.
update_workflowReplace the full definition of an existing workflow.
set_workflow_activePause or resume.
delete_workflowRemove a workflow (requires confirm: true).
run_workflowUpload a local file and execute the workflow end-to-end.
list_workflow_runsPull 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.
CategoryKindWhat it doesExample config
TriggeruploadEntry point. The file you upload (or post via /api/workflows/{id}/run) lands here.
EncodingconvertTranscode to a target format.{ "outputFormat": "webp", "compressionLevel": 80 }
EncodingcompressRe-encode at lower quality without changing the format.{ "compressionLevel": 60 }
EncodingresizeScale via sharp.{ "width": 1600, "fit": "inside" }
EncodingaudioAudio re-encode.{ "outputFormat": "m4a", "compressionLevel": 80 }
Imagebackground_removeRemove image background via the bundled model.{ "outputFormat": "png", "model": "small" }
ImageadjustBrightness / saturation / contrast / hue / grayscale / sharpen / invert.{ "brightness": 1.2, "saturation": 1.05, "grayscale": true }
Imagestrip_metadataDrop EXIF / XMP / ICC and other non-image metadata.
UtilityrenameRewrite the filename. Pattern tokens: {original}, {format}, {ext}, {timestamp}.{ "pattern": "{original}-w" }
LogicbranchEvaluate 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)
DeliverystoragePersist the current buffer to Convertly Storage.
DeliverywebhookFire workflow.completed to your registered webhook endpoints.
Deliverypublish / platformQueue 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.