Nodes
Learn about node types, naming conventions, configuration, data flow, and execution behavior.
Nodes are the building blocks of a Swirls graph. Each node has a type, a configuration object, and optional input/output schemas. Nodes are connected by edges to form a directed acyclic graph (DAG), and execution proceeds in topological order from upstream to downstream.
Node types
Every node has one of the following types. Each type has its own configuration schema, input expectations, and output shape.
| Type | Purpose |
|---|---|
| AI | Call models for text, structured output, images, embeddings, and more. |
| HTTP | Make HTTP requests to external APIs, webhooks, or services. |
| Switch | Route execution to one branch by returning one of the defined cases from a function. |
| Code | Run JavaScript in an isolated sandbox to transform or compute data. |
| Graph | Execute another graph as a subgraph; pass inputs and receive the child graph's output. |
| Stream | Read from a project-scoped stream with filtering, sorting, and pagination. |
| Bucket | Read or write files in the project's default storage bucket (download or upload). |
| Send email with dynamic content via a configured provider. | |
| Scrape | Fetch and extract structured content from web pages. |
| Wait | Pause execution for a fixed or dynamically computed duration. |
Naming conventions
Every node has a name that uniquely identifies it within the graph. Node names must match the pattern /^[a-zA-Z0-9_]+$/ -- only letters, numbers, and underscores are allowed. Nodes also support an optional label and description for display in the Portal and execution logs.
Placeholders
Configuration fields that accept string values support placeholders for injecting runtime data. Placeholders use double-brace syntax:
{{input.text}}-- reference a field from the trigger payload or upstream node output.{{secrets.apiKey}}-- reference a project secret (see Secrets).
Placeholders are resolved at execution time, immediately before the node runs. Any string configuration field (URLs, prompts, headers, email addresses, and more) can contain one or more placeholders.
Inputs and outputs
- Input: Each node receives data from two sources: the trigger payload (the graph's initial input) and the outputs of upstream nodes. When nodes are connected by edges, the downstream node automatically inherits the output schema of the upstream node as its input schema, keeping data flow type-safe and predictable.
- Output: Each node produces an output that is stored in the node execution record and passed to all downstream nodes. If a node fails, the error is recorded and the graph execution status reflects the failure.
Execution model
Nodes execute in topological order. A node runs only after all of its upstream dependencies have completed. This guarantees that every node has access to the full set of upstream outputs when it executes.
- Code nodes run user-provided JavaScript in an isolated sandbox. The host process, filesystem, and network are not accessible from within the sandbox.
- HTTP nodes record request and response metadata for auditability and debugging.
- LLM nodes record the full configuration used (model, prompt, temperature, max tokens) so runs are reproducible.
Next steps
Choose the right node type for each step in your workflow and connect them with edges to define data flow. See Schemas for how schemas define data at graph boundaries and power TypeScript code generation.