> ## 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/uploads — Upload a CSV File to Flowmatic

> POST /api/uploads — Upload a CSV file to Flowmatic and receive an uploadId to reference in DATA_SOURCE nodes within your workflow graphs.

The upload endpoint lets you bring your own data into Flowmatic by submitting a CSV file. Once uploaded, Flowmatic parses the file, registers it under a unique `uploadId`, and makes each row available as structured data inside your workflow graphs. You reference the `uploadId` in a `DATA_SOURCE` node, and every column header in your CSV becomes a named template variable that downstream nodes — such as `AI`, `FILTER`, and `OUTPUT` — can access directly.

## Endpoint

```
POST https://api.flowmatic.io/api/uploads
```

**Content-Type:** `multipart/form-data`\
**Authentication:** `Authorization: Bearer <accessToken>` header required.

## Request

<ParamField body="file" type="file" required>
  The CSV file you want to upload. The first row must contain column headers — these headers become the template variable names you use in downstream nodes (e.g., `{{item.email}}`, `{{item.name}}`). The file must be a valid `.csv` with UTF-8 encoding.
</ParamField>

<Tip>
  CSV column headers become template variable names throughout your workflow. For example, a column named `email` becomes `{{item.email}}` inside an `OUTPUT` node's `to` field, and a column named `rating` becomes `{{item.rating}}` inside a `FILTER` expression. Keep your headers concise and free of spaces or special characters for the cleanest template syntax.
</Tip>

### Example CSV Format

Your CSV file should include a header row followed by data rows. Here is a representative example:

```csv theme={null}
name,email,rating
Alice Johnson,alice@example.com,5
Bob Smith,bob@example.com,3
```

## Example Request

```bash theme={null}
curl -X POST https://api.flowmatic.io/api/uploads \
  -H "Authorization: Bearer <accessToken>" \
  -F "file=@customers.csv"
```

## Response

A successful upload returns HTTP `200 OK` with a JSON body containing the `uploadId` for your file.

<ResponseField name="uploadId" type="string">
  A unique identifier for the uploaded file. Store this value and use it as the `uploadId` property in any `DATA_SOURCE` node that should read from this file. The `uploadId` remains valid for as long as the file exists in your account.
</ResponseField>

### Example Response

```json theme={null}
{ "uploadId": "upload_abc123xyz" }
```

## Using the uploadId in a Workflow

After you receive an `uploadId`, you reference it inside a `DATA_SOURCE` node in your workflow graph. The node makes all rows from the uploaded file available to subsequent nodes via the `{{ds.rows}}` template expression (where `ds` is the node's `id`).

```json theme={null}
{ "id": "ds", "type": "DATA_SOURCE", "data": { "uploadId": "upload_abc123xyz" } }
```

Once a `DATA_SOURCE` node is wired into your graph, you can pass `{{ds.rows}}` to a `FILTER` node's `source` field, an `AI` node's `prompt`, or any other field that accepts template expressions.