Create Workflow

Create a workflow programmatically

Published Jul 11, 2026·Updated Jul 15, 2026

POST

/v1/workflows

curl -X POST "https://api.orshot.com/v1/workflows" \
  -H "Authorization: Bearer <ORSHOT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": [],
    "name": "<NAME>",
    "description": "<DESCRIPTION>",
    "status": "<STATUS>"
  }'

const res = await fetch("https://api.orshot.com/v1/workflows", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    "steps": [],
    "name": "<NAME>",
    "description": "<DESCRIPTION>",
    "status": "<STATUS>"
  }),
});

const data = await res.json();

import requests

response = requests.post(
    "https://api.orshot.com/v1/workflows",
    headers={"Authorization": "Bearer <ORSHOT_API_KEY>"},
    json={
      "steps": [],
      "name": "<NAME>",
      "description": "<DESCRIPTION>",
      "status": "<STATUS>"
    },
)

data = response.json()

$ch = curl_init("https://api.orshot.com/v1/workflows");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <ORSHOT_API_KEY>",
    "Content-Type: application/json",
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
  "steps" => [],
  "name" => "<NAME>",
  "description" => "<DESCRIPTION>",
  "status" => "<STATUS>"
]));

$data = json_decode(curl_exec($ch), true);
curl_close($ch);

require "net/http"
require "json"

uri = URI("https://api.orshot.com/v1/workflows")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer <ORSHOT_API_KEY>"
req["Content-Type"] = "application/json"
req.body = {
  "steps": [],
  "name": "<NAME>",
  "description": "<DESCRIPTION>",
  "status": "<STATUS>"
}.to_json

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

Enterprise Only

The Workflows API is available only to first party clients like the Orshot MCP server and workspaces on the Enterprise plan. Checkout the Enterprise Pricing to get access.

Overview#

Create a workflow from a steps array. This is the same contract the in-app builder uses, with identical validation and plan gating, so a workflow created here behaves exactly like one built in the dashboard.

A workflow is an ordered list of steps, each { key, type, config }. Use the node catalog (GET /v1/workflows/nodes) to discover every buildable node, its configSchema, and whether it is available on your plan. You can validate a steps array without writing anything via POST /v1/workflows/validate.

Endpoint

https://api.orshot.com/v1/workflows

Request Body#

Parameter	Type	Required	Description
`name`	String	No	Workflow name, up to 200 characters. Defaults to "Untitled workflow"
`description`	String	No	Optional description
`steps`	Array	Yes	Ordered steps, each `{ key, type, config }`. The first step must be a trigger or data source
`status`	String	No	`draft`, `active`, `paused` or `archived`. Defaults to `draft`
`metadata`	Object	No	Your own metadata. Server-managed keys (`health`, `poll`, `share`, `schema`) are ignored

Request#

JavaScript

await fetch("https://api.orshot.com/v1/workflows", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <ORSHOT_API_KEY>",
  },
  body: JSON.stringify({
    name: "Renders from new Drive files",
    status: "draft",
    steps: [
      {
        key: "google_drive_new_file",
        type: "trigger",
        config: { folderId: "<DRIVE_FOLDER_ID>", pollInterval: 10 },
      },
      {
        key: "render",
        type: "action",
        config: {
          templateId: "1443",
          format: "jpg",
          mapping: { headline: "name", hero_image: "image_url" },
        },
      },
      {
        key: "orshot_url",
        type: "destination",
        config: {},
      },
    ],
  }),
});

JSON

{
  "workflow": {
    "id": 91,
    "name": "Renders from new Drive files",
    "status": "draft",
    "trigger_type": "google_drive_new_file",
    "required_connections": ["google_drive"],
    "steps": [ ... ],
    "schedule_config": { "poll": true, "frequency": "custom", "intervalMinutes": 10 },
    "next_run_at": null,
    "created_at": "2026-07-11T10:00:00.000Z"
  },
  "warnings": []
}

Returns 201 Created. warnings lists anything that would block a run (for example a missing destination), so you can save a draft now and finish it later.

Activation Rules#

Creating with status: "active" enforces everything a run needs up front:

The steps must be complete and runnable (no warnings)
Steps gated to a higher plan tier block activation (they save fine as a draft)
Required provider connections must already be connected in the workspace
Your plan's active-workflow limit must not be exceeded

Error Responses#

Invalid Workflow (400)#

JSON

{
  "error": "Invalid workflow",
  "details": ["Step 2 (render): templateId is required"]
}

Not Runnable Yet (400)#

Returned when activating an incomplete workflow.

JSON

{
  "error": "Workflow is not runnable yet, finish it before activating",
  "details": ["no_destination"],
  "hints": ["Add a destination step so every render is delivered somewhere."]
}

Missing Connection (400)#

JSON

{
  "error": "Connect Google Drive before activating — this workflow needs it to run.",
  "code": "missing_connection"
}

Plan Gated Steps (403)#

JSON

{
  "error": "This workflow uses steps that need a higher plan",
  "code": "plan_gated",
  "details": ["..."],
  "hints": ["..."]
}

Rate Limits#

60 requests per minute per workspace

Was this page helpful?

Ready to automate?

Start rendering images, PDFs and videos from your templates in under 2 minutes. Free plan, no credit card.

Get your API key

Image, PDF and video generation via API
Visual editor with AI and smart layouts
Zapier, Make, MCP and 50+ integrations
White-label embed for your own app
30 free credits — no credit card required