# 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.

![HTTP and Transform block](/images/http-transform-block.png)

## Prerequisites
[Section titled “Prerequisites”](#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
[Section titled “Step 1: Access Your Project”](#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
[Section titled “Step 2: Create a New Flow”](#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
[Section titled “Step 3: Understand the Interface”](#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
[Section titled “Step 4: Add Blocks”](#step-4-add-blocks)
Create two blocks:

**HTTP Endpoint Block:**

 1. From Core Blocks, click “HTTP Endpoint”
 1. Place it on the canvas
 1. This receives incoming HTTP requests

**Transform Block:**

 1. Add a “Transform” block from Core Blocks
 1. Place it below the HTTP Endpoint
 1. This processes the incoming data

## Step 5: Connect the Blocks
[Section titled “Step 5: Connect the Blocks”](#step-5-connect-the-blocks)
 1. Drag from the HTTP Endpoint’s output socket (bottom)
 1. Drop onto the Transform block’s input socket (top)
 1. You’ll see a line showing the connection

## Step 6: Configure the Blocks
[Section titled “Step 6: Configure the Blocks”](#step-6-configure-the-blocks)
**HTTP Endpoint Configuration:**

 1. Select the block to see settings in the right sidebar
 1. Name it “Text Transform API”
 1. Set these values:
 - **Name**: “Text Transform API”
 - **Path**: `/transform`
 - **Methods**: `POST`
 - **Audience**: Choose based on your needs

**Transform Block Configuration:**

 1. Select the Transform block
 1. Name it “Text Transformer”
 1. 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

![Transform Config](/images/transform-config.png)

**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
 1. Configure the HTTP Endpoint response:
 - **Header Expressions**: Add `Content-Type` with value `'application/json'`
 - **Response Body**: `outputs.textTransformer`

![HTTP Config](/images/http-config.png)

## Step 7: Test Your Flow
[Section titled “Step 7: Test Your Flow”](#step-7-test-your-flow)
 1. Save the flow
 1. Copy the webhook URL from the HTTP Endpoint block
 1. Test with curl:


*Terminal window*

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

![Testing with curl](/images/testing-with-curl.png)

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}
```

![HTTP Response Event](/images/http-response-event.png)

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

## What You Built
[Section titled “What You Built”](#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
[Section titled “Next Steps”](#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