Understanding Pieces

Pieces are the building blocks of Activepieces - they’re integrations that connect your workflows to external services and APIs. With over 600 pieces available, you can integrate with nearly any service, and if one doesn’t exist, you can easily create your own using TypeScript.

What are Pieces?

A piece is a packaged integration that provides:

Actions: Operations you can perform (send email, create record, etc.)
Triggers: Events that start flows (new email, form submission, etc.)
Authentication: Secure connection management
Properties: Configurable inputs for actions and triggers

Piece Structure

Based on the Activepieces framework source code, here’s how pieces are defined:

import { createPiece, PieceAuth } from '@activepieces/pieces-framework';

export const myPiece = createPiece({
  displayName: 'My Service',
  description: 'Integration with My Service',
  auth: PieceAuth.OAuth2({
    authUrl: 'https://api.myservice.com/oauth/authorize',
    tokenUrl: 'https://api.myservice.com/oauth/token',
    required: true,
    scope: ['read', 'write']
  }),
  minimumSupportedRelease: '0.30.0',
  logoUrl: 'https://cdn.activepieces.com/pieces/myservice.png',
  authors: ['YourName'],
  categories: [PieceCategory.PRODUCTIVITY],
  actions: [
    createRecordAction,
    updateRecordAction,
    deleteRecordAction
  ],
  triggers: [
    newRecordTrigger,
    updatedRecordTrigger
  ],
});

Types of Pieces

Activepieces organizes pieces into three categories:

Core Pieces

Core pieces are essential integrations maintained by the Activepieces team. Located in packages/pieces/core/, there are 26 core pieces including:

HTTP: Make requests to any API
Code: Write custom JavaScript/TypeScript
Schedule: Trigger flows on a schedule
Webhook: Receive HTTP requests
Data Mapper: Transform and manipulate data
AI: AI-powered text, image, and agent operations

Core pieces are:

Always available
Battle-tested and reliable
Maintained with every Activepieces release
Include fundamental workflow operations

Community Pieces

Community pieces are integrations contributed by the open source community. Located in packages/pieces/community/, there are 597+ community pieces including:

Google Sheets, Gmail, Google Drive
Slack, Discord, Microsoft Teams
OpenAI, Anthropic, Replicate
Airtable, Notion, Asana
Stripe, PayPal, Shopify
And hundreds more!

Over 95% of Activepieces pieces are contributed by the community, making it one of the most contributor-friendly automation platforms.

Community pieces are:

Open source and published to npmjs.com
Independently versioned
Community-maintained
Constantly growing with new contributions

Custom Pieces

Custom pieces are private integrations you build for your specific needs. Located in packages/pieces/custom/, these pieces:

Stay private to your instance
Can be proprietary integrations
Work with internal APIs
Follow the same framework as community pieces

Piece Components

Authentication

Pieces support multiple authentication methods:

OAuth2

auth: PieceAuth.OAuth2({
  authUrl: 'https://api.service.com/oauth/authorize',
  tokenUrl: 'https://api.service.com/oauth/token',
  required: true,
  scope: ['read', 'write']
})

API Key

auth: PieceAuth.SecretText({
  displayName: 'API Key',
  description: 'Enter your API key from the service',
  required: true,
})

Basic Auth

auth: PieceAuth.BasicAuth({
  displayName: 'Credentials',
  required: true,
})

Custom Auth

auth: PieceAuth.CustomAuth({
  displayName: 'Connection',
  required: true,
  props: {
    apiKey: Property.ShortText({
      displayName: 'API Key',
      required: true,
    }),
    baseUrl: Property.ShortText({
      displayName: 'Base URL',
      required: true,
    }),
  },
})

No Auth

auth: PieceAuth.None()

Actions

Actions are operations your piece can perform. Example from the Activepieces Platform piece:

import { createAction, Property } from '@activepieces/pieces-framework';

export const createProject = createAction({
  name: 'create_project',
  displayName: 'Create Project',
  description: 'Creates a new project in Activepieces',
  auth: activePieceAuth,
  props: {
    displayName: Property.ShortText({
      displayName: 'Display Name',
      required: true,
    }),
    externalId: Property.ShortText({
      displayName: 'External ID',
      required: true,
    }),
  },
  async run(context) {
    const { displayName, externalId } = context.propsValue;
    const response = await httpClient.sendRequest({
      method: HttpMethod.POST,
      url: `${context.auth.baseApiUrl}/v1/projects`,
      headers: {
        Authorization: `Bearer ${context.auth.apiKey}`,
      },
      body: { displayName, externalId },
    });
    return response.body;
  },
});

Triggers

Triggers listen for events and start flows. They can be:

Polling Triggers

Check for new data on a schedule:

import { createTrigger, TriggerStrategy } from '@activepieces/pieces-framework';

export const newRecord = createTrigger({
  name: 'new_record',
  displayName: 'New Record',
  description: 'Triggers when a new record is created',
  type: TriggerStrategy.POLLING,
  props: {
    // Configuration properties
  },
  async onEnable(context) {
    // Setup when trigger is enabled
  },
  async onDisable(context) {
    // Cleanup when trigger is disabled
  },
  async run(context) {
    const lastCheck = context.propsValue.lastCheck;
    const newRecords = await fetchNewRecords(lastCheck);
    return newRecords;
  },
});

Webhook Triggers

Receive real-time events via webhooks:

export const newWebhook = createTrigger({
  name: 'new_webhook',
  displayName: 'New Webhook Event',
  type: TriggerStrategy.WEBHOOK,
  async onEnable(context) {
    // Register webhook with service
    await registerWebhook({
      url: context.webhookUrl,
      events: ['record.created']
    });
  },
  async onDisable(context) {
    // Unregister webhook
    await unregisterWebhook(context.webhookUrl);
  },
  async run(context) {
    return [context.payload.body];
  },
});

Properties

Properties define inputs for actions and triggers:

import { Property } from '@activepieces/pieces-framework';

// Text input
Property.ShortText({
  displayName: 'Email',
  required: true,
})

// Long text
Property.LongText({
  displayName: 'Description',
  required: false,
})

// Dropdown
Property.StaticDropdown({
  displayName: 'Priority',
  required: true,
  options: {
    options: [
      { label: 'Low', value: 'low' },
      { label: 'Medium', value: 'medium' },
      { label: 'High', value: 'high' },
    ]
  }
})

// Dynamic dropdown (fetched from API)
Property.Dropdown({
  displayName: 'Channel',
  required: true,
  refreshers: [],
  async options(context) {
    const channels = await fetchChannels(context.auth);
    return {
      options: channels.map(ch => ({
        label: ch.name,
        value: ch.id
      }))
    };
  },
})

// Number
Property.Number({
  displayName: 'Count',
  required: true,
})

// Checkbox
Property.Checkbox({
  displayName: 'Send Notification',
  required: false,
})

// Array
Property.Array({
  displayName: 'Items',
  required: true,
})

// Object/JSON
Property.Json({
  displayName: 'Configuration',
  required: false,
})

Piece Framework Features

Type Safety

The pieces framework is built with TypeScript and provides full type safety:

import { createPiece } from '@activepieces/pieces-framework';
import { PieceAuth } from '@activepieces/pieces-framework';

// TypeScript ensures correct structure
const myPiece = createPiece({
  displayName: 'My Piece',
  auth: PieceAuth.None(),
  actions: [], // Type-checked array of actions
  triggers: [], // Type-checked array of triggers
  // ... other required fields
});

NPM Package Distribution

All pieces are published as npm packages:

Naming: @activepieces/piece-{name}
Versioning: Follows semantic versioning
Distribution: Published to npmjs.com
Installation: Install like any npm package

{
  "name": "@activepieces/piece-slack",
  "version": "0.25.6",
  "dependencies": {
    "@activepieces/pieces-framework": "0.25.6",
    "@slack/web-api": "^7.9.0"
  }
}

Hot Reloading

During local development, pieces support hot reloading:

# Start dev environment with hot reloading
npm run dev

# Edit a piece file
# Changes are automatically reloaded

Context API

Pieces have access to a rich context object:

interface ActionContext {
  auth: AuthValue;           // Authentication credentials
  propsValue: PropsValue;    // Action input values
  store: Store;              // Persistent key-value store
  server: ServerContext;     // API access
  files: FilesService;       // File operations
  connections: Connections;  // Access other connections
}

MCP Server Integration

Every Activepieces piece automatically becomes available as an MCP (Model Context Protocol) server!

When you create a piece, it can be:

Used in Activepieces flows
Exposed as an MCP server tool
Called by AI assistants like Claude Desktop, Cursor, and Windsurf

Learn more in the MCP Servers documentation.

Building Your Own Piece

Creating a piece is straightforward:

Generate Piece Scaffold

npm run create-piece

Follow the prompts to set up your piece structure.

Define Authentication

Choose the appropriate auth method for your service.

Create Actions

Add operations users can perform.

Add Triggers

Set up event listeners if needed.

Test Locally

Use hot reloading to test your piece in real workflows.

Publish

Publish to npm and optionally contribute back to the community.

For detailed instructions, see the Building Pieces guide.

Piece Categories

Pieces are organized into categories for easy discovery:

Productivity: Google Workspace, Microsoft 365, Notion
Communication: Slack, Discord, Email services
Artificial Intelligence: OpenAI, Anthropic, AI utilities
Marketing: Mailchimp, SendGrid, social media
Developer Tools: GitHub, GitLab, API testing
E-commerce: Shopify, WooCommerce, Stripe
Business Intelligence: Analytics, reporting tools
And many more…

Piece Versioning

Each piece specifies its minimum supported Activepieces release:

createPiece({
  minimumSupportedRelease: '0.30.0',
  maximumSupportedRelease: '0.50.0', // Optional
  // ...
})

This ensures:

Compatibility with platform features
Breaking changes are communicated
Users know which version to use

Best Practices

Clear Naming

Use descriptive names for actions and triggers that clearly indicate what they do.

Good Descriptions

Write helpful descriptions for properties and include examples.

Error Handling

Handle errors gracefully and return helpful error messages.

Validation

Validate inputs before making API calls to fail fast.

Use Store

Leverage the store API for caching and state management.

Test Thoroughly

Test all actions and triggers with various inputs before publishing.

Next Steps

Build Your First Piece - Step-by-step guide
Piece Development Guide - Complete reference
MCP Integration - Connect pieces to AI
AI Pieces - Build AI-powered pieces

Getting Started

Core Concepts

Pieces

Understanding Pieces

What are Pieces?

Piece Structure

Types of Pieces

Core Pieces

Community Pieces

Custom Pieces

Piece Components

Authentication

OAuth2

API Key

Basic Auth

Custom Auth

No Auth

Actions

Triggers

Polling Triggers

Webhook Triggers

Properties

Piece Framework Features

Type Safety

NPM Package Distribution

Hot Reloading

Context API

MCP Server Integration

Building Your Own Piece

Piece Categories

Piece Versioning

Best Practices

Clear Naming

Good Descriptions

Error Handling

Validation

Use Store

Test Thoroughly

Next Steps

Getting Started

Core Concepts

​Understanding Pieces

​What are Pieces?

​Piece Structure

​Types of Pieces

​Core Pieces

​Community Pieces

​Custom Pieces

​Piece Components

​Authentication

​OAuth2

​API Key

​Basic Auth

​Custom Auth

​No Auth

​Actions

​Triggers

​Polling Triggers

​Webhook Triggers

​Properties

​Piece Framework Features

​Type Safety

​NPM Package Distribution

​Hot Reloading

​Context API

​MCP Server Integration

​Building Your Own Piece

​Piece Categories

​Piece Versioning

​Best Practices

Clear Naming

Good Descriptions

Error Handling

Validation

Use Store

Test Thoroughly

​Next Steps

Understanding Pieces

What are Pieces?

Piece Structure

Types of Pieces

Core Pieces

Community Pieces

Custom Pieces

Piece Components

Authentication

OAuth2

API Key

Basic Auth

Custom Auth

No Auth

Actions

Triggers

Polling Triggers

Webhook Triggers

Properties

Piece Framework Features

Type Safety

NPM Package Distribution

Hot Reloading

Context API

MCP Server Integration

Building Your Own Piece

Piece Categories

Piece Versioning

Best Practices

Next Steps