> ## 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.
# What is Flowmatic? Graph-Based Workflow Automation
> Flowmatic is a REST API for building graph-based automation pipelines. Define nodes, upload CSV data, and trigger email campaigns powered by AI or filters.
Flowmatic is a REST API that lets you build, run, and monitor automation pipelines modelled as directed node graphs. Instead of writing brittle point-to-point scripts, you describe your workflow as a set of typed nodes and the edges that connect them — Flowmatic handles execution order, data passing between nodes, and delivery of the final output. Whether you need to blast a targeted email campaign to a filtered slice of your audience or chain together AI-powered transformations before sending, Flowmatic gives you a composable, API-first way to do it.
## How Flowmatic Works
Every automation in Flowmatic follows the same four-step lifecycle: upload your data, define a graph, start a run, and wait for the result.
1. **Upload a CSV** — Push your audience or dataset to Flowmatic via `POST /api/uploads`. Flowmatic stores the file and returns an `uploadId` you reference in your graph.
2. **Build a node graph** — Describe the workflow as a JSON object containing `nodes` and `edges`. Each node has a `type`, an `id`, and a `data` payload appropriate to that type.
3. **Trigger a run** — Call `POST /api/workflows/:workflowId/run`. Flowmatic schedules the run asynchronously and returns a `runId` immediately with HTTP 202.
4. **Emails get sent** — Flowmatic walks the graph, evaluating filters or AI steps, and hands off each output to its built-in email delivery layer.
Runs are always asynchronous. Flowmatic returns a `runId` at submission time so your application never blocks on execution. Poll `GET /api/workflows/runs/:runId` or set up a webhook to know when a run finishes.
## Node Types
Flowmatic workflows are built from five primitive node types. Combine them in any order that makes sense for your use case — the only rule is that every graph must begin with a `TRIGGER` node and end with at least one `OUTPUT` node.
The entry point of every workflow. A `TRIGGER` node has no inputs and carries no data of its own — it simply signals that execution should begin. Every graph must contain exactly one `TRIGGER` node.
Attaches an uploaded CSV to the graph. Set `data.uploadId` to the ID returned by `POST /api/uploads`. Downstream nodes receive the parsed rows as `{{ds.rows}}`, where `ds` is the node's `id`.
Passes each row (or any upstream value) through a large-language-model prompt. Configure the model, system prompt, and per-row user message in the `data` payload. Requires an AI API key configured in your account settings.
Evaluates a boolean expression against every item in an upstream array and emits only the items for which the expression is truthy. Reference the incoming array with `data.source` and write a plain expression in `data.expr` (e.g. `rating > 4`).
Sends an email for each item produced by an upstream node. Use `data.forEach` to reference the array, then template `data.to`, `data.subject`, and `data.body` with `{{item.*}}` placeholders. Flowmatic renders each template per item before dispatching.
## Node Data Flow
Nodes communicate through a lightweight template syntax. When a node produces output, Flowmatic registers it under the node's `id`. Any downstream node can reference that output using double-brace notation:
| Expression | Meaning |
| ---------------- | ----------------------------------------------------------------------- |
| `{{ds.rows}}` | All rows emitted by the `DATA_SOURCE` node whose `id` is `ds` |
| `{{f.items}}` | The filtered array emitted by the `FILTER` node whose `id` is `f` |
| `{{item.email}}` | The `email` field of the current iteration item inside an `OUTPUT` node |
| `{{ai.result}}` | The text generated by the `AI` node whose `id` is `ai` |
Template expressions are evaluated lazily at runtime. If a node referenced in a template has not yet executed (or failed), Flowmatic will surface a clear error in the run log rather than sending malformed emails.
## Async Run Lifecycle
When you trigger a workflow, the run passes through the following states:
```
PENDING → RUNNING → SUCCESS
↘ FAILED
```
| State | Meaning |
| --------- | -------------------------------------------------------------------------------- |
| `PENDING` | The run has been accepted and is waiting for an available worker. |
| `RUNNING` | A worker has picked up the run and is executing the graph. |
| `SUCCESS` | All nodes completed without error. Check `result` for delivery statistics. |
| `FAILED` | One or more nodes encountered an unrecoverable error. Check `error` for details. |
Poll `GET /api/workflows/runs/:runId` until the status is `SUCCESS` or `FAILED`. A typical simple workflow completes within a few seconds; AI-heavy workflows may take longer depending on model response times.
## Google Drive Integration
Flowmatic can pull CSV data directly from Google Drive, so you never have to manually export and re-upload files. Connect your Google account in the dashboard under **Integrations → Google Drive**, then use the Drive file picker in the `DATA_SOURCE` node instead of an `uploadId`. The integration uses OAuth 2.0 — Flowmatic never stores your Google credentials.
Google Drive–sourced data is fetched fresh at run time, meaning every workflow run reflects the latest version of the spreadsheet without any manual intervention.
## What's Next
Ready to build your first workflow? The quickstart walks you through every step — from registering an account to monitoring a live run — in under 10 minutes.
Go from zero to a running workflow in 7 steps.
Learn how to register, verify your email, and authenticate API requests.