Workflows

Create, manage, deploy, and execute automation workflows. Workflows are composed of interconnected nodes that define data processing pipelines.

All endpoints require authentication via X-API-Key header and the appropriate scope.

Workflow Object

{
  "id": "wf_abc123",
  "name": "Daily ETL Pipeline",
  "description": "Extracts data from MySQL, transforms, and loads to S3",
  "status": "active",
  "version": 3,
  "nodes": [
    {
      "id": "node_1",
      "nodeId": "mysql-source",
      "label": "Extract Orders",
      "position": { "x": 100, "y": 200 },
      "config": {}
    }
  ],
  "connections": [
    {
      "sourceNodeId": "node_1",
      "sourcePort": "output",
      "targetNodeId": "node_2",
      "targetPort": "input"
    }
  ],
  "config": {},
  "settings": {
    "timeout": 3600,
    "retryOnFailure": true,
    "maxRetries": 3
  },
  "tags": ["etl", "production"],
  "organizationId": "org_xyz",
  "ownerId": "user_456",
  "sharedWith": ["user_789"],
  "isPublic": false,
  "isTemplate": false,
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

`GET` /api/v1/workflows

List all workflows accessible to the authenticated user.

Scope: workflows:read

Query Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter by status: `draft`, `active`, `paused`, `archived`
`tag`	string	No	Filter by tag
`search`	string	No	Search by name or description
`limit`	integer	No	Number of results to return (default: 20)
`offset`	integer	No	Number of results to skip (default: 0)
`sort`	string	No	Sort field and direction, e.g. `createdAt:desc`

Response 200 OK

{
  "count": 42,
  "limit": 20,
  "offset": 0,
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Daily ETL Pipeline",
      "description": "Extracts data from MySQL, transforms, and loads to S3",
      "status": "active",
      "version": 3,
      "tags": ["etl", "production"],
      "organizationId": "org_xyz",
      "ownerId": "user_456",
      "isPublic": false,
      "isTemplate": false,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-02-01T14:22:00Z"
    }
  ]
}

`POST` /api/v1/workflows

Create a new workflow.

Scope: workflows:write

Request Body

{
  "name": "Daily ETL Pipeline",
  "description": "Extracts data from MySQL, transforms, and loads to S3",
  "status": "draft",
  "nodes": [],
  "connections": [],
  "tags": ["etl"],
  "settings": {
    "timeout": 3600,
    "retryOnFailure": true,
    "maxRetries": 3
  }
}

Field	Type	Required	Description
`name`	string	Yes	Workflow name
`description`	string	No	Workflow description
`status`	string	No	Initial status (default: `draft`)
`nodes`	array	No	Array of node objects
`connections`	array	No	Array of connection objects
`tags`	array	No	Array of tag strings
`settings`	object	No	Workflow settings (timeout, retry, etc.)

Response 201 Created

{
  "workflowId": "wf_abc123"
}

`GET` /api/v1/workflows/:id

Get a single workflow by ID.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Response 200 OK

Returns the full Workflow object.

`PUT` /api/v1/workflows/:id

Update an existing workflow.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Request Body

{
  "name": "Updated ETL Pipeline",
  "description": "Updated description",
  "nodes": [],
  "connections": [],
  "tags": ["etl", "v2"],
  "settings": {
    "timeout": 7200
  }
}

Field	Type	Required	Description
`name`	string	No	Workflow name
`description`	string	No	Workflow description
`nodes`	array	No	Array of node objects
`connections`	array	No	Array of connection objects
`tags`	array	No	Array of tag strings
`settings`	object	No	Workflow settings

Response 200 OK

Returns the updated Workflow object.

`DELETE` /api/v1/workflows/:id

Delete a workflow. This action is irreversible.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Response 204 No Content

`POST` /api/v1/workflows/:id/duplicate

Duplicate an existing workflow. Creates a copy with a new ID and draft status.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID to duplicate

Response 201 Created

{
  "workflowId": "wf_def456"
}

`POST` /api/v1/workflows/:id/execute

Execute a workflow. Submits the workflow for execution and returns an execution ID.

Scope: workflows:execute

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Request Body

{
  "definition": {
    "nodes": [],
    "connections": []
  },
  "triggerInputs": {
    "key": "value"
  }
}

Field	Type	Required	Description
`definition`	object	No	Override workflow definition for this execution
`triggerInputs`	object	No	Input data to pass to the trigger node

Response 201 Created

{
  "executionId": "exec_xyz789"
}

`POST` /api/v1/workflows/:id/deploy

Deploy a workflow. Provisions the required infrastructure and makes the workflow ready for execution.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Response 200 OK

{
  "message": "Workflow deployed successfully",
  "workflowId": "wf_abc123",
  "status": "active"
}

`POST` /api/v1/workflows/:id/undeploy

Undeploy a workflow. Tears down the provisioned infrastructure.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Response 200 OK

{
  "message": "Workflow undeployed successfully",
  "workflowId": "wf_abc123",
  "status": "draft"
}

`PUT` /api/v1/workflows/:id/status

Update the status of a workflow.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Request Body

{
  "status": "active"
}

Field	Type	Required	Description
`status`	string	Yes	New status. Must be one of: `draft`, `active`, `paused`, `archived`

Response 200 OK

Returns the updated Workflow object.

`GET` /api/v1/workflows/:id/versions

List all versions of a workflow.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Response 200 OK

{
  "workflowId": "wf_abc123",
  "currentVersion": 3,
  "versions": [
    {
      "version": 1,
      "versionTag": "v1.0.0",
      "description": "Initial version",
      "createdBy": "user_456",
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "version": 2,
      "versionTag": "v1.1.0",
      "description": "Added error handling",
      "createdBy": "user_456",
      "createdAt": "2025-01-20T08:15:00Z"
    },
    {
      "version": 3,
      "versionTag": "v2.0.0",
      "description": "Refactored pipeline",
      "createdBy": "user_456",
      "createdAt": "2025-02-01T14:22:00Z"
    }
  ]
}

`POST` /api/v1/workflows/:id/versions

Create a new version snapshot of the workflow.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Request Body

{
  "versionTag": "v2.1.0",
  "description": "Added retry logic to S3 upload node"
}

Field	Type	Required	Description
`versionTag`	string	Yes	Version tag label
`description`	string	No	Description of changes in this version

Response 201 Created

{
  "workflowId": "wf_abc123",
  "version": 4,
  "versionTag": "v2.1.0"
}

`GET` /api/v1/workflows/:id/share

List users the workflow is shared with.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Response 200 OK

{
  "workflowId": "wf_abc123",
  "sharedWith": [
    {
      "userId": "user_789",
      "sharedAt": "2025-01-18T12:00:00Z"
    }
  ]
}

`POST` /api/v1/workflows/:id/share

Share a workflow with another user in the organization.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID

Request Body

{
  "userId": "user_789"
}

Field	Type	Required	Description
`userId`	string	Yes	ID of the user to share with

Response 200 OK

{
  "message": "Workflow shared successfully",
  "workflowId": "wf_abc123",
  "userId": "user_789"
}

`DELETE` /api/v1/workflows/:id/share/:userId

Remove sharing access for a user.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Workflow ID
`userId`	string	Yes	User ID to remove

Response 204 No Content

`GET` /api/v1/workflows/templates

List available workflow templates.

Scope: workflows:read

Response 200 OK

{
  "count": 5,
  "templates": [
    {
      "id": "wf_tmpl_001",
      "name": "Basic ETL Pipeline",
      "description": "A starter template for extract-transform-load workflows",
      "tags": ["etl", "starter"],
      "nodes": [],
      "connections": [],
      "createdAt": "2025-01-01T00:00:00Z"
    }
  ]
}

`GET` /api/v1/workflows/stats

Get aggregate statistics for workflows in the organization.

Scope: workflows:read

Response 200 OK

{
  "total": 42,
  "active": 18,
  "paused": 5,
  "draft": 15,
  "archived": 4
}

Workflow Object​

GET /api/v1/workflows​

POST /api/v1/workflows​

GET /api/v1/workflows/:id​

PUT /api/v1/workflows/:id​

DELETE /api/v1/workflows/:id​

POST /api/v1/workflows/:id/duplicate​

POST /api/v1/workflows/:id/execute​

POST /api/v1/workflows/:id/deploy​

POST /api/v1/workflows/:id/undeploy​

PUT /api/v1/workflows/:id/status​

GET /api/v1/workflows/:id/versions​

POST /api/v1/workflows/:id/versions​

GET /api/v1/workflows/:id/share​

POST /api/v1/workflows/:id/share​

DELETE /api/v1/workflows/:id/share/:userId​

GET /api/v1/workflows/templates​

GET /api/v1/workflows/stats​

Workflow Object

`GET` /api/v1/workflows

`POST` /api/v1/workflows

`GET` /api/v1/workflows/:id

`PUT` /api/v1/workflows/:id

`DELETE` /api/v1/workflows/:id

`POST` /api/v1/workflows/:id/duplicate

`POST` /api/v1/workflows/:id/execute

`POST` /api/v1/workflows/:id/deploy

`POST` /api/v1/workflows/:id/undeploy

`PUT` /api/v1/workflows/:id/status

`GET` /api/v1/workflows/:id/versions

`POST` /api/v1/workflows/:id/versions

`GET` /api/v1/workflows/:id/share

`POST` /api/v1/workflows/:id/share

`DELETE` /api/v1/workflows/:id/share/:userId

`GET` /api/v1/workflows/templates

`GET` /api/v1/workflows/stats