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.

---

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

Get the full configuration schema, input/output definitions, and human-readable documentation for a node type. Looks up the node in the catalog first (by node type string), then falls back to the workflowNodes collection by MongoDB _id or type field.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Node type identifier or MongoDB _id

Response 200 OK

{
  "type": "mysql-source",
  "name": "MySQL Source",
  "category": "sources",
  "description": "Extracts data from a MySQL database.",
  "tags": ["database", "mysql", "etl"],
  "inputDefinition": {
    "type": "object",
    "properties": {}
  },
  "outputDefinition": {
    "type": "object",
    "properties": {
      "rows": { "type": "array" }
    }
  },
  "editorConfig": {},
  "defaultData": {},
  "dependencies": [],
  "examples": [],
  "documentation": "Markdown-formatted documentation for the node."
}

---

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/datasource-fields/:id

Get the credential field definitions for a data source type (for example, postgres requires host, port, database, username, password). Used by the workflow builder UI to render dynamic connection forms.

Scope: workflows:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Data source type, e.g. mysql, postgres, mongodb, redis, s3, sftp, milvus, elasticsearch

Response 200 OK

{
  "type": "postgres",
  "name": "PostgreSQL",
  "category": "database",
  "defaultPort": 5432,
  "requiresSSL": false,
  "fields": [
    {
      "name": "host",
      "label": "Host",
      "type": "string",
      "required": true,
      "placeholder": "localhost"
    },
    {
      "name": "port",
      "label": "Port",
      "type": "number",
      "required": true,
      "placeholder": "5432"
    },
    {
      "name": "database",
      "label": "Database",
      "type": "string",
      "required": true,
      "placeholder": null
    },
    {
      "name": "username",
      "label": "Username",
      "type": "string",
      "required": true,
      "placeholder": null
    },
    {
      "name": "password",
      "label": "Password",
      "type": "password",
      "required": true,
      "placeholder": null
    }
  ]
}

---

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"
    }
  ]
}

---

GET /api/v1/workflow-nodes/suggest-mappings

Suggest input mappings between two node types based on their output and input definitions. Matches by exact field name first, then falls back to common data / input aliases.

Scope: workflows:read

Query Parameters

Parameter	Type	Required	Description
sourceType	string	Yes	Source node type
targetType	string	Yes	Target node type

Response 200 OK

{
  "sourceType": "mysql-source",
  "targetType": "ai-gateway",
  "suggestedMappings": {
    "prompt": "data.prompt",
    "data": "data"
  },
  "sourceOutputFields": ["rows", "rowCount", "prompt"],
  "targetInputFields": ["prompt", "model", "data"]
}

---

POST /api/v1/workflow-nodes/sync-from-s3

Admin-only. Re-scan s3://strongly-shared/workflows/nodes/ and upsert every node definition into the workflowNodes collection. This is the same seeding path the platform runs on startup, and is called by the strongly-ai-workflow-assets CI after a successful publish so the registry catches up without waiting for a platform restart. Idempotent.

Scope: workflows:write (requires an admin API key)

Response 200 OK

{
  "inserted": 2,
  "updated": 15,
  "total": 35,
  "source": "s3",
  "bucket": "strongly-shared",
  "prefix": "workflows/nodes/"
}

Error 403 Forbidden

{
  "error": "forbidden",
  "message": "sync-from-s3 requires an admin API key",
  "statusCode": 403
}