Getting Started

Understand the core building blocks and how they work together.

Blocktion API Documentation

Comprehensive reference and guides for the Blocktion REST API. Build powerful workflows, integrate with external services, and create amazing automation experiences.

Get Started View on GitHub

Overview

High-level relationship between Providers, Handlers, Blocks, and Workflows.

Providers

Manage authentication and credentials for external services. They handle OAuth flows, store API keys securely, and provide standardized access to third-party APIs.

Handlers

Define the business logic and parameter schemas for specific actions. They contain the actual implementation code and specify what parameters are required.

Blocks

Reusable components that combine handlers with specific parameter configurations. They can be published to the marketplace and shared across workflows.

Nodes

Instances of blocks within workflows with specific configurations. They can have static config (from locked parameters) and dynamic inputs (from unlocked parameters).

Workflows

Visual representations of business processes that connect nodes together. They orchestrate execution, handle data flow, and provide error handling and retries.

Create your first workflow

Add nodes, wire data with expressions, and control execution order with explicit connections.

1. Create an empty workflow

POST /api/workflows with a name (optionally description and tags). You can also pass initial nodes, but adding/updating nodes later is fine.

2. Add nodes (instances of blocks)

PUT /api/workflows/<workflow_id> with a nodes object keyed by nodeId. Each node typically includes block_id, optional position_x/position_y, and a config object. Use system blocks directly; install marketplace blocks first if not available.

3. Let data connections be derived automatically

When a target node input is set via an expression like {{ outputs.<sourceNodeId>.<outputName> }} inside its config, the backend detects and creates a data connection from the source to the target. No manual wiring needed for these.

4. Add explicit connections when needed

For control-flow (order without data) or special cases, send explicit_connections in PUT /api/workflows/<workflow_id> using the connection model: connection_type is control_flow, data, or both; you may include conditions and a transformation.

5. Define workflow variables (optional)

Provide a variables map in PUT /api/workflows/<workflow_id>. Variables become available as inputs context for nodes and are also returned by /api/workflows/<workflow_id>/blocks/<block_id>/available-inputs.

6. Validate

POST /api/workflows/<workflow_id>/validate to confirm structure, missing references, cycles, and presence of at least one trigger node.

7. Execute

Manual: POST /api/workflows/<workflow_id>/execute with optional trigger_node_id and inputs.

Triggers: Set up triggers as nodes (detected by block_id containing "trigger" or an explicit flag), then:

Enable: POST /api/triggers/<trigger_id>/enable
Activate directly: POST /api/triggers/<trigger_id>/activate
Emit event: POST /api/triggers/events/emit
Process webhook: POST /api/triggers/webhooks/process

Notes

No strict order to create nodes or connections; update anytime.
Node positions (position_x, position_y) are optional and purely visual.
Use /api/workflows/<workflow_id>/topology to fetch nodes plus both derived and explicit connections.