> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowmaticai.in/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField body="name" type="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.
</ParamField>

<ParamField body="graph" type="object" required>
  The complete workflow graph, containing all nodes and the edges that connect them.

  <Expandable title="graph properties">
    <ParamField body="nodes" type="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`.

      <Expandable title="node object properties">
        <ParamField body="id" type="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}}`.
        </ParamField>

        <ParamField body="type" 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.
        </ParamField>

        <ParamField body="data" type="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`).
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="edges" type="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.

      <Expandable title="edge object properties">
        <ParamField body="source" type="string" required>
          The `id` of the node from which this edge originates.
        </ParamField>

        <ParamField body="target" type="string" required>
          The `id` of the node to which this edge points.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

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

<Tabs>
  <Tab title="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.

    ```bash theme={null}
    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:**

    ```json theme={null}
    {
      "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" }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="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.

    ```bash theme={null}
    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:**

    ```json theme={null}
    {
      "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" }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

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

<ResponseField name="id" type="string">
  The unique identifier assigned to your workflow by Flowmatic. Use this value as the `workflowId` path parameter in run, get, and delete requests.
</ResponseField>

<ResponseField name="name" type="string">
  The display name you provided in the request body.
</ResponseField>

<ResponseField name="graph" type="object">
  The full graph definition as saved, including all nodes and edges exactly as you submitted them.
</ResponseField>

<ResponseField name="createdAt" type="string">
  An ISO 8601 timestamp indicating when the workflow was created (e.g., `"2024-08-15T10:30:00.000Z"`).
</ResponseField>

### Example Response

```json theme={null}
{
  "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"
}
```