Skip to content
flow8

Developer Quick Start

Developer Quick Start

1. Start flow8

The fastest way to get a local instance running:

Terminal window
# Create a .env file with minimum required values
cat > .env << 'ENVEOF'
SERVER_PORT=4454
MONGODB_URI=mongodb://mongo:27017
MONGODB_DB=ud
API_URL=http://localhost:4454/api/
ENV_KEY_SALT=$(openssl rand -hex 32)
ENC_KEY_SECRET=$(openssl rand -hex 128)
ENVEOF


# Start with Docker Compose
curl -O https://raw.githubusercontent.com/your-org/flow8/main/docker-compose.yml
docker-compose up -d

Wait ~10 seconds, then verify:

Terminal window
curl http://localhost:4454/api/health
# {"status":"ok"}

2. Authenticate

Create a session and get your auth cookie:

Terminal window
curl -c cookies.txt -X POST http://localhost:4454/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"your-password"}'

Or create an API key for programmatic access:

Terminal window
# First login to get session cookie
curl -c cookies.txt -b cookies.txt -X POST http://localhost:4454/api/auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name":"my-integration-key"}'


# Response: {"id":"...","token":"eyJ..."}
# Use token as: Authorization: Bearer eyJ...

3. Create a Flow

Terminal window
curl -b cookies.txt -X POST http://localhost:4454/api/flows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hello World Flow",
    "enabled": true,
    "category": "Demo"
  }'
# Response: {"id":"65abc123",...}

4. Add a Module Step

Add a step that fetches a URL and extracts data:

Terminal window
FLOW_ID="65abc123"


# Add a cURL module step
curl -b cookies.txt -X POST http://localhost:4454/api/flows/$FLOW_ID/layers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fetch API",
    "ref": "fetchApi",
    "appId": "curl",
    "index": 0,
    "args": {
      "method": "GET",
      "url": "https://httpbin.org/json",
      "headers": {}
    }
  }'


# Add a template step that uses the output
curl -b cookies.txt -X POST http://localhost:4454/api/flows/$FLOW_ID/layers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Format Result",
    "ref": "formatResult",
    "appId": "template",
    "index": 1,
    "args": {
      "template": "Got response: {{ .fetchApi.body }}"
    }
  }'

5. Run the Flow

Terminal window
curl -b cookies.txt -X POST http://localhost:4454/api/flows/$FLOW_ID/run \
  -H "Content-Type: application/json" \
  -d '{}'
# Response: {"playId":"65xyz789","state":"RUN"}

6. Get Execution Results

Terminal window
PLAY_ID="65xyz789"


# Poll until done
curl -b cookies.txt http://localhost:4454/api/plays/$PLAY_ID


# Get step-by-step output
curl -b cookies.txt http://localhost:4454/api/plays/$PLAY_ID/layers

The out field of each layer contains that module’s output, available to subsequent steps via expressions like {{ $prev.fetchApi.body }}.