flow() function defines a single flow within a code-native integration. A flow has a trigger (webhook, schedule, or polling) and a main execution function. Flows are passed as an array to the flows field of integration().
Function signature
export const flow = <
TInputs extends Inputs,
TActionInputs extends Inputs,
TPayload extends TriggerPayload = TriggerPayload,
TAllowsBranching extends boolean = boolean,
TResult extends TriggerResult<TAllowsBranching, TPayload> = TriggerResult<TAllowsBranching, TPayload>,
TTriggerPayload extends TriggerPayload = TriggerPayload,
T extends Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload>
= Flow<TInputs, TActionInputs, TPayload, TAllowsBranching, TResult, TTriggerPayload>,
>(
definition: T,
): T
Flow is a union of StandardFlow (webhook or scheduled trigger) and PollingFlow (polling trigger). The triggerType field determines which variant applies.
Parameters
An object that defines the flow. All base fields apply to both standard and polling flows.
Hide Base flow fields (all flow types)
Hide Base flow fields (all flow types)
The unique display name for this flow.
A unique, unchanging identifier for this flow. Even if the
name changes, stableKey preserves the flow’s identity in the platform.Human-readable description for this flow.
The main function executed when this flow is invoked. Receives
context and params (which includes the trigger payload via params.onTrigger.results).When
true, the flow responds synchronously to the HTTP request that triggered it, returning the execution result in the response body.When
true, this flow is an AI agent flow exposed on the integration’s MCP server.Retry configuration for this flow when execution fails.
Show RetryConfig fields
Show RetryConfig fields
Maximum number of retry attempts. Must be between 0 and 10.
Delay in minutes between retry attempts. Must be between 0 and 60.
When
true, uses exponential backoff to calculate the delay between attempts.Name of the field in the trigger payload to use as a unique request ID for retry deduplication.
Queue configuration controlling how concurrent executions are handled. See queue config variants below.
Security configuration for this flow’s endpoint URL.Accepted values:
"unsecured"— No authentication required."customer_optional"— Customer API key is optional."customer_required"— Customer API key is required."organization"— Uses organization-level API keys.
List of API keys for the endpoint when
endpointSecurityType is "organization".Error handling configuration for steps within this flow.
Show StepErrorConfig fields
Show StepErrorConfig fields
The type of error handler:
"fail", "ignore", or "retry".Maximum number of retry attempts (0–5). Only applies when
errorHandlerType is "retry".Delay in seconds between retry attempts (0–60).
When
true, uses exponential backoff between step retry attempts.When
true, ignores the final error after the last retry attempt.Preprocess flow configuration for when this flow’s result contains flow routing attributes. Only one flow per integration may define this.
Show PreprocessFlowConfig fields
Show PreprocessFlowConfig fields
Function executed when an instance of this integration is deployed.
Function executed when an instance of this integration is deleted.
Optional handlers for webhook lifecycle events.
Optional JSON Schema definitions for this flow. Currently used only with AI agent flows. Must include an
invoke key.Show FlowDefinitionFlowSchema fields
Show FlowDefinitionFlowSchema fields
Title for the schema.
Optional comment.
JSON Schema version URI. Defaults to
"https://json-schema.org/draft/2020-12/schema".Properties in the schema, each with a description and optional type.
List of required property names.
Show Standard flow fields (triggerType: 'standard' or unset)
Show Standard flow fields (triggerType: 'standard' or unset)
Set to
"standard" (or omit) for webhook and scheduled flows.Schedule configuration for automatically-executed flows. Use a cron expression as a
value, or reference a schedule config variable with configVar.The trigger function for this flow. Accepts either a reference to a component trigger or an inline function. If omitted, a default webhook trigger is used.
Show Polling flow fields (triggerType: 'polling')
Show Polling flow fields (triggerType: 'polling')
Must be
"polling" to use a polling trigger. Polling flows run on a schedule and have access to context.polling.* functions for managing state between runs.Required for polling flows. Defines the polling frequency as a cron expression.
Required for polling flows. The trigger function that runs on each poll cycle.
Queue config variants
ThequeueConfig field accepts one of the following shapes:
- ParallelQueueConfig
- ThrottledQueueConfig
- SequentialQueueConfig
- StandardQueueConfig
All requests are processed simultaneously with no limits.
queueConfig: {
type: "parallel",
}
Limits the maximum number of concurrent executions per instance.
queueConfig: {
type: "throttled",
concurrencyLimit: 5, // 2–15
dedupeIdField: "requestId", // optional
}
Processes one execution at a time, in the order received.
queueConfig: {
type: "sequential",
dedupeIdField: "requestId", // optional
}
Fine-grained queue control without a fixed processing mode.
queueConfig: {
usesFifoQueue: true, // FIFO ordering
dedupeIdField: "requestId", // optional
singletonExecutions: false, // only for scheduled/polling flows
concurrencyLimit: 4, // 2–15
}
Return type
The same flow definition object passed in, unchanged. The function is used for type-checking and inference.
Examples
import { flow } from "@prismatic-io/spectral";
const syncFlow = flow({
name: "Sync Records",
stableKey: "sync-records",
description: "Processes incoming webhook payloads.",
isSynchronous: false,
endpointSecurityType: "customer_optional",
retryConfig: {
maxAttempts: 3,
delayMinutes: 5,
usesExponentialBackoff: true,
},
onExecution: async (context, params) => {
const payload = params.onTrigger.results;
context.logger.info("Received payload", { payload });
return { data: null };
},
});
Related
integration()— The parent function that accepts an array of flows.configPage()— Define config wizard pages referenced in flows.componentManifest()— Register components whose actions are available incontext.components.