Workflow Nodes

Browse, create, and manage workflow node types. Node types define the building blocks available in the workflow builder, including data sources, transformations, AI models, and custom logic. System nodes are read-only and cannot be modified or deleted.

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

WorkflowNode Object

{
  "id": "node_type_001",
  "nodeId": "mysql-source",
  "label": "MySQL Source",
  "name": "mysql-source",
  "description": "Extracts data from a MySQL database",
  "category": "sources",
  "type": "database",
  "nodeType": "source",
  "version": "1.2.0",
  "isSystem": true,
  "isActive": true,
  "configSchema": {
    "type": "object",
    "properties": {
      "dataSource": {
        "type": "string",
        "description": "Name of the data source to connect to"
      },
      "query": {
        "type": "string",
        "description": "SQL query to execute"
      }
    },
    "required": ["dataSource", "query"]
  },
  "defaultConfig": {
    "query": "SELECT * FROM table LIMIT 100"
  },
  "icon": "database",
  "inputs": [],
  "outputs": [
    {
      "id": "output",
      "label": "Data",
      "type": "data"
    }
  ],
  "tags": ["database", "mysql", "etl"],
  "createdBy": "system",
  "updatedBy": "system",
  "createdAt": "2025-01-01T00:00:00Z",
  "updatedAt": "2025-01-15T00:00:00Z"
}

`GET` /api/v1/workflow-nodes

List available workflow node types.

Scope: workflows:read

Query Parameters

Parameter	Type	Required	Description
`active`	boolean	No	Filter by active status (default: `true`)
`category`	string	No	Filter by category, e.g. `sources`, `destinations`, `transforms`, `ai`, `logic`
`type`	string	No	Filter by type, e.g. `database`, `file`, `api`, `model`
`isSystem`	boolean	No	Filter by system vs. custom nodes
`search`	string	No	Search by label, name, or description
`limit`	integer	No	Number of results to return (default: 50)
`offset`	integer	No	Number of results to skip (default: 0)
`sort`	string	No	Sort field and direction, e.g. `label:asc`

Response 200 OK

{
  "count": 35,
  "limit": 50,
  "offset": 0,
  "nodes": [
    {
      "id": "node_type_001",
      "nodeId": "mysql-source",
      "label": "MySQL Source",
      "name": "mysql-source",
      "description": "Extracts data from a MySQL database",
      "category": "sources",
      "type": "database",
      "nodeType": "source",
      "version": "1.2.0",
      "isSystem": true,
      "isActive": true,
      "icon": "database",
      "tags": ["database", "mysql", "etl"],
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-15T00:00:00Z"
    }
  ]
}

`POST` /api/v1/workflow-nodes

Create a custom workflow node type.

Scope: workflows:write

Request Body

{
  "label": "Custom Enrichment",
  "category": "transforms",
  "type": "custom",
  "nodeId": "custom-enrichment",
  "description": "Enriches records with additional data from an external API",
  "version": "1.0.0",
  "configSchema": {
    "type": "object",
    "properties": {
      "apiUrl": {
        "type": "string",
        "description": "External API endpoint"
      },
      "apiKey": {
        "type": "string",
        "description": "API authentication key"
      }
    },
    "required": ["apiUrl"]
  },
  "defaultConfig": {},
  "icon": "sparkles",
  "inputs": [
    {
      "id": "input",
      "label": "Data",
      "type": "data"
    }
  ],
  "outputs": [
    {
      "id": "output",
      "label": "Enriched Data",
      "type": "data"
    }
  ],
  "tags": ["custom", "enrichment"],
  "isActive": true
}

Field	Type	Required	Description
`label`	string	Yes	Display label for the node
`category`	string	Yes	Node category: `sources`, `destinations`, `transforms`, `ai`, `logic`
`type`	string	Yes	Node type within the category, e.g. `database`, `file`, `custom`
`nodeId`	string	No	Unique identifier slug. Auto-generated from label if not provided
`description`	string	No	Description of what the node does
`version`	string	No	Semantic version (default: `1.0.0`)
`configSchema`	object	No	JSON Schema defining the node's configuration options
`defaultConfig`	object	No	Default configuration values
`icon`	string	No	Icon name for the workflow builder UI
`inputs`	array	No	Array of input port definitions
`outputs`	array	No	Array of output port definitions
`tags`	array	No	Array of tag strings
`isActive`	boolean	No	Whether the node is active (default: `true`)

Response 201 Created

{
  "nodeId": "custom-enrichment"
}

`GET` /api/v1/workflow-nodes/:id

Get a single workflow node type by ID.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Node type ID

Response 200 OK

Returns the full WorkflowNode object.

`PUT` /api/v1/workflow-nodes/:id

Update a custom workflow node type. System nodes cannot be modified.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Node type ID

Request Body

{
  "label": "Custom Enrichment v2",
  "description": "Updated enrichment node with batch support",
  "version": "2.0.0",
  "configSchema": {
    "type": "object",
    "properties": {
      "apiUrl": {
        "type": "string",
        "description": "External API endpoint"
      },
      "apiKey": {
        "type": "string",
        "description": "API authentication key"
      },
      "batchSize": {
        "type": "integer",
        "description": "Number of records per batch",
        "default": 100
      }
    },
    "required": ["apiUrl"]
  },
  "defaultConfig": {
    "batchSize": 100
  },
  "tags": ["custom", "enrichment", "batch"]
}

Field	Type	Required	Description
`label`	string	No	Display label for the node
`description`	string	No	Node description
`version`	string	No	Semantic version
`configSchema`	object	No	JSON Schema for configuration
`defaultConfig`	object	No	Default configuration values
`icon`	string	No	Icon name
`inputs`	array	No	Input port definitions
`outputs`	array	No	Output port definitions
`tags`	array	No	Tag strings
`isActive`	boolean	No	Active status

Response 200 OK

Returns the updated WorkflowNode object.

Error 403 Forbidden

Returned when attempting to update a system node.

{
  "error": "Forbidden",
  "message": "System nodes cannot be modified",
  "statusCode": 403
}

`DELETE` /api/v1/workflow-nodes/:id

Delete a custom workflow node type. System nodes cannot be deleted.

Scope: workflows:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Node type ID

Response 204 No Content

Error 403 Forbidden

Returned when attempting to delete a system node.

{
  "error": "Forbidden",
  "message": "System nodes cannot be deleted",
  "statusCode": 403
}

`GET` /api/v1/workflow-nodes/services/datasources

List data sources available for use in workflow nodes. These are the configured database and file connections that source and destination nodes can connect to.

Scope: workflows:read

Query Parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by data source type, e.g. `mysql`, `postgresql`, `mongodb`, `s3`
`category`	string	No	Filter by category, e.g. `database`, `file`, `api`

Response 200 OK

{
  "count": 4,
  "datasources": [
    {
      "id": "ds_001",
      "name": "Production MySQL",
      "type": "mysql",
      "category": "database",
      "status": "connected",
      "organizationId": "org_xyz"
    },
    {
      "id": "ds_002",
      "name": "Analytics PostgreSQL",
      "type": "postgresql",
      "category": "database",
      "status": "connected",
      "organizationId": "org_xyz"
    },
    {
      "id": "ds_003",
      "name": "Data Lake S3",
      "type": "s3",
      "category": "file",
      "status": "connected",
      "organizationId": "org_xyz"
    },
    {
      "id": "ds_004",
      "name": "MongoDB Atlas",
      "type": "mongodb",
      "category": "database",
      "status": "connected",
      "organizationId": "org_xyz"
    }
  ]
}

`GET` /api/v1/workflow-nodes/services/addons

List add-ons available for use in workflow nodes. Add-ons provide additional capabilities such as caching, message queues, and vector databases.

Scope: workflows:read

Query Parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by add-on type, e.g. `redis`, `rabbitmq`, `chromadb`

Response 200 OK

{
  "count": 2,
  "addons": [
    {
      "id": "addon_001",
      "name": "Redis Cache",
      "type": "redis",
      "status": "running",
      "organizationId": "org_xyz"
    },
    {
      "id": "addon_002",
      "name": "ChromaDB Vectors",
      "type": "chromadb",
      "status": "running",
      "organizationId": "org_xyz"
    }
  ]
}

`GET` /api/v1/workflow-nodes/services/models

List AI models available for use in workflow nodes. These are the models configured through AI Gateway that can be used in AI-powered nodes.

Scope: workflows:read

Query Parameters

Parameter	Type	Required	Description
`provider`	string	No	Filter by model provider, e.g. `openai`, `anthropic`, `google`
`type`	string	No	Filter by model type, e.g. `chat`, `embedding`, `image`

Response 200 OK

{
  "count": 3,
  "models": [
    {
      "id": "model_001",
      "name": "GPT-4o",
      "provider": "openai",
      "type": "chat",
      "modelId": "gpt-4o",
      "organizationId": "org_xyz"
    },
    {
      "id": "model_002",
      "name": "Claude Sonnet 4",
      "provider": "anthropic",
      "type": "chat",
      "modelId": "claude-sonnet-4-20250514",
      "organizationId": "org_xyz"
    },
    {
      "id": "model_003",
      "name": "Text Embedding 3 Large",
      "provider": "openai",
      "type": "embedding",
      "modelId": "text-embedding-3-large",
      "organizationId": "org_xyz"
    }
  ]
}

WorkflowNode Object​

GET /api/v1/workflow-nodes​

POST /api/v1/workflow-nodes​

GET /api/v1/workflow-nodes/:id​

PUT /api/v1/workflow-nodes/:id​

DELETE /api/v1/workflow-nodes/:id​

GET /api/v1/workflow-nodes/services/datasources​

GET /api/v1/workflow-nodes/services/addons​

GET /api/v1/workflow-nodes/services/models​

WorkflowNode Object

`GET` /api/v1/workflow-nodes

`POST` /api/v1/workflow-nodes

`GET` /api/v1/workflow-nodes/:id

`PUT` /api/v1/workflow-nodes/:id

`DELETE` /api/v1/workflow-nodes/:id

`GET` /api/v1/workflow-nodes/services/datasources

`GET` /api/v1/workflow-nodes/services/addons

`GET` /api/v1/workflow-nodes/services/models