Create a workflow node

curl --request POST \
  --url https://app.loops.so/api/v1/workflows/{workflowId}/nodes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedRevisionId": "<string>",
  "insertMode": "between",
  "fromNodeId": "<string>",
  "toNodeId": "<string>"
}
'

import requests

url = "https://app.loops.so/api/v1/workflows/{workflowId}/nodes"

payload = {
    "expectedRevisionId": "<string>",
    "insertMode": "between",
    "fromNodeId": "<string>",
    "toNodeId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    expectedRevisionId: '<string>',
    insertMode: 'between',
    fromNodeId: '<string>',
    toNodeId: '<string>'
  })
};

fetch('https://app.loops.so/api/v1/workflows/{workflowId}/nodes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.loops.so/api/v1/workflows/{workflowId}/nodes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expectedRevisionId' => '<string>',
    'insertMode' => 'between',
    'fromNodeId' => '<string>',
    'toNodeId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.loops.so/api/v1/workflows/{workflowId}/nodes"

	payload := strings.NewReader("{\n  \"expectedRevisionId\": \"<string>\",\n  \"insertMode\": \"between\",\n  \"fromNodeId\": \"<string>\",\n  \"toNodeId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.loops.so/api/v1/workflows/{workflowId}/nodes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expectedRevisionId\": \"<string>\",\n  \"insertMode\": \"between\",\n  \"fromNodeId\": \"<string>\",\n  \"toNodeId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.loops.so/api/v1/workflows/{workflowId}/nodes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expectedRevisionId\": \"<string>\",\n  \"insertMode\": \"between\",\n  \"fromNodeId\": \"<string>\",\n  \"toNodeId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "node": {
    "id": "<string>",
    "typeName": "SignupTrigger",
    "nextNodeIds": [
      "<string>"
    ],
    "workflowRevisionId": "<string>",
    "createdChildNodes": [
      {
        "id": "<string>",
        "typeName": "SignupTrigger",
        "nextNodeIds": [
          "<string>"
        ]
      }
    ]
  },
  "workflow": {
    "id": "<string>",
    "workflowRevisionId": "<string>",
    "mailingListId": "<string>",
    "rootNodeId": "<string>",
    "nodes": {
      "cf16k73gq014h3mmj5b6jdi9r": {
        "typeName": "SignupTrigger",
        "nextNodeIds": [
          "cf16k73gq014h3mmj5b4jdifg",
          "cf16k73gq014h3mmj5b4jdifh"
        ]
      }
    },
    "name": "<string>",
    "description": "<string>"
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

POST

workflows

{workflowId}

nodes

Create a workflow node

curl --request POST \
  --url https://app.loops.so/api/v1/workflows/{workflowId}/nodes \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedRevisionId": "<string>",
  "insertMode": "between",
  "fromNodeId": "<string>",
  "toNodeId": "<string>"
}
'

import requests

url = "https://app.loops.so/api/v1/workflows/{workflowId}/nodes"

payload = {
    "expectedRevisionId": "<string>",
    "insertMode": "between",
    "fromNodeId": "<string>",
    "toNodeId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    expectedRevisionId: '<string>',
    insertMode: 'between',
    fromNodeId: '<string>',
    toNodeId: '<string>'
  })
};

fetch('https://app.loops.so/api/v1/workflows/{workflowId}/nodes', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.loops.so/api/v1/workflows/{workflowId}/nodes",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'expectedRevisionId' => '<string>',
    'insertMode' => 'between',
    'fromNodeId' => '<string>',
    'toNodeId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.loops.so/api/v1/workflows/{workflowId}/nodes"

	payload := strings.NewReader("{\n  \"expectedRevisionId\": \"<string>\",\n  \"insertMode\": \"between\",\n  \"fromNodeId\": \"<string>\",\n  \"toNodeId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.loops.so/api/v1/workflows/{workflowId}/nodes")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"expectedRevisionId\": \"<string>\",\n  \"insertMode\": \"between\",\n  \"fromNodeId\": \"<string>\",\n  \"toNodeId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.loops.so/api/v1/workflows/{workflowId}/nodes")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"expectedRevisionId\": \"<string>\",\n  \"insertMode\": \"between\",\n  \"fromNodeId\": \"<string>\",\n  \"toNodeId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "node": {
    "id": "<string>",
    "typeName": "SignupTrigger",
    "nextNodeIds": [
      "<string>"
    ],
    "workflowRevisionId": "<string>",
    "createdChildNodes": [
      {
        "id": "<string>",
        "typeName": "SignupTrigger",
        "nextNodeIds": [
          "<string>"
        ]
      }
    ]
  },
  "workflow": {
    "id": "<string>",
    "workflowRevisionId": "<string>",
    "mailingListId": "<string>",
    "rootNodeId": "<string>",
    "nodes": {
      "cf16k73gq014h3mmj5b6jdi9r": {
        "typeName": "SignupTrigger",
        "nextNodeIds": [
          "cf16k73gq014h3mmj5b4jdifg",
          "cf16k73gq014h3mmj5b4jdifh"
        ]
      }
    },
    "name": "<string>",
    "description": "<string>"
  }
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

{
  "message": "<string>"
}

Choose where the node goes with insertMode:

between places it between an existing fromNodeId -> toNodeId connection
before places it before beforeNodeId.

New nodes start with default settings; update the node after creation to configure it. Branch nodes create their default paths too: BranchNode creates two AudienceFilter children, and ExperimentBranchNode creates two regular VariantNode children plus one control VariantNode. Public workflows can have up to 300 nodes. Generated children count toward that limit, so a normal create adds 1 node, BranchNode adds 3, and ExperimentBranchNode adds 4. To add a sibling child path to a branch or experiment branch, use the POST /v1/workflows/{workflowId}/nodes/{nodeId}/add-branch endpoint. Branch paths can be edited with create-node, but a workflow cannot be started unless each direct BranchNode child is an AudienceFilter. For experiments, use create-node only to insert a missing VariantNode before non-variant content; use add-branch for another variant path.

Authorizations

Authorization

string

header

required

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

Path Parameters

workflowId

string

required

The ID of the workflow.

Body

application/json

Option 1
Option 2

Create a new workflow node with an explicit insertMode. To configure the node after creation, use the POST /v1/workflows/{workflowId}/nodes/{nodeId} endpoint.

expectedRevisionId

string | null

required

The workflow revision token returned by the latest workflow read or mutation. Older workflows may return null before their first revision-aware mutation; pass null back as expectedRevisionId in that case. If the token is stale, the API returns a 409 Conflict error.

insertMode

enum<string>

required

Available options:

between

nodeTypeName

enum<string>

required

Node types that can be created with the API. *Trigger nodes and ExitAction nodes cannot be created.

Available options:

AudienceFilter,

BranchNode,

ExperimentBranchNode,

TimerAction,

SendEmailAction,

VariantNode

fromNodeId

string

required

The node to insert after. This node must currently point to toNodeId. If this is an ExperimentBranchNode, nodeTypeName must be VariantNode and toNodeId cannot already be a VariantNode.

toNodeId

string

required

The node to insert before.

Response

Workflow node created.

node

object

required

Detailed workflow node returned from a mutation, plus the latest workflow revision token.

Show child attributes

workflow

object

required

Show child attributes

Example:

{
  "id": "clw1a3b5c7d9e1f3g5h7i9j1",
  "status": "Draft",
  "name": "Welcome series",
  "description": "Onboarding emails for new signups",
  "mailingListId": "clm2k8j4h6g0f8d6s4a2b0z8",
  "rootNodeId": "cln8p0q2r4s6t8u0v2w4x6z8",
  "nodes": {
    "cln8p0q2r4s6t8u0v2w4x6z8": {
      "typeName": "SignupTrigger",
      "nextNodeIds": ["cln1a3b5c7d9e1f3g5h7i9j1"]
    },
    "cln1a3b5c7d9e1f3g5h7i9j1": {
      "typeName": "SendEmailAction",
      "nextNodeIds": [],
      "emailMessageId": "cle5f7g9h1i3j5k7l9m1n3p5",
      "subject": "Welcome to Acme!"
    }
  }
}

Last modified on August 4, 2026

Learn

API

CLI

Guides

Create a workflow node

Authorizations

Path Parameters

Body

Response