Flow Definition Reference

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

Flow

The root object for a flow definition.

Syntax

appInstallations:
  Key: AppInstallation
dataTables:
  Key: DataTable
agentPools:
  Key: AgentPool
blocks:
  - Block
notes:
  - Note

Properties

appInstallations

Type: Map of String to AppInstallation

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

dataTables

Type: Map of String to DataTable

Data tables used by blocks in this flow. Keys are references used by Data Table blocks.

agentPools

Type: Map of String to AgentPool

Agent pools used by HTTP Request blocks. Keys are local references used by block configs. Each entry identifies a pool by its name or agent pool ID.

blocks

Type: Array of Block

List of blocks in the flow.

notes

Type: Array of Note

Sticky notes on the canvas.

---

Block

A block in the flow.

Syntax

name: String
description: String
alternativeLookupStrategy: BlockLookupStrategy
type: BlockType
position: Position
config: BlockConfig
inputs: BlockInputs
outputs: BlockOutputs
errorHandler: String
dynamicOutputKeys:
  - String
group: String

Properties

name

Type: String

The name of the block. Unique within the flow.

description

Type: String

Optional description of what this block does.

alternativeLookupStrategy

Type: BlockLookupStrategy

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

type

Type: BlockType

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

position

Type: Position

Canvas position as [x, y] coordinates.

config

Type: One of: HTTPEndpointBlockConfig (for httpEndpoint), ScheduleBlockConfig (for schedule), MCPToolBlockConfig (for mcpTool), AppBlockConfig (for app blocks), SpaceliftBlockConfig (for spacelift), DataTableCreateRowConfig (for dataTableCreateRow), DataTableGetRowConfig (for dataTableGetRow), DataTableUpdateRowConfig (for dataTableUpdateRow), DataTableQueryRowsConfig (for dataTableQueryRows), DataTableDeleteRowConfig (for dataTableDeleteRow), DataTableSetRowAssignedUsersConfig (for dataTableShareRow)

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

inputs

Type: One of: CoreBlockInputs (for core blocks), AppBlockInputs (for app blocks), SpaceliftBlockInputs (for spacelift), ConcurrencyGroupBlockInputs (for concurrencyGroup), GroupBlockIOConfig (for group blocks)

Input connections and configuration.

outputs

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

Output configuration and customization.

errorHandler

Type: String

Name of the block to receive error events.

dynamicOutputKeys

Type: Array of String

Output keys to pre-create for blocks with dynamically managed outputs.

group

Type: String

Name of the group this block belongs to.

---

Note

A sticky note on the canvas.

Syntax

body: String
position: Position
style: NoteStyleMetadata
alternativeLookupStrategy: NoteLookupStrategy

Properties

body

Type: String

Markdown content of the note.

position

Type: Position

Canvas position as [x, y] coordinates.

style

Type: NoteStyleMetadata

Visual style settings for the note.

alternativeLookupStrategy

Type: NoteLookupStrategy

Alternative strategy for looking up an existing note.

---

AppInstallation

Describes an app installation referenced by blocks.

Syntax

appName: String
appVersion: String
id: String

Properties

appName

Type: String

The name of the app.

appVersion

Type: String

Version of the app.

id

Type: String (UUID)

Installation ID (UUID format).

---

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

---

DataTable

Describes a data table referenced by blocks.

Syntax

id: String
name: String
schema: DataTableSchema

Properties

id

Type: String (UUID)

Data table ID (UUID format).

name

Type: String

The name of the data table.

schema

Type: DataTableSchema

Schema of the data table.

---

DataTableSchema

The columns a data table holds.

Syntax

columns:
  - DataTableSchemaColumn

Properties

columns

Type: Array of DataTableSchemaColumn

List of columns in the data table.

---

DataTableSchemaColumn

A single data table column.

Syntax

name: String
type: String
dataTableRef: String

Properties

name

Type: String

The name of the column.

type

Type: String (string, integer, float, boolean, datetime, json, row_ref)

The type of the column. One of string, integer, boolean, datetime, json, float, object, row_ref.

dataTableRef

Type: String

The slug of the data table this column references.

---

AgentPool

Identifies an agent pool by name or ID, for blocks that run through a private agent pool.

Syntax

name: String
id: String

Properties

name

Type: String

The name of the agent pool.

id

Type: String (UUID)

Agent pool ID (UUID format). If both id and name are provided, id takes precedence.

---

BlockType

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

Syntax

appBlock: AppBlockType
coreBlock: String
kind: String

Properties

appBlock

Type: AppBlockType

App block type specification.

coreBlock

Type: String (condition, sleep, transform, httpRequest, explode, collect, memorySet, memoryGet, memoryList, schedule, httpEndpoint, mcpTool, handleError, group, dataTableCreateRow, dataTableUpdateRow, dataTableGetRow, dataTableQueryRows, dataTableDeleteRow, dataTableShareRow, formOpened, showForm, concurrencyGroup, spacelift)

Core block type name.

kind

Type: String

Sub-block of a core block family (required for coreBlock: spacelift, e.g. triggerRun).

---

AppBlockType

Specification for an app block.

Syntax

block: String
appInstallation: String
schema: AppBlockSchema

Properties

block

Type: String

The block type name within the app.

appInstallation

Type: String

Reference to an app installation key defined in appInstallations.

schema

Type: Object (app block schema)

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

---

HTTPEndpointBlockConfig

Configuration for HTTP Endpoint blocks.

Syntax

path: String
methods:
  - String
audience: String

Properties

path

Type: String

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

methods

Type: Array of String

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

audience

Type: String (world, organization, project)

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

---

ScheduleBlockConfig

Configuration for Schedule blocks.

Syntax

definition: ScheduleDefinition

Properties

definition

Type: ScheduleDefinition

Schedule definition (cron or frequency-based).

---

MCPToolBlockConfig

Configuration for MCP Tool blocks.

Syntax

inputSchema: MCPToolInputSchema

Properties

inputSchema

Type: MCPToolInputSchema

JSON Schema defining the tool's input parameters.

---

AppBlockConfig

Configuration for app blocks.

Type: Map of String to Expression

---

DataTableCreateRowConfig

Configuration for Data Table Create Row blocks.

Syntax

table: String

Properties

table

Type: String

Reference to a data table key defined in dataTables.

---

DataTableGetRowConfig

Configuration for Data Table Get Row blocks.

Syntax

table: String

Properties

table

Type: String

Reference to a data table key defined in dataTables.

---

DataTableUpdateRowConfig

Configuration for Data Table Update Row blocks.

Syntax

table: String

Properties

table

Type: String

Reference to a data table key defined in dataTables.

---

DataTableQueryRowsConfig

Configuration for Data Table Query Rows blocks.

Syntax

table: String
limit: Integer

Properties

table

Type: String

Reference to a data table key defined in dataTables.

limit

Type: Number

Maximum number of rows to return.

---

DataTableDeleteRowConfig

Configuration for Data Table Delete Row blocks.

Syntax

table: String

Properties

table

Type: String

Reference to a data table key defined in dataTables.

---

DataTableSetRowAssignedUsersConfig

Configuration for Data Table Share Row blocks.

Syntax

table: String

Properties

table

Type: String

Reference to a data table key defined in dataTables.

---

CoreBlockInputs

Input configuration for core blocks.

Syntax

default: CoreBlockInput

Properties

default

Type: CoreBlockInput

The default input.

---

CoreBlockInput

A single input with links and configuration.

Syntax

links:
  - BlockIOLink
config: Object

Properties

links

Type: Array of BlockIOLink

Connections from other block outputs.

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), ConcurrencyGroupBlockInputConfig (for concurrencyGroup), DataTableCreateRowInputConfig (for dataTableCreateRow), DataTableGetRowInputConfig (for dataTableGetRow), DataTableUpdateRowInputConfig (for dataTableUpdateRow), DataTableQueryRowsInputConfig (for dataTableQueryRows), DataTableDeleteRowInputConfig (for dataTableDeleteRow), DataTableSetRowAssignedUsersInputConfig (for dataTableShareRow)

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

---

AppBlockInputs

Input configuration for app blocks.

Type: Map of String to AppBlockInput

---

AppBlockInput

A single app block input with links and configuration.

Syntax

links:
  - BlockIOLink
config:
  Key: Expression

Properties

links

Type: Array of BlockIOLink

Connections from other block outputs.

config

Type: Map of String to Expression

Input-specific configuration expressions.

---

SpaceliftBlockConfig

Block-level configuration for Spacelift blocks, resolved once when saved rather than per event.

Type: Map of String to Expression

---

SpaceliftBlockInputs

Input configuration for Spacelift blocks, keyed by socket name.

Type: Map of String to SpaceliftBlockInput

---

SpaceliftBlockInput

A single Spacelift input socket, with links and the configuration the block's kind declares on it.

Syntax

links:
  - BlockIOLink
config:
  Key: Expression

Properties

links

Type: Array of BlockIOLink

Connections from other block outputs.

config

Type: Map of String to Expression

Input-specific configuration expressions.

---

ConcurrencyGroupBlockInputs

Input configuration for Concurrency Group blocks, which take events on two sockets.

Syntax

acquire: CoreBlockInput
release: CoreBlockInput

Properties

acquire

Type: CoreBlockInput

Events to queue in the concurrency group.

release

Type: CoreBlockInput

Release input to mark the active item as processed.

---

GroupBlockIOConfig

Input/output configuration for Group blocks.

Type: Map of String to GroupBlockIOLinks

---

GroupBlockIOLinks

Configuration for a single group input/output socket.

Syntax

name: String
links:
  - BlockIOLink
outputCustomization: Expression
sensitivePaths:
  - String

Properties

name

Type: String

Name of the socket.

links

Type: Array of BlockIOLink

Connections for this socket.

outputCustomization

Type: Expression

Expression to transform the output value.

sensitivePaths

Type: Array of String

JSONPath expressions marking sensitive parts of the output.

---

ConditionBlockInputConfig

Input configuration for Condition blocks.

Syntax

condition: Expression

Properties

condition

Type: Expression

JavaScript expression that evaluates to a boolean.

---

SleepBlockInputConfig

Input configuration for Sleep blocks.

Syntax

sleep: Expression

Properties

sleep

Type: Expression

Duration to sleep in seconds.

---

TransformBlockInputConfig

Input configuration for Transform blocks.

---

HTTPRequestBlockInputConfig

Input configuration for HTTP Request blocks.

Syntax

url: Expression
method: String
body: Expression
headers:
  Key: Expression
agentPool: String

Properties

url

Type: Expression

The URL to send the request to.

method

Type: String

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

body

Type: Expression

Request body expression.

headers

Type: Map of String to Expression

HTTP headers as key-value expressions.

agentPool

Type: String

Reference to an agent pool key defined in agentPools.

---

HTTPEndpointBlockInputConfig

Input configuration for HTTP Endpoint blocks (response configuration).

Syntax

statusCode: Expression
body: Expression
headers:
  Key: Expression

Properties

statusCode

Type: Expression

HTTP response status code.

body

Type: Expression

Response body expression.

headers

Type: Map of String to Expression

Response headers as key-value expressions.

---

ExplodeBlockInputConfig

Input configuration for Explode blocks.

Syntax

items: Expression
emittedLimit: Integer

Properties

items

Type: Expression

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

emittedLimit

Type: Number

Maximum number of items to emit. Maximum of 1024.

---

CollectBlockInputConfig

Input configuration for Collect blocks.

Syntax

group: Expression
count: Expression
emit: Expression
item: Expression
delay: Integer

Properties

group

Type: Expression

Expression to group items by.

count

Type: Expression

Trigger based on number of items to collect before emitting.

emit

Type: Expression

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

item

Type: Expression

Expression to extract the item value from each input event.

delay

Type: Number

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

---

MemorySetBlockInputConfig

Input configuration for Memory Set blocks.

Syntax

key: Expression
collection: String
value: Expression
ttl: Expression

Properties

key

Type: Expression

Key to store the value under.

collection

Type: String

Collection name for organizing keys.

value

Type: Expression

Value to store.

ttl

Type: Expression

Time-to-live in seconds (optional).

---

MemoryGetBlockInputConfig

Input configuration for Memory Get blocks.

Syntax

key: Expression
collection: String

Properties

key

Type: Expression

Key to retrieve the value for.

collection

Type: String

Collection name for organizing keys.

---

MemoryListBlockInputConfig

Input configuration for Memory List blocks.

Syntax

collection: String
limit: Expression
startingKey: Expression

Properties

collection

Type: String

Collection name to list keys from.

limit

Type: Expression

Maximum number of keys to return. Maximum of 100.

startingKey

Type: Expression

Key to start listing from (for pagination).

---

MCPToolBlockInputConfig

Input configuration for MCP Tool blocks (response configuration).

Syntax

responseBody: Expression

Properties

responseBody

Type: Expression

Expression for the MCP Tool response body.

---

ConcurrencyGroupBlockInputConfig

Input configuration for a Concurrency Group block's sockets.

Syntax

groupKey: Expression
itemKey: Expression

Properties

groupKey

Type: Expression

Expression to compute the group key. Null means all events share one group.

itemKey

Type: Expression

Expression to compute the item key. Used to match releases to active items.

---

DataTableCreateRowInputConfig

Input configuration for Data Table Create Row blocks.

Syntax

row: Expression
ttl: Expression

Properties

row

Type: Expression

Row object to be added to the table.

ttl

Type: Expression

Time to live in seconds. The row will expire after this duration.

---

DataTableGetRowInputConfig

Input configuration for Data Table Get Row blocks.

Syntax

rowID: Expression

Properties

rowID

Type: Expression

Expression for the row ID to retrieve.

---

DataTableUpdateRowInputConfig

Input configuration for Data Table Update Row blocks.

Syntax

rowID: Expression
row: Expression
ttl: Expression

Properties

rowID

Type: Expression

Expression for the row ID to update.

row

Type: Expression

Row object with updated fields.

ttl

Type: Expression

Time to live in seconds. The row will expire after this duration.

---

DataTableQueryRowsInputConfig

Input configuration for Data Table Query Rows blocks.

Syntax

filter: Expression
queryOrders: Expression
continuationToken: Expression

Properties

filter

Type: Expression

Expression for the query filter.

queryOrders

Type: Expression

Expression for the query sort orders.

continuationToken

Type: Expression

Continuation token for paginated queries.

---

DataTableDeleteRowInputConfig

Input configuration for Data Table Delete Row blocks.

Syntax

rowIDs: Expression

Properties

rowIDs

Type: Expression

Expression for the row IDs to delete.

---

DataTableSetRowAssignedUsersInputConfig

Input configuration for Data Table Share Row blocks.

Syntax

rowID: Expression
assignees: Expression

Properties

rowID

Type: Expression

Expression for the row ID to assign users to.

assignees

Type: Expression

Expression for user emails to assign. Can use 'stored' variable.

---

CustomizableBlockOutput

Output configuration for blocks that support output customization.

Type: Map of String to CoreBlockOutput

---

CoreBlockOutput

Configuration for a single block output.

Syntax

outputCustomization: Expression
sensitivePaths:
  - String

Properties

outputCustomization

Type: Expression

Expression to transform the output value.

sensitivePaths

Type: Array of String

JSONPath expressions marking sensitive parts of the output.

---

BlockIOLink

A connection from another block's output.

Syntax

block: String
output: String

Properties

block

Type: String

Name of the source block.

output

Type: String

Name of the output on the source block.

---

BlockLookupStrategy

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

Syntax

id: String
name: String

Properties

id

Type: String (UUID)

Block ID to look up directly.

name

Type: String

Previous block name to look up by.

---

NoteLookupStrategy

Strategy for looking up an existing note.

Syntax

id: String

Properties

id

Type: String (UUID)

Note ID to look up directly.

---

Position

Canvas position as [x, y] coordinates.

Syntax

x: Number
y: Number

Properties

x

Type: Number

Horizontal coordinate of the position.

y

Type: Number

Vertical coordinate of the position.

---

ScheduleDefinition

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

Syntax

type: String
cron: ScheduleDefinitionCron
frequency: ScheduleDefinitionFrequency

Properties

type

Type: String (cron, frequency)

Type of the schedule definition.

cron

Type: ScheduleDefinitionCron

Cron schedule definition. Required when type is 'cron'.

frequency

Type: ScheduleDefinitionFrequency

Frequency schedule definition. Required when type is 'frequency'.

---

ScheduleDefinitionCron

Cron-based schedule configuration.

Syntax

expression: String
location: String

Properties

expression

Type: String

Cron expression defining the schedule.

location

Type: String

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

---

ScheduleDefinitionFrequency

Frequency-based schedule configuration.

Syntax

interval: Integer
unit: String

Properties

interval

Type: Number

Interval between scheduled runs, in the given unit.

unit

Type: String (seconds, minutes, hours)

Unit of time for the interval; defaults to 'seconds'.

---

NoteStyleMetadata

Visual style settings for notes.

Syntax

width: Integer
height: Integer
color: String

Properties

width

Type: Number

Width of the note.

height

Type: Number

Height of the note.

color

Type: String

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

---

MCPToolInputSchema

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

Type: Map of String to MCPToolInputProperty

---

MCPToolInputProperty

Definition of a single MCP tool input parameter.

Syntax

required: Boolean
type: Object

Properties

required

Type: Boolean

Whether this input is required.

type

Type: Object (JSON Schema)

The JSON schema document defining this input.

---