Projects API - Activepieces

Overview

The Projects API allows you to create and manage projects (workspaces) within your platform. Projects are isolated environments where flows, connections, and runs are organized. Each project can have multiple users and its own configuration.

Base Endpoint

GET    /api/v1/projects
POST   /api/v1/projects
GET    /api/v1/projects/:id
POST   /api/v1/projects/:id
DELETE /api/v1/projects/:id

List Projects

Retrieve a paginated list of projects for your platform.

curl https://cloud.activepieces.com/api/v1/projects \
  -H "Authorization: Bearer sk-your-api-key"

Query Parameters

externalId

string

Filter by external ID (useful for integration with external systems)

displayName

string

Search projects by name (partial match)

types

array

Filter by project type: TEAM, PERSONAL

limit

number

default:"50"

Number of projects to return (1-100)

cursor

string

Pagination cursor from previous response

Response

data

array

Array of project objects with limits and analytics

Show Project Object

string

Unique identifier for the project

ownerId

string

User ID of the project owner

displayName

string

Display name of the project

platformId

string

Platform ID this project belongs to

type

enum

Project type: TEAM or PERSONAL

externalId

string

External identifier for integration with other systems

maxConcurrentJobs

number

Maximum number of concurrent flow runs allowed

releasesEnabled

boolean

Whether git-based releases are enabled

metadata

object

Custom metadata attached to the project

icon

object

Project icon configuration

color

enum

Icon color: RED, BLUE, YELLOW, PURPLE, GREEN, PINK, VIOLET, ORANGE, DARK_GREEN, CYAN, LAVENDER, DEEP_ORANGE

plan

object

Project plan configuration

piecesFilterType

enum

How pieces (integrations) are filtered: NONE, ALLOWED

pieces

array

List of allowed piece names (when filter type is ALLOWED)

locked

boolean

Whether the plan is locked from editing

analytics

object

Project usage analytics

totalUsers

number

Total number of users in the project

activeUsers

number

Number of active users

totalFlows

number

Total number of flows

activeFlows

number

Number of enabled flows

created

string

ISO 8601 timestamp of creation

updated

string

ISO 8601 timestamp of last update

string

Cursor for next page

string

Cursor for previous page

Response Example

{
  "data": [
    {
      "id": "project_abc123",
      "ownerId": "user_xyz789",
      "displayName": "Marketing Automation",
      "platformId": "platform_456",
      "type": "TEAM",
      "externalId": "ext_marketing_01",
      "maxConcurrentJobs": 10,
      "releasesEnabled": true,
      "metadata": {
        "department": "marketing",
        "region": "us-west"
      },
      "icon": {
        "color": "BLUE"
      },
      "plan": {
        "id": "plan_123",
        "projectId": "project_abc123",
        "name": "Team Plan",
        "piecesFilterType": "ALLOWED",
        "pieces": ["@activepieces/piece-slack", "@activepieces/piece-gmail"],
        "locked": false,
        "created": "2024-01-10T10:00:00.000Z",
        "updated": "2024-01-10T10:00:00.000Z"
      },
      "analytics": {
        "totalUsers": 8,
        "activeUsers": 5,
        "totalFlows": 24,
        "activeFlows": 18
      },
      "created": "2024-01-10T10:00:00.000Z",
      "updated": "2024-01-15T14:30:00.000Z"
    }
  ],
  "next": null,
  "previous": null
}

Create Project

Create a new team project on your platform.

curl -X POST https://cloud.activepieces.com/api/v1/projects \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Sales Team",
    "externalId": "ext_sales_01",
    "maxConcurrentJobs": 5
  }'

Request Body

displayName

string

required

Name of the project. Must match pattern: alphanumeric, spaces, hyphens, underscores only

externalId

string

External identifier for integration. Must be unique across the platform

metadata

object

Custom metadata to store with the project

maxConcurrentJobs

number

Maximum number of flow runs that can execute concurrently

globalConnectionExternalIds

array

Array of global connection external IDs to pre-assign to this project

Response

Returns the created project with plan and analytics (status code 201).

Project Types:

PERSONAL - Automatically created for each user, cannot be deleted
TEAM - Created via API or UI, can have multiple members

You can only create TEAM projects via the API.

Get Project

Retrieve details about a specific project.

curl https://cloud.activepieces.com/api/v1/projects/project_abc123 \
  -H "Authorization: Bearer sk-your-api-key"

Path Parameters

string

required

The project ID

Response

Returns the project object with plan and analytics.

Update Project

Update project configuration and settings.

curl -X POST https://cloud.activepieces.com/api/v1/projects/project_abc123 \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Sales & Marketing",
    "releasesEnabled": true,
    "plan": {
      "piecesFilterType": "ALLOWED",
      "pieces": ["@activepieces/piece-slack", "@activepieces/piece-hubspot"]
    }
  }'

Path Parameters

string

required

The project ID

Request Body

displayName

string

New display name for the project

externalId

string

Update external ID (platform admins only)

metadata

object

Update custom metadata

releasesEnabled

boolean

Enable or disable git-based releases

icon

object

Update project icon

icon.color

enum

Icon color name

plan

object

Update project plan settings

plan.piecesFilterType

enum

Set to ALLOWED to whitelist pieces, or NONE to allow all

plan.pieces

array

Array of allowed piece names (when filter type is ALLOWED)

globalConnectionExternalIds

array

Update global connections assigned to this project

Response

Returns the updated project object.

Authorization Note:Only platform admins can update externalId. Regular project members with appropriate permissions can update other fields.

Delete Project

Permanently delete a team project.

curl -X DELETE https://cloud.activepieces.com/api/v1/projects/project_abc123 \
  -H "Authorization: Bearer sk-your-api-key"

Path Parameters

string

required

The project ID to delete

Response

Returns 204 No Content on successful deletion.

Deletion Restrictions:

Personal projects cannot be deleted
Only platform admins can delete projects
Deletion is permanent and cannot be undone
All flows, runs, and connections in the project will be deleted

Project Plan Limits

Projects can have different plan limits based on your platform edition:

Team Projects Limits

Edition	Team Projects Allowed
Community	None (requires upgrade)
Pro	1 team project
Enterprise	Unlimited

Attempting to create more team projects than allowed will result in an error:

{
  "statusCode": 400,
  "code": "FEATURE_DISABLED",
  "params": {
    "message": "Maximum limit of 1 team project reached for this plan. Upgrade your plan to add more team projects."
  }
}

Pieces Filter (Integrations Control)

Control which integrations (pieces) are available in a project:

Allow All Pieces

{
  "plan": {
    "piecesFilterType": "NONE"
  }
}

Whitelist Specific Pieces

{
  "plan": {
    "piecesFilterType": "ALLOWED",
    "pieces": [
      "@activepieces/piece-slack",
      "@activepieces/piece-gmail",
      "@activepieces/piece-sheets"
    ]
  }
}

Use piece filtering to:

Restrict integrations for security/compliance
Simplify the UI for specific teams
Control costs for paid integrations

Global Connections

Assign platform-level (global) connections to projects:

{
  "globalConnectionExternalIds": [
    "ext_conn_shared_slack",
    "ext_conn_company_gmail"
  ]
}

Global connections:

Are managed at the platform level
Can be shared across multiple projects
Useful for company-wide integrations
Reduce duplicate connection setup

Concurrent Jobs Limit

Control resource usage by limiting concurrent flow runs:

{
  "maxConcurrentJobs": 10
}

Set to null for unlimited concurrent jobs
Use limits to prevent resource exhaustion
Runs exceeding the limit are queued

Error Responses

Project Not Found (404)

{
  "statusCode": 404,
  "code": "ENTITY_NOT_FOUND",
  "params": {
    "entityType": "project",
    "entityId": "project_abc123",
    "message": "Project not found"
  }
}

Cannot Delete Personal Project (400)

{
  "statusCode": 400,
  "code": "VALIDATION",
  "params": {
    "message": "Personal projects cannot be deleted"
  }
}

Team Projects Limit Reached (400)

{
  "statusCode": 400,
  "code": "FEATURE_DISABLED",
  "params": {
    "message": "Maximum limit of 1 team project reached for this plan."
  }
}

Best Practices

Project Organization

Use TEAM projects for departments or product lines
Set meaningful displayName values
Use metadata to store organizational info (cost center, owner email)
Leverage externalId for integration with external systems

Resource Management

Set maxConcurrentJobs based on expected load
Monitor analytics to track usage
Use piece filtering to control integration sprawl
Regularly review and archive inactive projects

Security & Governance

Use piece filtering to enforce allowed integrations
Assign global connections for sensitive credentials
Enable releasesEnabled for version-controlled deployments
Document project purpose in metadata

Multi-tenancy

Use one project per customer/tenant
Set unique externalId for each tenant
Store tenant metadata in project metadata
Configure appropriate concurrent job limits per tenant

Code Examples

import axios from 'axios';

const client = axios.create({
  baseURL: 'https://cloud.activepieces.com/api/v1',
  headers: {
    'Authorization': `Bearer ${process.env.ACTIVEPIECES_API_KEY}`
  }
});

// Create a new team project
const project = await client.post('/projects', {
  displayName: 'Customer Support',
  externalId: 'ext_support_team',
  maxConcurrentJobs: 15,
  metadata: {
    department: 'support',
    tier: 'premium'
  }
});

console.log('Created project:', project.data.id);

// Configure allowed integrations
await client.post(`/projects/${project.data.id}`, {
  plan: {
    piecesFilterType: 'ALLOWED',
    pieces: [
      '@activepieces/piece-slack',
      '@activepieces/piece-zendesk',
      '@activepieces/piece-gmail'
    ]
  }
});

console.log('Configured integrations');

// Get project analytics
const updated = await client.get(`/projects/${project.data.id}`);
console.log('Analytics:', updated.data.analytics);

Project Members

For managing project members, see the Project Members API documentation.

Flows API

Manage flows within projects

Connections API

Manage project connections

Overview

Endpoints

​Overview

​Base Endpoint

​List Projects

​Query Parameters

​Response

​Create Project

​Request Body

​Response

​Get Project

​Path Parameters

​Response

​Update Project

​Path Parameters

​Request Body

​Response

​Delete Project

​Path Parameters

​Response

​Project Plan Limits

​Team Projects Limits

​Pieces Filter (Integrations Control)

​Allow All Pieces

​Whitelist Specific Pieces

​Global Connections

​Concurrent Jobs Limit

​Error Responses

​Project Not Found (404)

​Cannot Delete Personal Project (400)

​Team Projects Limit Reached (400)

​Best Practices

​Code Examples

​Project Members

​Related Endpoints

Flows API

Connections API

Overview

Base Endpoint

List Projects

Query Parameters

Response

Create Project

Request Body

Response

Get Project

Path Parameters

Response

Update Project

Path Parameters

Request Body

Response

Delete Project

Path Parameters

Response

Project Plan Limits

Team Projects Limits

Pieces Filter (Integrations Control)

Allow All Pieces

Whitelist Specific Pieces

Global Connections

Concurrent Jobs Limit

Error Responses

Project Not Found (404)

Cannot Delete Personal Project (400)

Team Projects Limit Reached (400)

Best Practices

Code Examples

Project Members

Related Endpoints