> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Getting started with Flowker
> Run Flowker locally, create your first workflow, execute it, and retrieve results — a hands-on quick start for developers using the orchestration engine.
**This guide is intended for developers.** If you're looking for a business-level overview of what Flowker does, see [What is Flowker?](/en/flowker/what-is-flowker).
Flowker is a workflow orchestration engine designed to help you model, execute, and scale business processes with precision.
In this guide, you will run Flowker locally and execute your first workflow—from creation to result retrieval. By the end, you will have a working environment to validate automation flows and integrate them into your systems.
## Prerequisites
***
Before you begin, make sure your environment is ready:
| Tool | Minimum version | Check command |
| -------------- | --------------- | ------------------------ |
| Go | 1.26.5+ | `go version` |
| Docker | 24+ | `docker --version` |
| Docker Compose | 2.20+ | `docker compose version` |
| Make | Installed | `make --version` |
Flowker runs locally using Docker for its database (MongoDB). No external infrastructure is needed for this guide.
## Step 1: Obtain Flowker and set up the project
***
Flowker is available to licensed customers; its repository is maintained internally. The steps below assume you already have access to the required Flowker project files.
From the Flowker project directory, prepare the development environment:
```bash theme={null}
cd flowker
```
Install development tools and create the environment file:
```bash theme={null}
make dev-setup
```
Then start the local stack (MongoDB + Flowker on port 4021):
```bash theme={null}
make dev
```
Once the output shows the server is running, Flowker is available at `http://localhost:4021`.
The `make dev` command starts MongoDB, generates API documentation, and runs the Flowker application with authentication disabled—so you can test freely during development.
## Step 2: Create your first workflow
***
Workflows define how your business process behaves—what steps run, in which order, and under which conditions. Each workflow is composed of **nodes** (the steps) and **edges** (the connections between them).
Create a workflow with a webhook trigger and a log action:
```bash theme={null}
curl -s -X POST http://localhost:4021/v1/workflows \
-H "Content-Type: application/json" \
-d '{
"name": "my-first-workflow",
"description": "A simple workflow with one trigger and one action.",
"nodes": [
{
"id": "trigger-1",
"type": "trigger",
"name": "Start",
"position": { "x": 0, "y": 0 },
"data": {
"triggerType": "webhook",
"path": "my-first-workflow",
"method": "POST",
"input_contract": "open",
"format": "json"
}
},
{
"id": "log-event",
"type": "action",
"name": "Log event",
"position": { "x": 200, "y": 0 },
"data": { "action": "log" }
}
],
"edges": [
{
"id": "e1",
"source": "trigger-1",
"target": "log-event"
}
]
}' | jq .
```
The response confirms the workflow was created in `draft` status:
```json theme={null}
{
"id": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"name": "my-first-workflow",
"status": "draft"
}
```
Save the `id` value — you will need it in the next steps.
New workflows are always created in `draft` status. A workflow must have at least one node.
In Flowker, **nodes** represent the individual steps of your workflow — what you might call tasks in business terms. **Edges** define the order in which those steps run.
## Step 3: Activate the workflow
***
A workflow must be activated before it can be executed. This transitions the workflow from `draft` to `active`.
```bash theme={null}
curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate \
-H "Content-Type: application/json" | jq .
```
Once activated, a workflow's structure is locked and cannot be edited directly. To make changes, clone it, modify the clone, and activate the new version.
## Step 4: Execute the workflow
***
Trigger a workflow execution by sending input data. The `Idempotency-Key` header is required to ensure safe retries.
```bash theme={null}
curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/executions \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7f3e1a2b-4c5d-6e7f-8a9b-0c1d2e3f4a5b" \
-d '{
"inputData": {
"message": "hello from my first workflow"
}
}' | jq .
```
The response confirms the execution has started:
```json theme={null}
{
"executionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
"workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"status": "running",
"startedAt": "2026-03-18T14:35:00Z"
}
```
Save the `executionId` for the next step.
The `Idempotency-Key` header is required. Use a unique UUID per request to prevent duplicate executions on retry.
## Step 5: Check execution results
***
Retrieve the outcome of a workflow execution:
```bash theme={null}
curl -s http://localhost:4021/v1/executions/019c96a0-10ce-75fc-a273-dc799079a99c/results | jq .
```
The response includes the status of each step and the final output:
```json theme={null}
{
"executionId": "019c96a0-10ce-75fc-a273-dc799079a99c",
"workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
"status": "completed",
"stepResults": [
{
"stepNumber": 1,
"stepName": "action_log-event",
"nodeId": "log-event",
"status": "completed",
"output": { "action": "log" },
"executedAt": "2026-03-18T14:35:00Z",
"durationMs": 12
}
],
"finalOutput": {
"workflow": {
"message": "hello from my first workflow"
}
},
"startedAt": "2026-03-18T14:35:00Z",
"completedAt": "2026-03-18T14:35:00Z"
}
```
If the execution is still running, this endpoint returns a `422` status. Poll `/v1/executions/{executionId}` to check the current status before requesting results.
## Explore the API locally
***
Flowker serves its OpenAPI 3.1 description and an interactive docs UI when `SWAGGER_ENABLED=true`. The sample environment file that `make dev-setup` copies into place sets it, so the surface is available on a local stack; anywhere the variable is unset the routes are not mounted and return `404`.
| Surface | URL |
| ---------------- | ------------------------------------------------------------------------ |
| Interactive docs | [http://localhost:4021/openapi/docs](http://localhost:4021/openapi/docs) |
| Spec (JSON) | `http://localhost:4021/openapi/openapi.json` |
| Spec (YAML) | `http://localhost:4021/openapi/openapi.yaml` |
Use the docs UI to:
* Inspect all available endpoints
* Test requests interactively
* Understand request and response structures
## A note on authentication
***
In the local development environment (`make dev`), authentication is disabled by default.
In staging, production, or any environment with Access Manager enabled (`PLUGIN_AUTH_ENABLED=true`), all `/v1/*` endpoints require a Bearer token in the `Authorization` header:
```bash theme={null}
curl -H "Authorization: Bearer " http://your-flowker-host/v1/workflows
```
## What's next
***
You now have a running Flowker environment and have executed your first workflow.
From here, you can:
* **Model real business processes** using different node types: `trigger`, `executor`, `conditional`, and `action`
* **Integrate external systems** via provider configurations (connect to KYC providers, fraud engines, payment services)
* **Design conditional flows** with conditional nodes that evaluate expressions on step outputs and route through the matching `sourceHandle` edge
* **Monitor executions** using the execution status and results endpoints
Flowker is designed to move from simple flows to production-grade orchestration without changing the core model.