POST /api/workflows — Create a Flowmatic Workflow

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

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.

object

required

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

Show graph properties

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

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}}.

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.

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).

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

string

required

The id of the node from which this edge originates.

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
AI 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" }
    ]
  }
}

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.

string

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

string

The display name you provided in the request body.

object

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

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"
}

Authentication

Uploads

Workflows

Runs

POST /api/workflows — Create a Flowmatic Workflow

Endpoint

Request Body

Example Requests

Response

Example Response

​Endpoint

​Request Body

​Example Requests

​Response

​Example Response

Endpoint

Request Body

Example Requests

Response

Example Response