POST /api/workflows — Create a Flowmatic Workflow

POST /api/workflows — Define and save a workflow graph with nodes and edges. Supports TRIGGER, DATA_SOURCE, AI, FILTER, and OUTPUT node types.

Creating a workflow in Flowmatic means describing a directed graph of nodes connected by edges. Each node represents a discrete step — triggering the run, loading data, applying a filter, generating AI output, or delivering a result — and edges define the order in which those steps execute. You send the full graph definition in a single request, and Flowmatic validates, saves, and returns the workflow with a unique ID you can use to run or manage it later.

Endpoint

POST https://api.flowmatic.io/api/workflows

Content-Type: application/json
Authentication: Authorization: Bearer <accessToken> header required.

Request Body

name · string · required

A human-readable display name for the workflow. This name appears in the dashboard and in list/get responses to help you identify the workflow at a glance.

graph · object · required

The complete workflow graph, containing all nodes and the edges that connect them.

Show graph properties

nodes · array · required

An ordered array of node objects. Each node represents one step in the workflow. Every node must have a unique id within the graph. Supported node types are TRIGGER, DATA_SOURCE, AI, FILTER, and OUTPUT.

Show node object properties

id · string · required

A short, unique identifier for this node within the graph (e.g., "t", "ds", "ai"). You reference this ID in edge definitions and in template expressions — for example, a node with id: "ds" exposes its output as {{ds.rows}}.

type · string · required

The node type. Must be one of:

• TRIGGER — marks the entry point of the workflow; every graph must include exactly one.
• DATA_SOURCE — loads rows from a previously uploaded CSV file.
• AI — sends a prompt to an LLM and captures structured output fields.
• FILTER — filters an array of items using a boolean expression.
• OUTPUT — iterates over a collection and sends a message for each item.

data · object · required

Configuration specific to the node type. Pass an empty object ({}) for TRIGGER nodes. For all other node types, supply the required fields for that type (e.g., uploadId for DATA_SOURCE, prompt and output for AI, source and expr for FILTER, and forEach/to/subject/body for OUTPUT).

edges · array · required

An array of edge objects that define the directed connections between nodes. Edges determine execution order — Flowmatic runs nodes in topological order based on this list.

Show edge object properties

source · string · required

The id of the node from which this edge originates.

target · string · required

The id of the node to which this edge points.

Example Requests

The two examples below show the most common workflow patterns. The first uses a FILTER node for pure logic-based row selection. The second delegates selection and message composition to an AI node.

FILTER Workflow

This workflow loads a customer list, keeps only rows where rating is greater than 4, and sends a thank-you email to each qualifying customer — no LLM call required.

curl -X POST https://api.flowmatic.io/api/workflows \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email 5-star raters",
    "graph": {
      "nodes": [
        { "id": "t",   "type": "TRIGGER",     "data": {} },
        { "id": "ds",  "type": "DATA_SOURCE",  "data": { "uploadId": "upload_abc123" } },
        { "id": "f",   "type": "FILTER",       "data": { "source": "{{ds.rows}}", "expr": "rating > 4" } },
        { "id": "out", "type": "OUTPUT", "data": {
            "forEach": "{{f.items}}",
            "to":      "{{item.email}}",
            "subject": "Thanks {{item.name}}",
            "body":    "Hi {{item.name}}, thanks for the 5-star review!"
        }}
      ],
      "edges": [
        { "source": "t",  "target": "ds" },
        { "source": "ds", "target": "f" },
        { "source": "f",  "target": "out" }
      ]
    }
  }'

Full request body:

{
  "name": "Email 5-star raters",
  "graph": {
    "nodes": [
      { "id": "t",   "type": "TRIGGER",     "data": {} },
      { "id": "ds",  "type": "DATA_SOURCE",  "data": { "uploadId": "upload_abc123" } },
      { "id": "f",   "type": "FILTER",       "data": { "source": "{{ds.rows}}", "expr": "rating > 4" } },
      { "id": "out", "type": "OUTPUT", "data": {
          "forEach": "{{f.items}}",
          "to":      "{{item.email}}",
          "subject": "Thanks {{item.name}}",
          "body":    "Hi {{item.name}}, thanks for the 5-star review!"
      }}
    ],
    "edges": [
      { "source": "t",  "target": "ds" },
      { "source": "ds", "target": "f" },
      { "source": "f",  "target": "out" }
    ]
  }
}

AI Workflow

This workflow passes the full customer list to an LLM, which selects high-rated customers and generates a personalised message body. The OUTPUT node then sends that message to each selected customer.

curl -X POST https://api.flowmatic.io/api/workflows \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Reward top raters",
    "graph": {
      "nodes": [
        { "id": "t",   "type": "TRIGGER",     "data": {} },
        { "id": "ds",  "type": "DATA_SOURCE",  "data": { "uploadId": "upload_abc123" } },
        { "id": "ai",  "type": "AI", "data": {
            "prompt": "From these customers pick those who rated above 4 stars. Rows: {{ds.rows}}",
            "output": [
              { "name": "customers",   "type": "array"  },
              { "name": "messageBody", "type": "string" }
            ]
        }},
        { "id": "out", "type": "OUTPUT", "data": {
            "forEach": "{{ai.customers}}",
            "to":      "{{item.email}}",
            "subject": "Thanks {{item.name}}",
            "body":    "Hi {{item.name}}, {{ai.messageBody}}"
        }}
      ],
      "edges": [
        { "source": "t",  "target": "ds" },
        { "source": "ds", "target": "ai" },
        { "source": "ai", "target": "out" }
      ]
    }
  }'

Full request body:

{
  "name": "Reward top raters",
  "graph": {
    "nodes": [
      { "id": "t",   "type": "TRIGGER",     "data": {} },
      { "id": "ds",  "type": "DATA_SOURCE",  "data": { "uploadId": "upload_abc123" } },
      { "id": "ai",  "type": "AI", "data": {
          "prompt": "From these customers pick those who rated above 4 stars. Rows: {{ds.rows}}",
          "output": [
            { "name": "customers",   "type": "array"  },
            { "name": "messageBody", "type": "string" }
          ]
      }},
      { "id": "out", "type": "OUTPUT", "data": {
          "forEach": "{{ai.customers}}",
          "to":      "{{item.email}}",
          "subject": "Thanks {{item.name}}",
          "body":    "Hi {{item.name}}, {{ai.messageBody}}"
      }}
    ],
    "edges": [
      { "source": "t",  "target": "ds" },
      { "source": "ds", "target": "ai" },
      { "source": "ai", "target": "out" }
    ]
  }
}

Response

A successful request returns HTTP 201 Created with a JSON body representing the saved workflow. Record the id field — you will use it as workflowId when running, updating, or deleting the workflow.

id · string

The unique identifier assigned to your workflow by Flowmatic. Use this value as the workflowId path parameter in run, get, and delete requests.

name · string

The display name you provided in the request body.

graph · object

The full graph definition as saved, including all nodes and edges exactly as you submitted them.

createdAt · string

An ISO 8601 timestamp indicating when the workflow was created (e.g., "2024-08-15T10:30:00.000Z").

Example Response

{
  "id": "wf_7kQmR9pL2x",
  "name": "Email 5-star raters",
  "graph": {
    "nodes": [
      { "id": "t",   "type": "TRIGGER",     "data": {} },
      { "id": "ds",  "type": "DATA_SOURCE",  "data": { "uploadId": "upload_abc123" } },
      { "id": "f",   "type": "FILTER",       "data": { "source": "{{ds.rows}}", "expr": "rating > 4" } },
      { "id": "out", "type": "OUTPUT", "data": {
          "forEach": "{{f.items}}",
          "to":      "{{item.email}}",
          "subject": "Thanks {{item.name}}",
          "body":    "Hi {{item.name}}, thanks for the 5-star review!"
      }}
    ],
    "edges": [
      { "source": "t",  "target": "ds" },
      { "source": "ds", "target": "f" },
      { "source": "f",  "target": "out" }
    ]
  },
  "createdAt": "2024-08-15T10:30:00.000Z"
}