Skip to content
Spacelift Flows

Flow Definition Reference

This page documents the YAML schema for Flow definitions used with the Flows TF Provider.

Flow

Section titled “Flow”

The root object for a flow definition.

Syntax

Section titled “Syntax”
appInstallations:
  Key: AppInstallation
blocks:
  - Block
notes:
  - Note

Properties

Section titled “Properties”

appInstallations

Section titled “appInstallations”

Type: Map of String to AppInstallation

App installations used by blocks in this flow. Keys are references used by app blocks.

blocks

Section titled “blocks”

Type: Array of Block

List of blocks in the flow.

notes

Section titled “notes”

Type: Array of Note

Sticky notes on the canvas.

Block

Section titled “Block”

A block in the flow.

Syntax

Section titled “Syntax”
name: String
description: String
alternativeLookupStrategy: BlockLookupStrategy
type: BlockType
position: Position
config: BlockConfig
inputs: BlockInputs
outputs: BlockOutputs
errorHandler: String
group: String

Properties

Section titled “Properties”

name

Section titled “name”

Type: String

The name of the block. Unique within the flow.

description

Section titled “description”

Type: String

Optional description of what this block does.

alternativeLookupStrategy

Section titled “alternativeLookupStrategy”

Type: BlockLookupStrategy

Alternative strategy for looking up an existing block (useful when renaming blocks).

type

Section titled “type”

Type: BlockType

Block type specification. Either a core block or an app block.

position

Section titled “position”

Type: Position

Canvas position as [x, y] coordinates.

config

Section titled “config”

Type: One of: HTTPEndpointBlockConfig (for httpEndpoint), ScheduleBlockConfig (for schedule), MCPToolBlockConfig (for mcpTool), AppBlockConfig (for app blocks)

Block-specific configuration. Structure depends on the block type.

inputs

Section titled “inputs”

Type: One of: CoreBlockInputs (for core blocks), AppBlockInputs (for app blocks), GroupBlockIOConfig (for group blocks)

Input connections and configuration.

outputs

Section titled “outputs”

Type: One of: CustomizableBlockOutput (for most blocks), GroupBlockIOConfig (for group blocks)

Output configuration and customization.

errorHandler

Section titled “errorHandler”

Type: String

Name of the block to receive error events.

group

Section titled “group”

Type: String

Name of the group this block belongs to.

Note

Section titled “Note”

A sticky note on the canvas.

Syntax

Section titled “Syntax”
body: String
position: Position
style: NoteStyleMetadata
alternativeLookupStrategy: NoteLookupStrategy

Properties

Section titled “Properties”

body

Section titled “body”

Type: String

Markdown content of the note.

position

Section titled “position”

Type: Position

Canvas position as [x, y] coordinates.

style

Section titled “style”

Type: NoteStyleMetadata

Visual style settings for the note.

alternativeLookupStrategy

Section titled “alternativeLookupStrategy”

Type: NoteLookupStrategy

Alternative strategy for looking up an existing note.

AppInstallation

Section titled “AppInstallation”

Describes an app installation referenced by blocks.

Syntax

Section titled “Syntax”
appName: String
appVersion: String
id: String

Properties

Section titled “Properties”

appName

Section titled “appName”

Type: String

The name of the app.

appVersion

Section titled “appVersion”

Type: String

Version of the app.

id

Section titled “id”

Type: String (UUID)

Installation ID (UUID format).

Expression

Section titled “Expression”

Expressions are values or JavaScript code snippets that are evaluated at runtime.

You can use a raw value, as simple as this:

body: 'Hello, World!'

To use a dynamic expression, prefix with !expr:

body: !expr '`Hello, ${outputs.endpoint.params.name}`'
condition: !expr outputs.check.value > 10
delay: !expr 5 + outputs.config.extraDelay

Expressions have access to:

  • outputs: Values from connected block outputs (e.g., outputs.myBlock.someField)
  • config: Block configuration values
  • event (for input config fields): The current event being processed
  • Standard JavaScript operators and functions

BlockType

Section titled “BlockType”

Specifies whether the block is a core block or an app block. Exactly one must be set.

Syntax

Section titled “Syntax”
appBlock: AppBlockType
coreBlock: String

Properties

Section titled “Properties”

appBlock

Section titled “appBlock”

Type: AppBlockType

App block type specification.

coreBlock

Section titled “coreBlock”

Type: String (httpEndpoint, httpRequest, condition, sleep, transform, explode, collect, memorySet, memoryGet, memoryList, schedule, mcpTool, group)

Core block type name.

AppBlockType

Section titled “AppBlockType”

Specification for an app block.

Syntax

Section titled “Syntax”
block: String
appInstallation: String
schema: AppBlockSchema

Properties

Section titled “Properties”

block

Section titled “block”

Type: String

The block type name within the app.

appInstallation

Section titled “appInstallation”

Type: String

Reference to an app installation key defined in appInstallations.

schema

Section titled “schema”

Type: Object (app block schema)

Inline block schema (typically not used when appInstallation is set). Filled out automatically when exporting flows.

HTTPEndpointBlockConfig

Section titled “HTTPEndpointBlockConfig”

Configuration for HTTP endpoint blocks.

Syntax

Section titled “Syntax”
path: String
methods:
  - String
audience: String

Properties

Section titled “Properties”

path

Section titled “path”

Type: String

URL path pattern. Can include parameters like /hello/{name}.

methods

Section titled “methods”

Type: Array of String

HTTP methods to accept (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS).

audience

Section titled “audience”

Type: String (world, organization, project)

Who can access this endpoint. Values: world, organization, project.

ScheduleBlockConfig

Section titled “ScheduleBlockConfig”

Configuration for schedule blocks.

Syntax

Section titled “Syntax”
definition: ScheduleDefinition

Properties

Section titled “Properties”

definition

Section titled “definition”

Type: ScheduleDefinition

Schedule definition (cron or frequency-based).

MCPToolBlockConfig

Section titled “MCPToolBlockConfig”

Configuration for MCP tool blocks.

Syntax

Section titled “Syntax”
inputSchema: MCPToolInputSchema

Properties

Section titled “Properties”

inputSchema

Section titled “inputSchema”

Type: MCPToolInputSchema

JSON Schema defining the tool’s input parameters.

AppBlockConfig

Section titled “AppBlockConfig”

Configuration for app blocks.

Type: Map of String to Expression

CoreBlockInputs

Section titled “CoreBlockInputs”

Input configuration for core blocks.

Syntax

Section titled “Syntax”
default: CoreBlockInput

Properties

Section titled “Properties”

default

Section titled “default”

Type: CoreBlockInput

The default input.

CoreBlockInput

Section titled “CoreBlockInput”

A single input with links and configuration.

Syntax

Section titled “Syntax”
links:
  - BlockIOLink
config: Object

Properties

Section titled “Properties”
Section titled “links”

Type: Array of BlockIOLink

Connections from other block outputs.

config

Section titled “config”

Type: One of: ConditionBlockInputConfig (for condition), SleepBlockInputConfig (for sleep), TransformBlockInputConfig (for transform), HTTPRequestBlockInputConfig (for httpRequest), HTTPEndpointBlockInputConfig (for httpEndpoint), ExplodeBlockInputConfig (for explode), CollectBlockInputConfig (for collect), MemorySetBlockInputConfig (for memorySet), MemoryGetBlockInputConfig (for memoryGet), MemoryListBlockInputConfig (for memoryList), MCPToolBlockInputConfig (for mcpTool)

Input-specific configuration. Structure depends on the block type.

AppBlockInputs

Section titled “AppBlockInputs”

Input configuration for app blocks.

Type: Map of String to AppBlockInput

AppBlockInput

Section titled “AppBlockInput”

A single app block input with links and configuration.

Syntax

Section titled “Syntax”
links:
  - BlockIOLink
config:
  Key: Expression

Properties

Section titled “Properties”
Section titled “links”

Type: Array of BlockIOLink

Connections from other block outputs.

config

Section titled “config”

Type: Map of String to Expression

Input-specific configuration expressions.

GroupBlockIOConfig

Section titled “GroupBlockIOConfig”

Input/output configuration for group blocks.

Type: Map of String to GroupBlockIOLinks

Section titled “GroupBlockIOLinks”

Configuration for a single group input/output socket.

Syntax

Section titled “Syntax”
name: String
links:
  - BlockIOLink
outputCustomization: Expression

Properties

Section titled “Properties”

name

Section titled “name”

Type: String

Name of the socket.

Section titled “links”

Type: Array of BlockIOLink

Connections for this socket.

outputCustomization

Section titled “outputCustomization”

Type: Expression

Expression to transform the output value.

ConditionBlockInputConfig

Section titled “ConditionBlockInputConfig”

Input configuration for condition blocks.

Syntax

Section titled “Syntax”
condition: Expression

Properties

Section titled “Properties”

condition

Section titled “condition”

Type: Expression

JavaScript expression that evaluates to a boolean.

SleepBlockInputConfig

Section titled “SleepBlockInputConfig”

Input configuration for sleep blocks.

Syntax

Section titled “Syntax”
sleep: Expression

Properties

Section titled “Properties”

sleep

Section titled “sleep”

Type: Expression

Duration to sleep in seconds.

TransformBlockInputConfig

Section titled “TransformBlockInputConfig”

Input configuration for transform blocks.

HTTPRequestBlockInputConfig

Section titled “HTTPRequestBlockInputConfig”

Input configuration for HTTP request blocks.

Syntax

Section titled “Syntax”
url: Expression
method: String
body: Expression
headers:
  Key: Expression

Properties

Section titled “Properties”

url

Section titled “url”

Type: Expression

The URL to send the request to.

method

Section titled “method”

Type: String

HTTP method (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS).

body

Section titled “body”

Type: Expression

Request body expression.

headers

Section titled “headers”

Type: Map of String to Expression

HTTP headers as key-value expressions.

HTTPEndpointBlockInputConfig

Section titled “HTTPEndpointBlockInputConfig”

Input configuration for HTTP endpoint blocks (response configuration).

Syntax

Section titled “Syntax”
statusCode: Expression
body: Expression
headers:
  Key: Expression

Properties

Section titled “Properties”

statusCode

Section titled “statusCode”

Type: Expression

HTTP response status code.

body

Section titled “body”

Type: Expression

Response body expression.

headers

Section titled “headers”

Type: Map of String to Expression

Response headers as key-value expressions.

ExplodeBlockInputConfig

Section titled “ExplodeBlockInputConfig”

Input configuration for explode blocks.

Syntax

Section titled “Syntax”
items: Expression
emittedLimit: Integer

Properties

Section titled “Properties”

items

Section titled “items”

Type: Expression

Expression that evaluates to an array to explode into individual events.

emittedLimit

Section titled “emittedLimit”

Type: Number

Maximum number of items to emit. Maximum of 1024.

CollectBlockInputConfig

Section titled “CollectBlockInputConfig”

Input configuration for collect blocks.

Syntax

Section titled “Syntax”
group: Expression
count: Expression
emit: Expression
item: Expression
delay: Integer

Properties

Section titled “Properties”

group

Section titled “group”

Type: Expression

Expression to group items by.

count

Section titled “count”

Type: Expression

Trigger based on number of items to collect before emitting.

emit

Section titled “emit”

Type: Expression

Customized trigger to decide if the group is ready to be emitted.

item

Section titled “item”

Type: Expression

Expression to extract the item value from each input event.

delay

Section titled “delay”

Type: Number

Trigger based on delay in seconds before emitting after last item received.

MemorySetBlockInputConfig

Section titled “MemorySetBlockInputConfig”

Input configuration for memory set blocks.

Syntax

Section titled “Syntax”
key: Expression
collection: String
value: Expression
ttl: Expression

Properties

Section titled “Properties”

key

Section titled “key”

Type: Expression

Key to store the value under.

collection

Section titled “collection”

Type: String

Collection name for organizing keys.

value

Section titled “value”

Type: Expression

Value to store.

ttl

Section titled “ttl”

Type: Expression

Time-to-live in seconds (optional).

MemoryGetBlockInputConfig

Section titled “MemoryGetBlockInputConfig”

Input configuration for memory get blocks.

Syntax

Section titled “Syntax”
key: Expression
collection: String

Properties

Section titled “Properties”

key

Section titled “key”

Type: Expression

Key to retrieve the value for.

collection

Section titled “collection”

Type: String

Collection name for organizing keys.

MemoryListBlockInputConfig

Section titled “MemoryListBlockInputConfig”

Input configuration for memory list blocks.

Syntax

Section titled “Syntax”
collection: String
limit: Expression
startingKey: Expression

Properties

Section titled “Properties”

collection

Section titled “collection”

Type: String

Collection name to list keys from.

limit

Section titled “limit”

Type: Expression

Maximum number of keys to return. Maximum of 100.

startingKey

Section titled “startingKey”

Type: Expression

Key to start listing from (for pagination).

MCPToolBlockInputConfig

Section titled “MCPToolBlockInputConfig”

Input configuration for MCP tool blocks (response configuration).

Syntax

Section titled “Syntax”
responseBody: Expression

Properties

Section titled “Properties”

responseBody

Section titled “responseBody”

Type: Expression

Expression for the MCP tool response body.

CustomizableBlockOutput

Section titled “CustomizableBlockOutput”

Output configuration for blocks that support output customization.

Type: Map of String to CoreBlockOutput

CoreBlockOutput

Section titled “CoreBlockOutput”

Configuration for a single block output.

Syntax

Section titled “Syntax”
outputCustomization: Expression

Properties

Section titled “Properties”

outputCustomization

Section titled “outputCustomization”

Type: Expression

Expression to transform the output value.

Section titled “BlockIOLink”

A connection from another block’s output.

Syntax

Section titled “Syntax”
block: String
output: String

Properties

Section titled “Properties”

block

Section titled “block”

Type: String

Name of the source block.

output

Section titled “output”

Type: String

Name of the output on the source block.

BlockLookupStrategy

Section titled “BlockLookupStrategy”

Strategy for looking up an existing block (useful when renaming).

Syntax

Section titled “Syntax”
id: String
name: String

Properties

Section titled “Properties”

id

Section titled “id”

Type: String (UUID)

Block ID to look up directly.

name

Section titled “name”

Type: String

Previous block name to look up by.

NoteLookupStrategy

Section titled “NoteLookupStrategy”

Strategy for looking up an existing note.

Syntax

Section titled “Syntax”
id: String

Properties

Section titled “Properties”

id

Section titled “id”

Type: String (UUID)

Note ID to look up directly.

Position

Section titled “Position”

Canvas position as [x, y] coordinates.

Syntax

Section titled “Syntax”
x: Number
y: Number

Properties

Section titled “Properties”

x

Section titled “x”

Type: Number

Horizontal coordinate of the position.

y

Section titled “y”

Type: Number

Vertical coordinate of the position.

ScheduleDefinition

Section titled “ScheduleDefinition”

Schedule definition. Either cron-based or frequency-based.

Syntax

Section titled “Syntax”
type: String
cron: ScheduleDefinitionCron
frequency: ScheduleDefinitionFrequency

Properties

Section titled “Properties”

type

Section titled “type”

Type: String (cron, frequency)

cron

Section titled “cron”

Type: ScheduleDefinitionCron

Cron schedule definition.

frequency

Section titled “frequency”

Type: ScheduleDefinitionFrequency

Frequency schedule definition.

ScheduleDefinitionCron

Section titled “ScheduleDefinitionCron”

Cron-based schedule configuration.

Syntax

Section titled “Syntax”
expression: String
location: String

Properties

Section titled “Properties”

expression

Section titled “expression”

Type: String

Cron expression defining the schedule.

location

Section titled “location”

Type: String

IANA time zone name defining the schedule’s time zone, e.g., ‘America/Los_Angeles’. Defaults to ‘UTC’.

ScheduleDefinitionFrequency

Section titled “ScheduleDefinitionFrequency”

Frequency-based schedule configuration.

Syntax

Section titled “Syntax”
interval: Integer
unit: String

Properties

Section titled “Properties”

interval

Section titled “interval”

Type: Number

Interval between scheduled runs, in the given unit.

unit

Section titled “unit”

Type: String (seconds, minutes, hours)

Unit of time for the interval; defaults to ‘seconds’.

NoteStyleMetadata

Section titled “NoteStyleMetadata”

Visual style settings for notes.

Syntax

Section titled “Syntax”
width: Integer
height: Integer
color: String

Properties

Section titled “Properties”

width

Section titled “width”

Type: Number

Width of the note.

height

Section titled “height”

Type: Number

Height of the note.

color

Section titled “color”

Type: String

Color of the note, in hex format (e.g. #18181b).

MCPToolInputSchema

Section titled “MCPToolInputSchema”

Input schema for MCP tools. Maps parameter names to their definitions.

Type: Map of String to MCPToolInputProperty

MCPToolInputProperty

Section titled “MCPToolInputProperty”

Definition of a single MCP tool input parameter.

Syntax

Section titled “Syntax”
required: Boolean
type: Object

Properties

Section titled “Properties”

required

Section titled “required”

Type: Boolean

Whether this input is required.

type

Section titled “type”

Type: Object (JSON Schema)

The JSON schema document defining this input.