Skip to main content
POST
/
api
/
workflows
Create a new workflow
curl --request POST \
  --url https://your-instance.example.com/api/workflows \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "New Lead Welcome",
  "description": "Greet new leads and assign them to a leasing agent.",
  "nodes": [
    {
      "id": "n1",
      "type": "trigger",
      "position": {
        "x": 50,
        "y": 50
      },
      "data": {
        "event": "application.created"
      }
    },
    {
      "id": "n2",
      "type": "sendMessage",
      "position": {
        "x": 250,
        "y": 50
      },
      "data": {
        "template": "welcome-sms"
      }
    }
  ],
  "edges": [
    {
      "id": "e1",
      "source": "n1",
      "target": "n2"
    }
  ],
  "viewport": {
    "x": 0,
    "y": 0,
    "zoom": 1
  },
  "enabled": true
}
'
{
  "success": true,
  "message": "Workflow created successfully",
  "data": {
    "_id": "64d2f9c5e8a1d4e001a0b1c2",
    "name": "New Lead Welcome",
    "description": "Greet new leads and assign them to a leasing agent.",
    "organizationId": "64a1b2c3d4e5f60012345678",
    "userId": "64a1b2c3d4e5f60012345679",
    "nodes": [],
    "edges": [],
    "viewport": {
      "x": 0,
      "y": 0,
      "zoom": 1
    },
    "enabled": false,
    "createdAt": "2026-04-12T14:22:10.000Z",
    "updatedAt": "2026-04-12T14:22:10.000Z"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Human-readable workflow name. Must be unique within the caller organization.

​
description
string

Free-text description shown in the workflows list and builder header.

​
nodes
object[]

Visual builder nodes — each carries id, type, position, and node-specific data.

​
edges
object[]

Directed connections between nodes (source → target ids) defining execution flow.

​
viewport
object

Camera state for the canvas (x, y, zoom). Defaults to { x: 0, y: 0, zoom: 1 } when omitted.

​
enabled
boolean

When false, the trigger system skips this workflow even when conditions match. Defaults to false on create.

Response

Workflow created successfully

Returned by create/update/toggle. Wraps the resulting WorkflowDocument plus a status message.

​
success
enum<boolean>
required
Available options:
true
​
message
string
required
​
data
object
required

A Workflow document — visual builder canvas (nodes + edges) plus enabled flag and metadata.

Example:
{
  "_id": "64d2f9c5e8a1d4e001a0b1c2",
  "name": "New Lead Welcome",
  "description": "Greet new leads and assign them to a leasing agent.",
  "organizationId": "64a1b2c3d4e5f60012345678",
  "userId": "64a1b2c3d4e5f60012345679",
  "nodes": [
    {
      "id": "n1",
      "type": "trigger",
      "position": { "x": 50, "y": 50 },
      "data": { "event": "application.created" }
    },
    {
      "id": "n2",
      "type": "sendMessage",
      "position": { "x": 250, "y": 50 },
      "data": { "template": "welcome-sms" }
    }
  ],
  "edges": [
    {
      "id": "e1",
      "source": "n1",
      "target": "n2"
    }
  ],
  "viewport": { "x": 0, "y": 0, "zoom": 1 },
  "enabled": true,
  "createdAt": "2026-04-12T14:22:10.000Z",
  "updatedAt": "2026-04-22T10:14:00.000Z"
}