Quick Start

This guide walks you through building your first flow - a text transformation API that receives text via HTTP and returns it in uppercase.

Prerequisites

You need access to a Spacelift Flows organization. Organization admins can invite users. If you're the org admin, you can create flows immediately.

Step 1: Access Your Project

Go to the Projects view and select your Personal Sandbox project. Every user gets a sandbox for testing flows.

Step 2: Create a New Flow

Click '+ New flow' in the top right corner. Give your flow a descriptive name like "Text Transform API".

Step 3: Understand the Interface

You're now in the flow editor:

• Left sidebar: Block types you can add (Core blocks and App blocks)
• Right sidebar: Configuration for selected blocks
• Center canvas: Where you place and connect blocks

Step 4: Add Blocks

Create two blocks:

HTTP Endpoint Block:

1. From Core Blocks, click "HTTP Endpoint"
2. Place it on the canvas
3. This receives incoming HTTP requests

Transform Block:

1. Add a "Transform" block from Core Blocks
2. Place it below the HTTP Endpoint
3. This processes the incoming data

Step 5: Connect the Blocks

1. Drag from the HTTP Endpoint's output socket (bottom)
2. Drop onto the Transform block's input socket (top)
3. You'll see a line showing the connection

Step 6: Configure the Blocks

HTTP Endpoint Configuration:

1. Select the block to see settings in the right sidebar
2. Name it "Text Transform API"
3. Set these values:
4. Name: "Text Transform API"
5. Path: /transform
6. Methods: POST
7. Audience: Choose based on your needs

Transform Block Configuration:

1. Select the Transform block
2. Name it "Text Transformer"
3. In the Output field, enter:

{
  original: outputs.textTransformApi.body?.text || "No text provided",
  transformed: (outputs.textTransformApi.body?.text || "No text provided").toUpperCase(),
  timestamp: new Date().toISOString(),
  requestId: outputs.textTransformApi.requestId
}

This expression creates a JSON object that:

• original: Captures the input text from the HTTP request body (or defaults to "No text provided" if missing)
• transformed: Takes the same input text and converts it to uppercase
• timestamp: Adds the current date and time in ISO format
• requestId: Includes the request ID from the original HTTP request for tracking

Connect the Response: For the API to respond properly, you need to connect the Transform block's output back to the HTTP Endpoint's input:

1. Drag from Transform block's output back to HTTP Endpoint's input
2. Configure the HTTP Endpoint response:
3. Header Expressions: Add Content-Type with value 'application/json'
4. Response Body: outputs.textTransformer

Step 7: Test Your Flow

1. Save the flow
2. Copy the webhook URL from the HTTP Endpoint block
3. Test with curl:

curl -X POST [your-webhook-url] \
  -H "Content-Type: application/json" \
  -d '{"text": "hello world"}'

Expected response:

{
  "body": {
    "original": "hello world",
    "requestId": "0198ea47-3f09-759c-bfad-6b60970c5f93",
    "timestamp": "2025-08-27T06:46:34.551Z",
    "transformed": "HELLO WORLD"
  },
  "headers": {
    "Content-Type": "'application/json'"
  },
  "statusCode": 200
}

If you need help, click the AI assistant icon in the bottom left of the canvas.

What You Built

Your flow:

• Accepts POST requests with JSON containing a "text" field
• Transforms text to uppercase
• Returns structured response with original text, transformed text, timestamp, and request ID
• Handles missing text with a default message

This demonstrates core Flows concepts:

• Event flow: HTTP requests create events that flow through blocks
• Data accumulation: Each block adds its own output, without discarding the others (textTransformApi → textTransformer)
• JavaScript expressions: Dynamic configuration using outputs variable

Next Steps

Continue with:

• Block Management: Learn how to create, connect, and configure blocks effectively
• Using Event Data: Master JavaScript expressions and data manipulation in your flows
• Core Blocks: Explore HTTP, Time, Business Logic, and Collections blocks for common automation tasks
• Installing Apps: Connect external services like Slack, AWS, or GitHub to your flows
• Flow Organization: Understand projects, permissions, and managing multiple automations