Skip to main content
Projects in Activepieces are isolated workspaces that contain flows, connections, and team members. They enable multi-tenancy and resource isolation in your platform.

​
Project Types

Activepieces supports two types of projects:

Team Projects

Shared workspaces where multiple users collaborate on flows and automations.

Personal Projects

Individual workspaces for single users with dedicated resources.

​
Creating Projects

1

Define Project Details

Set the project display name, type, and optional metadata:
{
  displayName: "Marketing Team",
  type: ProjectType.TEAM,
  platformId: "platform_123",
  icon: {
    color: ColorName.BLUE
  }
}
2

Configure Project Icon

Choose from 12 predefined color themes:
  • RED, BLUE, YELLOW, PURPLE, GREEN, PINK
  • VIOLET, ORANGE, DARK_GREEN, CYAN
  • LAVENDER, DEEP_ORANGE
3

Set Resource Limits

Configure concurrent job limits for the project:
{
  maxConcurrentJobs: 10  // Limit parallel flow executions
}

​
Project Structure

Each project maintains isolated resources:

​
Core Components

  • Flows: Automation workflows specific to the project
  • Connections: API credentials and integrations
  • Members: Users with assigned roles and permissions
  • Folders: Organization structure for flows
  • Tables: Data storage within the project
  • Runs: Execution history and logs

​
Project Metadata

{
  id: "proj_abc123",
  displayName: "Marketing Team",
  platformId: "platform_123",
  ownerId: "user_owner",
  type: ProjectType.TEAM,
  releasesEnabled: true,
  created: "2026-03-01T00:00:00.000Z",
  updated: "2026-03-03T00:00:00.000Z"
}

​
Multi-Tenancy

Activepieces provides strong isolation between projects:
Each project has completely isolated:
  • Flow definitions and versions
  • Connection credentials
  • Run history and logs
  • User access controls
Projects can have independent:
  • Concurrent execution limits
  • Piece allowlists
  • Custom domains
  • Webhook endpoints
Users require explicit membership:
  • Project-specific roles
  • Permission-based access
  • Audit trail per project

​
Project Plans

Configure piece filtering and restrictions per project: 
{
  projectId: "proj_abc123",
  name: "Enterprise Plan",
  piecesFilterType: PiecesFilterType.ALLOWED,
  pieces: ["@activepieces/piece-slack", "@activepieces/piece-gmail"],
  locked: false
}

​
Filter Types

PiecesFilterType.NONE  // All pieces available
Piece filtering allows you to control which integrations are available to each project, useful for security compliance or custom pricing tiers.

​
Project Analytics

Track project usage and activity: 
{
  totalUsers: 8,
  activeUsers: 5,
  totalFlows: 23,
  activeFlows: 15
}

​
External IDs

Link projects to your external systems: 
{
  projectId: "proj_abc123",
  externalId: "org_456_workspace_789"  // Your system's identifier
}
External IDs are optional but recommended for integration with your existing user management or billing systems.

​
Project Releases

Enable version control for projects: 
{
  releasesEnabled: true  // Enable Git-sync and versioning
}
When enabled, projects support:
  • Flow version control
  • Git synchronization
  • State snapshots
  • Deployment pipelines
See Project Releases for details.

​
Soft Deletion

Deleted projects are soft-deleted for recovery: 
{
  deleted: "2026-03-03T00:00:00.000Z"  // Timestamp when deleted
}
Soft-deleted projects can be restored within your retention period. They don’t appear in normal queries but remain in the database.

​
API Reference

Common project operations via API: 
curl -X GET 'https://api.activepieces.com/v1/projects/{projectId}' \
  -H 'Authorization: Bearer {token}'

​
Best Practices

Naming Conventions

Use clear, descriptive names that reflect team or department structure.

Resource Limits

Set appropriate concurrent job limits based on expected workload.

External Mapping

Always set externalId to link with your existing systems.

Plan Management

Use piece allowlists to enforce security and compliance policies.

Users & Permissions

Manage team members and roles

Pieces Management

Control available integrations

Audit Logs

Track project activity