---
name: activepieces
description: Use when building AI automation workflows, creating agents that
  handle variable tasks, designing flows with triggers and actions, managing
  data in tables, integrating with 760+ apps, or setting up governance and
  security controls for automation platforms.
metadata:
  mintlify-proj: activepieces
  version: "1.0"
---

# Activepieces Skill

## Product Summary

Activepieces is an AI automation platform for building workflows, agents, and data tables with governance built in. Agents handle variable tasks using natural language instructions; flows execute deterministic sequences triggered by schedules, webhooks, or events; tables store structured data for flows and agents to reference. The platform supports 760+ integrations (Slack, Gmail, Google Sheets, Notion, HubSpot, Salesforce, OpenAI, etc.) and runs on your own infrastructure or Activepieces Cloud. Access the full documentation at https://www.activepieces.com/docs. Key entry points: **Flows** (trigger + actions), **Agents** (AI workers with tools), **Tables** (persistent data), **MCP Server** (connect Claude, Cursor, Copilot, Gemini CLI, Windsurf, Zed), **API** (REST endpoints for programmatic control).

## When to Use

Reach for this skill when:
- **Building flows**: User asks to automate a sequence (e.g., "send Slack when new Gmail arrives")
- **Creating agents**: User needs AI to handle variable tasks (e.g., "triage support tickets" where each ticket differs)
- **Managing data**: User needs to store, query, or trigger on table records
- **Integrating apps**: User wants to connect services or build multi-step automations
- **Setting up governance**: Admin needs to control who builds what, which apps are available, where credentials live
- **Using MCP**: User wants to build flows from Claude, Cursor, or other AI clients
- **Debugging runs**: User needs to inspect why a flow failed or what data it produced
- **Publishing safely**: User needs approval gates or versioning for sensitive automations

## Quick Reference

### Core Concepts

| Concept | Purpose | When to Use |
|---------|---------|------------|
| **Flow** | Trigger + sequential actions | Deterministic, repeatable tasks (e.g., "every day at 9am, send report") |
| **Agent** | AI that decides which tools to use | Variable tasks (e.g., "handle this support ticket however it needs") |
| **Table** | Rows and columns of data | Store leads, invoices, decisions; trigger flows on new records |
| **Piece** | Integration with an app (Slack, Gmail, etc.) | Connect to external services; 760+ available |
| **Connection** | Authenticated credential for a piece | OAuth2, API key, or basic auth to a service |
| **Trigger** | Flow's starting point | Schedule, webhook, event, or new table record |
| **Action** | Step that runs after trigger | Call a piece, write to table, branch, run agent, etc. |

### Flow Building Essentials

- **Trigger types**: Schedule (cron), Webhook (HTTP POST), Event (piece-specific like "new Gmail"), Table (new/updated record)
- **Data passing**: Use `{{step_name.field}}` to reference previous step output; available in Data Selector
- **Formulas**: Type `/` in any text input to insert functions (combine, if, coalesce, format_date, etc.)
- **Publishing**: Draft mode is editable; publish to activate. Sensitive projects require approval.
- **Versioning**: Published versions are locked; drafts can be edited without affecting live flow

### Agent Essentials

- **Tools**: Any piece action becomes a tool (e.g., "send Slack message", "create Google Sheet row")
- **Knowledge**: Upload files (PDF, DOCX, TXT, CSV) or link tables for grounding
- **Project scope**: Agent can only reach connections, flows, and tables in its project
- **Structured output**: Ask agent for specific fields (category, urgency, needs_human) to branch on in flows

### Table Essentials

- **Field types**: Text, Number, Date, Date & Time, Dropdown (fixed options)
- **Triggers**: "New record" or "Updated record" can start flows
- **In flows**: Read records, write records, update records, delete records, clear table
- **With agents**: Tables become knowledge base for agent lookups and grounding

### API & MCP

- **Authentication**: Bearer token in Authorization header (Platform/Enterprise only for API keys)
- **Pagination**: Seek-based with `limit` and `cursor` query params
- **MCP Server**: Enable in Settings → MCP Server, copy URL, add to Claude/Cursor/Copilot config
- **MCP tools**: Discovery (read-only), Flow Management, Flow Building, Router & Branching, Tables, Testing & Runs

## Decision Guidance

### Flow vs. Agent

| Scenario | Use Flow | Use Agent |
|----------|----------|-----------|
| Logic is known and fixed | ✓ | |
| Same input always produces same steps | ✓ | |
| Task varies by situation | | ✓ |
| Need to branch on prose/judgment | | ✓ |
| Need deterministic audit trail | ✓ | |
| Need to handle edge cases flexibly | | ✓ |

### Trigger Type Selection

| Trigger | Use When | Example |
|---------|----------|---------|
| Schedule | Recurring at fixed times | Daily report at 9am |
| Webhook | External system pushes data | Typeform submission arrives |
| Event | Service-specific event | New Gmail, new Slack message |
| Table | Data changes in Activepieces | New lead added to table |

### Data Passing vs. Variables

| Approach | Use When |
|----------|----------|
| `{{step_name.field}}` | Reference output from earlier steps in same flow |
| `{{variables['NAME']}}` | Store encrypted secrets or config once, reuse across flows |
| Formulas (combine, if, etc.) | Transform data before using it |

### Router vs. AI Router

| Type | Use When |
|------|----------|
| Conditional Router | Logic is clear and rule-based (e.g., if amount > 1000) |
| AI Router | Decision is judgment-based (e.g., "is this urgent?") |

## Workflow

### Building a Flow

1. **Understand the requirement**: What triggers it? What should each step do? Where does data come from?
2. **Choose a trigger**: Schedule, webhook, event, or table record
3. **Add actions**: Click + to add steps; search for piece actions (Slack, Gmail, Google Sheets, etc.)
4. **Configure each step**: Fill in inputs; use Data Selector to reference previous steps
5. **Use formulas**: Type `/` to transform data (combine names, format dates, branch on conditions)
6. **Test**: Run the flow manually to check outputs
7. **Publish**: Click Publish to activate; sensitive projects require approval
8. **Monitor**: Go to Runs to inspect execution and debug failures

### Creating an Agent

1. **Identify the task**: What job does the agent do? What varies each time?
2. **Click New Agent**: Choose project (or it goes to your personal project)
3. **Pick a model**: Select from available AI providers
4. **Write the brief**: Plain language description of the job
5. **Add tools**: Select which piece actions the agent can call
6. **Add knowledge** (optional): Upload files or link tables for grounding
7. **Test**: Chat with the agent to verify it understands the task
8. **Use in flows**: Drop the agent as a step and ask for structured output

### Setting Up a Table

1. **Create table**: Click Tables, then New Table
2. **Add fields**: Text, Number, Date, Date & Time, or Dropdown
3. **Import data** (optional): Upload CSV or JSON template
4. **Use in flows**: Read records, write records, update records
5. **Trigger flows**: Enable "New record" or "Updated record" trigger
6. **Use with agents**: Add as knowledge source in agent editor

### Connecting via MCP

1. **Enable MCP Server**: Settings → MCP Server → Toggle on → Copy URL
2. **Add to client config**: Paste URL into Claude, Cursor, Copilot, etc.
3. **Authenticate**: First use opens browser for OAuth
4. **Build with AI**: Ask Claude to create flows, manage tables, test runs

## Common Gotchas

- **Formulas use semicolons, not commas**: `combine(first; last; -)` not `combine(first, last, -)`
- **Empty strings need quotes**: `coalesce(""; fallback)` not `coalesce(; fallback)`
- **Published flows are locked**: Edit in draft mode; publish creates a new version
- **Agents are project-scoped**: An agent can only reach connections, flows, and tables in its project
- **Data Selector is your friend**: Don't type `{{step_name.field}}` manually; use the Data Selector to avoid typos
- **Connections are per-project**: Two projects with the same Gmail connection name are two different mailboxes
- **Tables need pgvector for knowledge**: Agents can't use tables as knowledge base without pgvector extension
- **Piece versions are pinned**: Flows don't auto-upgrade; you upgrade explicitly in the builder
- **Sensitive projects require approval**: Publishing a flow in a Sensitive project needs review unless you're an admin
- **MCP tools cost credits**: `ap_run_action` costs 1 credit per call; flow runs are billed normally
- **Secrets are write-only**: API responses never contain variable values; only signed-in users can reveal them

## Verification Checklist

Before submitting a flow or agent:

- [ ] **Trigger is correct**: Schedule, webhook, event, or table record as intended
- [ ] **All steps have valid inputs**: No red error badges; Data Selector shows available fields
- [ ] **Formulas are syntactically correct**: Preview panel shows expected output, no errors
- [ ] **Connections are authenticated**: No "Missing" or "Error" status in connection list
- [ ] **Data flows correctly**: Test run shows expected output at each step
- [ ] **Sensitive data is handled**: Credentials in variables, not hardcoded; secrets never logged
- [ ] **Agent has tools and knowledge**: If using agent, verify tools are selected and knowledge is available
- [ ] **Approval gate is ready**: If project is Sensitive, ensure approvers are assigned
- [ ] **Versioning is clear**: Published version is stable; draft has new changes
- [ ] **Run history is clean**: No repeated failures; debug any errors before publishing

## Resources

- **Comprehensive navigation**: https://www.activepieces.com/docs/llms.txt — page-by-page reference for all docs
- **Building flows**: https://www.activepieces.com/docs/flows/building-flows
- **Creating agents**: https://www.activepieces.com/docs/agents/overview
- **API reference**: https://www.activepieces.com/docs/endpoints/overview

---

> For additional documentation and navigation, see: https://www.activepieces.com/docs/llms.txt