Flows API - Activepieces

Overview

The Flows API allows you to create, update, retrieve, and delete automation flows. Flows are the core building blocks of Activepieces automations, containing triggers and actions that define your workflow logic.

Base Endpoint

POST   /api/v1/flows
GET    /api/v1/flows
GET    /api/v1/flows/:id
POST   /api/v1/flows/:id
DELET  /api/v1/flows/:id

Create Flow

Create a new flow in your project.

curl -X POST https://cloud.activepieces.com/api/v1/flows \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My New Flow",
    "projectId": "project_123",
    "folderName": "Marketing Automations"
  }'

Request Body

displayName

string

required

Name of the flow that will be displayed in the UI

projectId

string

required

ID of the project where the flow will be created

folderId

string

ID of the folder to place the flow in. If provided, folderName is ignored

folderName

string

Name of the folder to create or use. Only used if folderId is not provided

templateId

string

ID of a template to use as a starting point for the flow

metadata

object

Custom metadata to attach to the flow. Useful for storing additional information

Response

string

Unique identifier for the flow

projectId

string

ID of the project containing the flow

externalId

string

External identifier for the flow (used for git sync)

ownerId

string

ID of the user who created the flow

folderId

string

ID of the folder containing the flow

status

enum

Current status of the flow: ENABLED or DISABLED

publishedVersionId

string

ID of the currently published version of the flow

version

object

The flow version object containing triggers and actions

Show version properties

string

Version identifier

displayName

string

Display name of the flow

trigger

object

The trigger configuration that starts the flow

valid

boolean

Whether the flow version is valid and can be published

schemaVersion

string

Schema version for the flow structure

updated

string

Timestamp of last update

updatedBy

string

User ID who last updated this version

created

string

ISO 8601 timestamp of when the flow was created

updated

string

ISO 8601 timestamp of when the flow was last updated

Response Example

{
  "id": "flow_abc123",
  "projectId": "project_123",
  "externalId": "ext_flow_456",
  "ownerId": "user_789",
  "folderId": "folder_101",
  "status": "DISABLED",
  "publishedVersionId": null,
  "metadata": null,
  "operationStatus": "NONE",
  "timeSavedPerRun": null,
  "templateId": null,
  "version": {
    "id": "version_xyz",
    "displayName": "My New Flow",
    "trigger": {
      "type": "EMPTY",
      "settings": {}
    },
    "valid": false,
    "schemaVersion": "1.0.0",
    "created": "2024-01-15T10:00:00.000Z",
    "updated": "2024-01-15T10:00:00.000Z"
  },
  "created": "2024-01-15T10:00:00.000Z",
  "updated": "2024-01-15T10:00:00.000Z"
}

List Flows

Retrieve a paginated list of flows in a project.

curl https://cloud.activepieces.com/api/v1/flows?projectId=project_123&limit=20 \
  -H "Authorization: Bearer sk-your-api-key"

Query Parameters

projectId

string

required

Filter flows by project ID

folderId

string

Filter flows by folder ID

status

array

Filter by flow status: ENABLED, DISABLED

name

string

Search flows by name (partial match)

versionState

enum

Filter by version state: DRAFT, LOCKED

externalIds

array

Filter flows by external IDs (for git sync)

connectionExternalIds

array

Filter flows that use specific connections

agentExternalIds

array

Filter flows that use specific agents

limit

number

default:"10"

Number of flows to return (1-100)

cursor

string

Pagination cursor from previous response

Response

{
  "data": [
    {
      "id": "flow_abc123",
      "projectId": "project_123",
      "externalId": "ext_flow_456",
      "status": "ENABLED",
      "version": {
        "displayName": "Customer Onboarding",
        "valid": true
      },
      "created": "2024-01-10T10:00:00.000Z",
      "updated": "2024-01-15T14:30:00.000Z"
    },
    {
      "id": "flow_def789",
      "projectId": "project_123",
      "externalId": "ext_flow_789",
      "status": "DISABLED",
      "version": {
        "displayName": "Weekly Report",
        "valid": true
      },
      "created": "2024-01-12T09:00:00.000Z",
      "updated": "2024-01-14T16:00:00.000Z"
    }
  ],
  "next": "eyJpZCI6ImZsb3dfZGVmNzg5In0=",
  "previous": null
}

Get Flow

Retrieve a specific flow by ID.

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

Path Parameters

string

required

The flow ID

Query Parameters

versionId

string

Optional version ID to retrieve a specific version instead of the latest

Response

Returns the full flow object with the populated version.

Update Flow (Operations)

Apply operations to modify a flow. This endpoint handles various operations like changing status, importing flow definitions, and more.

curl -X POST https://cloud.activepieces.com/api/v1/flows/flow_abc123 \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "CHANGE_STATUS",
    "request": {
      "status": "ENABLED"
    }
  }'

Flow Operations

Change Status
Import Flow
Lock and Publish

Enable or disable a flow.

{
  "type": "CHANGE_STATUS",
  "request": {
    "status": "ENABLED"
  }
}

request.status

enum

required

New status: ENABLED or DISABLED

Import a flow definition (e.g., from template or export).

{
  "type": "IMPORT_FLOW",
  "request": {
    "displayName": "Imported Flow",
    "trigger": { /* trigger config */ },
    "schemaVersion": "1.0.0",
    "notes": []
  }
}

Sample data is automatically cleared during import for security.

Lock the current version and publish it.

{
  "type": "LOCK_AND_PUBLISH",
  "request": {}
}

This operation:

Locks the current draft version
Sets it as the published version
Enables the flow if it was disabled

The flow cannot be modified if it was updated by another user within the last minute. This prevents concurrent editing conflicts.

Count Flows

Get the count of flows in a folder or project.

curl https://cloud.activepieces.com/api/v1/flows/count?projectId=project_123&folderId=folder_101 \
  -H "Authorization: Bearer sk-your-api-key"

Query Parameters

projectId

string

required

Project ID

folderId

string

Optional folder ID to count flows in a specific folder

Response

{
  "count": 15
}

Export Flow as Template

Export a flow as a reusable template.

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

Response

Returns a SharedTemplate object that can be imported into other flows or shared.

{
  "name": "Customer Onboarding Template",
  "description": "Automated customer onboarding workflow",
  "template": {
    "displayName": "Customer Onboarding",
    "trigger": { /* trigger config */ },
    "schemaVersion": "1.0.0"
  },
  "created": "2024-01-15T10:00:00.000Z"
}

Delete Flow

Permanently delete a flow.

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

Path Parameters

string

required

The flow ID to delete

Response

Returns 204 No Content on successful deletion.

Deleting a flow is permanent and cannot be undone. All flow runs and history will be preserved, but the flow definition will be deleted.

Flow Status Management

Enabling Flows

When enabling a flow:

The flow must have a valid trigger configured
Platform active flow limits are checked
Webhooks are registered if using webhook triggers
Scheduled triggers are set up if using schedule triggers

Disabling Flows

When disabling a flow:

Active runs continue to completion
New runs are prevented
Webhooks are unregistered
Scheduled triggers are paused

Active Flows Limit

Your platform has a limit on the number of active (enabled) flows based on your plan. Attempting to enable a flow when at the limit will return an error.

Error Responses

Flow In Use (409)

{
  "statusCode": 409,
  "code": "FLOW_IN_USE",
  "params": {
    "flowVersionId": "version_xyz",
    "message": "Flow is being used by another user in the last minute. Please try again later."
  }
}

Flow Not Found (404)

{
  "statusCode": 404,
  "code": "ENTITY_NOT_FOUND",
  "params": {
    "entityType": "flow",
    "entityId": "flow_abc123",
    "message": "Flow not found"
  }
}

Best Practices

Folder Organization

Use folders to organize flows by team, department, or use case
Create folders with descriptive names
Leverage folderName parameter for automatic folder creation

Metadata Usage

Store custom tags, categories, or identifiers in metadata
Use metadata for integration with external systems
Keep metadata size reasonable (< 1KB recommended)

Version Control

Use externalId for git synchronization
Export flows as templates for backup
Test flows in disabled state before enabling

Performance

Use pagination cursors for large flow lists
Filter by folder or status to reduce response size
Cache flow definitions when possible

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 flow
const newFlow = await client.post('/flows', {
  displayName: 'Slack Notification',
  projectId: 'project_123',
  folderName: 'Notifications'
});

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

// Enable the flow
await client.post(`/flows/${newFlow.data.id}`, {
  type: 'CHANGE_STATUS',
  request: { status: 'ENABLED' }
});

console.log('Flow enabled!');

Flow Runs

Execute and monitor flow runs

Connections

Manage connections used in flows

Overview

Endpoints

​Overview

​Base Endpoint

​Create Flow

​Request Body

​Response

​List Flows

​Query Parameters

​Response

​Get Flow

​Path Parameters

​Query Parameters

​Response

​Update Flow (Operations)

​Flow Operations

​Count Flows

​Query Parameters

​Response

​Export Flow as Template

​Response

​Delete Flow

​Path Parameters

​Response

​Flow Status Management

​Enabling Flows

​Disabling Flows

​Active Flows Limit

​Error Responses

​Flow In Use (409)

​Flow Not Found (404)

​Best Practices

​Code Examples

​Related Endpoints

Flow Runs

Connections

Overview

Base Endpoint

Create Flow

Request Body

Response

List Flows

Query Parameters

Response

Get Flow

Path Parameters

Query Parameters

Response

Update Flow (Operations)

Flow Operations

Count Flows

Query Parameters

Response

Export Flow as Template

Response

Delete Flow

Path Parameters

Response

Flow Status Management

Enabling Flows

Disabling Flows

Active Flows Limit

Error Responses

Flow In Use (409)

Flow Not Found (404)

Best Practices

Code Examples

Related Endpoints