Blocks

Build reusable components with system, user, and custom blocks

What is a Block?

A block is a reusable execution unit within a workflow. It binds a handler and a specific action with parameter and output schemas, plus runtime configuration. Blocks can be system-provided or user-created, and may be triggers or regular processing steps.

Block Aspects

Blocks have different aspects that define their characteristics. A single block can have multiple aspects - for example, a user-created trigger block that integrates with Gmail.

Ownership

Who created and owns the block

System Blocks

is_system: true

Built-in blocks provided by Blocktion platform

HTTP RequestData TransformConditional Logic

User Blocks

is_system: false

Custom blocks created by users

Custom APIBusiness LogicData Processing

Purpose

What the block is designed to do

Trigger Blocks

is_trigger: true

Blocks that initiate workflow execution

Webhook TriggersSchedule TriggersEvent Triggers

Regular Blocks

is_trigger: false

Standard processing blocks in workflows

Data TransformAPI CallConditional Logic

Integration

External service connectivity

Integration Blocks

is_integration: true

Blocks that connect to external services

Gmail ConnectorTwitter APIDatabase Handler

Standalone Blocks

is_integration: false

Self-contained blocks with no external dependencies

Data TransformMath OperationsText Processing

Reusability

How the block can be reused

Template Blocks

is_template: true

Reusable templates for creating other blocks

Email TemplateReport GeneratorData Validator

Instance Blocks

is_template: false

Concrete block instances ready for execution

Send EmailGenerate ReportValidate Data

Block Tags

Blocks are categorized using tags for better organization and discoverability. Tags help filter and search for specific types of blocks.

HTTP & Networking

Web requests and network operations

httpnetworkgetpostputdelete

Data & Storage

Database and data operations

datastoredatabasecreateupdatequeryread

Triggers

Workflow initiation methods

triggermanualschedulewebhookeventconditionaldata_driven

Integrations

External service connections

integrationgmailgeminitwitter

Code & AI

Programming and AI operations

sandboxcodegeneratechat

Communication

Messaging and notifications

emailsendmessagetweetsearchuser

Overview

Blocks are reusable components that can be used in workflows. Each block has multiple aspects that define its characteristics and behavior.

Block Structure

• Handler & Action - Defines execution logic
• Parameters - Input schema and validation
• Outputs - Output schema definition
• Configuration - Runtime settings and options
• Tags - Categorization and searchability

Key Features

• Reusable across multiple workflows
• Parameter validation and type checking
• Fallback behavior configuration
• Marketplace publishing support
• Template-based creation

Example Block Combinations

• User + Trigger + Integration - Custom Gmail webhook trigger

• System + Regular + Standalone - Built-in data transform block

• User + Template + Integration - Reusable email template for Slack

Endpoints

GET/api/blocks

List Blocks

List blocks with pagination and filters

Query Parameters

tag(string)Filter by tag

is_system(boolean)System or user blocks

search(string)Search by name or description

page(number)Page number (starts at 1)

limit(number)Items per page (default 10)

Response

{
  "data": [
    {
      "id": "block_123456",
      "name": "Send Email Block",
      "description": "A powerful block for sending emails via SMTP",
      "is_system": false,
      "is_template": false,
      "parameters": {},
      "outputs": {},
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z",
      "user_id": "user_123",
      "icon": null,
      "category_icon": null,
      "ui_schema": null,
      "is_trigger": false,
      "trigger_config": null,
      "is_integration": false,
      "provider_id": null,
      "provider_name": null,
      "handler": "email_handler",
      "action": "send_email",
      "tags": [
        "communication"
      ]
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 10
}

cURL Example

curl -X GET "https://api.blocktion.io/api/blocks" \
  -H "Authorization: Bearer <your_access_token>"

GET/api/blocks/system

List System Blocks

List system blocks with pagination and filters

Query Parameters

tag(string)Filter by tag

search(string)Search by name or description

page(number)Page number (starts at 1)

limit(number)Items per page (default 10)

Response

{
  "data": [],
  "total": 0,
  "page": 1,
  "limit": 10
}

cURL Example

curl -X GET "https://api.blocktion.io/api/blocks/system"

GET/api/blocks/{block_id}

Get Block

Get block by ID

Response

{
  "data": {
    "id": "block_123456",
    "name": "Send Email Block",
    "description": "A powerful block for sending emails via SMTP",
    "is_system": false,
    "is_template": false,
    "parameters": {},
    "outputs": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z",
    "user_id": "user_123",
    "handler": "email_handler",
    "action": "send_email",
    "tags": [
      "communication"
    ],
    "icon": null,
    "category_icon": null,
    "ui_schema": null,
    "is_trigger": false,
    "trigger_config": null,
    "is_integration": false,
    "provider_id": null,
    "provider_name": null
  }
}

cURL Example

curl -X GET "https://api.blocktion.io/api/blocks/{block_id}" \
  -H "Authorization: Bearer <your_access_token>"

POST/api/blocks

Create Block

Create a new block

Request Body

{
  "name": "string (required)",
  "description": "string (optional)",
  "is_system": "boolean (optional, default: false)",
  "is_template": "boolean (optional, default: false)",
  "handler": "string (required)",
  "action": "string (optional)",
  "parameters": "Record<string, Parameter> (optional)",
  "outputs": "Record<string, Output> (optional)",
  "ui_schema": "object (optional)",
  "icon": "string (optional)",
  "color": "string (optional)",
  "tags": "string[] (optional)",
  "is_integration": "boolean (optional)",
  "provider_id": "string (optional)",
  "provider_name": "string (optional)"
}

Response

{
  "data": {
    "id": "block_123456",
    "name": "Send Email Block",
    "description": "A powerful block for sending emails via SMTP",
    "is_system": false,
    "is_template": false,
    "parameters": {},
    "outputs": {},
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "user_id": "user_123",
    "handler": "email_handler",
    "action": "send_email",
    "tags": [
      "communication"
    ]
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/blocks" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "name": "string (required)",
  "description": "string (optional)",
  "is_system": "boolean (optional, default: false)",
  "is_template": "boolean (optional, default: false)",
  "handler": "string (required)",
  "action": "string (optional)",
  "parameters": "Record<string, Parameter> (optional)",
  "outputs": "Record<string, Output> (optional)",
  "ui_schema": "object (optional)",
  "icon": "string (optional)",
  "color": "string (optional)",
  "tags": "string[] (optional)",
  "is_integration": "boolean (optional)",
  "provider_id": "string (optional)",
  "provider_name": "string (optional)"
}'

POST/api/blocks/clone/{system_block_id}

Clone System Block

Clone a system block to a user block

Response

{
  "data": {
    "id": "block_789",
    "name": "Cloned System Block"
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/blocks/clone/{system_block_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>"

PUT/api/blocks/{block_id}

Update Block

Update an existing block

Request Body

{
  "name": "string (optional)",
  "description": "string (optional)",
  "parameters": "Record<string, Parameter> (optional)",
  "outputs": "Record<string, Output> (optional)",
  "handler": "string (optional)",
  "action": "string (optional)",
  "tags": "string[] (optional)",
  "is_integration": "boolean (optional)",
  "provider_id": "string (optional)",
  "provider_name": "string (optional)"
}

Response

{
  "data": {
    "id": "block_123456",
    "name": "Send Email Block"
  }
}

cURL Example

curl -X PUT "https://api.blocktion.io/api/blocks/{block_id}" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "name": "string (optional)",
  "description": "string (optional)",
  "parameters": "Record<string, Parameter> (optional)",
  "outputs": "Record<string, Output> (optional)",
  "handler": "string (optional)",
  "action": "string (optional)",
  "tags": "string[] (optional)",
  "is_integration": "boolean (optional)",
  "provider_id": "string (optional)",
  "provider_name": "string (optional)"
}'

DELETE/api/blocks/{block_id}

Delete Block

Delete a block

Response

{
  "data": {
    "success": true,
    "id": "block_123456"
  }
}

cURL Example

curl -X DELETE "https://api.blocktion.io/api/blocks/{block_id}" \
  -H "Authorization: Bearer <your_access_token>"

POST/api/blocks/{block_id}/execute

Execute Block

Execute a block with inputs

Request Body

{
  "inputs": "object (required)"
}

Response

{
  "data": {
    "success": true,
    "output": {}
  }
}

cURL Example

curl -X POST "https://api.blocktion.io/api/blocks/{block_id}/execute" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
  "inputs": "object (required)"
}'

POST/api/blocks/{block_id}/publish

Publish Block

Publish a block to the marketplace

Response

{
  "data": {
    "block_id": "block_123456",
    "status": "published"
  },
  "message": "Block published successfully"
}

cURL Example

curl -X POST "https://api.blocktion.io/api/blocks/{block_id}/publish" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>"

Best Practices

Guidelines for creating and using blocks effectively

Block Design

• Keep blocks focused on a single responsibility
• Use descriptive names and clear documentation
• Validate input parameters thoroughly
• Handle errors gracefully with meaningful messages

Performance

• Optimize for execution speed and memory usage
• Use caching for expensive operations
• Implement proper timeout handling
• Monitor block execution metrics

Documentation

Blocks

What is a Block?

Block Aspects

Ownership

System Blocks

User Blocks

Purpose

Trigger Blocks

Regular Blocks

Integration

Integration Blocks

Standalone Blocks

Reusability

Template Blocks

Instance Blocks

Block Tags

HTTP & Networking

Data & Storage

Triggers

Integrations

Code & AI

Communication

Overview

Block Structure

Key Features

Example Block Combinations

Endpoints

List Blocks

Query Parameters

Response

cURL Example

List System Blocks

Query Parameters

Response

cURL Example

Get Block

Response

cURL Example

Create Block

Request Body

Response

cURL Example

Clone System Block

Response

cURL Example

Update Block

Request Body

Response

cURL Example

Delete Block

Response

cURL Example

Execute Block

Request Body

Response

cURL Example

Publish Block

Response

cURL Example

Best Practices

Block Design

Performance