Entity API Submission Reference

Detailed reference for creating and updating workflow entities via the REST API. This documentation is optimized for RAG integration and programmatic entity management.

API Endpoints

Operation	Method	Endpoint	Permission Required
List Entities	GET	/api/workflow-entities	entities:read
Create Entity	POST	/api/workflow-entities	entities:create
Get Entity	GET	/api/workflow-entities/{id}	entities:read
Update Entity	PUT	/api/workflow-entities/{id}	entities:update
Delete Entity	DELETE	/api/workflow-entities/{id}	entities:delete
Get Usage Count	GET	/api/workflow-entities/{id}/usage-count	entities:read

Authentication & Authorization

All API endpoints require authentication via session cookie. The user's role determines which operations are permitted.

Role Permissions

Role	Create	Read	Update	Delete
System	✅	✅	✅	✅
Admin	✅	✅	✅	✅
User	❌	✅	❌	❌
Guest	❌	✅	❌	❌

Error Responses

// 401 Unauthorized - Not logged in
{ "error": "Unauthorized: Please log in" }

// 403 Forbidden - Insufficient permissions
{ "error": "Forbidden: You do not have permission to create entities" }

Common Request Headers

Content-Type: application/json
Cookie: appSession=<session_cookie>

Entity Types Overview

Type	Purpose	Key Fields
Event	Entry point, condition filtering, branching	condition, tfCondition, logicField, preScript, postScript
Prompt	LLM/AI model execution	prompt, modelId, arguments, preScript, postScript
Action	Custom script execution	preScript, postScript, arguments

---

Event Entity Submission

Events are the entry point for workflow processing. They evaluate conditions and determine branching.

Create Event Entity

POST /api/workflow-entities
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "NFL Touchdown Event",
  "description": "Filters for NFL touchdown plays",
  "workflowEntityTypeId": "<event-type-uuid>",
  "condition": {
    "type": "group",
    "operator": "AND",
    "conditions": [
      {
        "type": "rule",
        "field": "payload.metadata.league",
        "comparison": "equals",
        "value": "nfl"
      },
      {
        "type": "rule",
        "field": "payload.event.play_type",
        "comparison": "equals",
        "value": "touchdown"
      }
    ]
  },
  "tfCondition": "Single Path",
  "logicField": null,
  "preScript": null,
  "postScript": "print('Processing touchdown event');",
  "arguments": [
    {
      "argumentName": "debugMode",
      "argumentValue": "true",
      "argumentDescription": "Enable debug logging"
    }
  ],
  "logic": []
}

Event with True/False Branching

{
  "organizationId": "...",
  "environmentId": "...",
  "name": "Check Premium User",
  "workflowEntityTypeId": "<event-type-uuid>",
  "condition": {
    "type": "rule",
    "field": "user.premium",
    "comparison": "equals",
    "value": true
  },
  "tfCondition": "True/False",
  "preScript": null,
  "postScript": null
}

Event with Multi Branching

{
  "organizationId": "...",
  "environmentId": "...",
  "name": "Route by Region",
  "workflowEntityTypeId": "<event-type-uuid>",
  "condition": {
    "type": "rule",
    "field": "type",
    "comparison": "equals",
    "value": "order.created"
  },
  "tfCondition": "Multi",
  "logicField": "region",
  "preScript": "var region = shipping.country === 'US' ? 'us' : 'intl';",
  "postScript": null,
  "logic": [
    { "name": "US Orders", "value": "us" },
    { "name": "International", "value": "intl" }
  ]
}

Event with Iterable Mode (Array Processing)

{
  "organizationId": "...",
  "environmentId": "...",
  "name": "Process Each Recipient",
  "workflowEntityTypeId": "<event-type-uuid>",
  "condition": {
    "type": "rule",
    "field": "type",
    "comparison": "equals",
    "value": "notification.broadcast"
  },
  "tfCondition": "Iterable",
  "logicField": "recipients",
  "preScript": null,
  "postScript": "print('Processing recipient:', ___iterableItem___.name);"
}

Event Branching Modes

Mode	tfCondition Value	Behavior
Single Path	"Single Path"	Condition true → continue; false → exit workflow
True/False	"True/False"	Branch to child with matching value: "true" or value: "false"
Multi	"Multi"	Evaluate logicField variable, branch to matching logic value
Iterable	"Iterable"	Execute children once for each item in logicField array

Multi Mode Requires the logic Array

When creating a Multi mode event entity via the API, you must include the logic array with { name, value } entries for each branch. The logic array creates WorkflowEntityLogic database rows that:

1. Define the allowed branch values shown in the entity form
2. Auto-generate logic-branch nodes when the entity is placed on the canvas
3. Keep the entity and workflow graph in sync when editing

Setting only tfCondition: "Multi" and logicField without logic will create a broken entity — the canvas will have no branch nodes to create, and the entity form will show no logic values.

{
  "tfCondition": "Multi",
  "logicField": "event.type",
  "logic": [
    { "name": "Play", "value": "play" },
    { "name": "Event", "value": "event" },
    { "name": "Catch-All", "value": "*" }
  ]
}

Update caution: The PUT endpoint deletes all existing logic rows before recreating them. Always include the full logic array on updates, or the entity will lose its logic values.

Iterable Mode Details

When using Iterable mode:

• logicField should point to an array in the message (e.g., recipients)
• The workflow executes its children once for each item in the array
• Each iteration receives the current item as ___iterableItem___ in the script context
• If the field is not an array, workflow proceeds normally (single execution)

Example Message for Iterable:

{
  "type": "notification.broadcast",
  "content": "Server maintenance tonight",
  "recipients": [
    { "name": "Alice", "email": "alice@example.com" },
    { "name": "Bob", "email": "bob@example.com" },
    { "name": "Charlie", "email": "charlie@example.com" }
  ]
}

With logicField: "recipients", the workflow executes 3 times, once for each recipient.

---

Prompt Entity Submission

Prompts execute AI/LLM models with templated prompts and capture responses.

Create Prompt Entity

POST /api/workflow-entities
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Generate Tweet",
  "description": "Creates a tweet from event data using AI",
  "workflowEntityTypeId": "<prompt-type-uuid>",
  "modelId": "770e8400-e29b-41d4-a716-446655440002",
  "prompt": "Generate a short, engaging tweet about this NFL play:\n\nPlay Type: {{playType}}\nPlayer: {{playerName}}\nTeam: {{teamName}}\n\nKeep it under 280 characters.",
  "tfCondition": "Single Path",
  "preScript": null,
  "postScript": "// Runs after the model call\nprint('AI Response:', latestPromptResponse());",
  "arguments": [
    {
      "argumentName": "playType",
      "argumentValue": "{{payload.event.play_type}}",
      "argumentDescription": "Type of play from message"
    },
    {
      "argumentName": "playerName",
      "argumentValue": "{{payload.event.player.name}}",
      "argumentDescription": "Player name"
    },
    {
      "argumentName": "teamName",
      "argumentValue": "{{payload.event.team.name}}",
      "argumentDescription": "Team name"
    }
  ]
}

Prompt Execution Flow

All entity types share the same unified pipeline (see Workflow Entities Overview). For Prompt entities, the notable steps are:

1. Inject message
2. Run preScript (if any)
3. Inject arguments (with handlebar resolution where applicable)
4. Evaluate condition (if any; else true) → ___result___
5. Inject prompt/model, process handlebars, executePromptWithModel() when a model is set
6. Run postScript (if any)
7. Capture context → continue to children

Available Prompt Functions

Function	Description
executePromptWithModel()	Auto-called if model is set
latestPromptResponse()	Get the AI response text
getPromptResponse(index)	Get response by index (0 = most recent)
promptCallUniversal(modelConfiguration, promptText)	Manual LLM call using the resolved universal model configuration injected into V8 (same shape as auto executePromptWithModel()); optional third argument imageUrlsJson for vision

---

Action Entity Submission

Actions execute custom JavaScript for data transformations and integrations.

Create Action Entity

POST /api/workflow-entities
Content-Type: application/json

{
  "organizationId": "550e8400-e29b-41d4-a716-446655440000",
  "environmentId": "660e8400-e29b-41d4-a716-446655440001",
  "name": "Post to Mastodon",
  "description": "Posts the AI-generated content to Mastodon",
  "workflowEntityTypeId": "<action-type-uuid>",
  "preScript": null,
  "postScript": "// Get the latest AI response and post to Mastodon\nconst tweetText = latestPromptResponse();\n\nif (tweetText) {\n  await postToMastodon(\n    MASTODON_URL,\n    MASTODON_ACCESS_TOKEN,\n    tweetText\n  );\n  print('Posted to Mastodon:', tweetText);\n} else {\n  print('No prompt response to post');\n}",
  "tfCondition": "Single Path",
  "arguments": [
    {
      "argumentName": "maxLength",
      "argumentValue": "500",
      "argumentDescription": "Maximum post length"
    }
  ]
}

Action Execution Flow

1. Inject message
2. Run preScript (if any)
3. Inject arguments
4. Evaluate condition (if any; else true)
5. Prompt + model (usually skipped for Actions)
6. Run postScript (if any)
7. Capture context → continue to children

Available Action Functions

Function	Description
print(...args)	Debug logging to console
postToMastodon(url, token, status)	Post to Mastodon server
postLatestPromptToMastodon()	Post AI response to Mastodon
stmStore(metadata, value, filename)	Store data in S3
stmRetrieve(metadata, filename)	Retrieve data from S3
pubsubPublish(channel, message)	Publish to Redis PubSub
nflGetTeams()	Get NFL teams from SportRadar
evaluateCondition(tree, data)	Evaluate a condition tree
latestPromptResponse()	Get most recent AI response

Script Context Variables

Variable	Type	Description
(top-level fields)	various	Incoming workflow message fields at global scope (type, payload, organizationId, content, etc.)
___result___	Boolean	Last condition result
___iterableItem___	any	Current item when in Iterable mode
output	any	Set to pass data to next nodes
{VARIABLE_NAME}	any	Each environment variable as top-level var

---

Arguments: Literal vs Reference

Arguments support two value types:

Literal Values

Plain text injected as-is:

{
  "argumentName": "apiEndpoint",
  "argumentValue": "https://api.example.com/v1",
  "argumentDescription": "API endpoint URL"
}

V8 injection: var apiEndpoint = "https://api.example.com/v1";

Reference Values (Handlebars)

Dynamic references to message or context data:

{
  "argumentName": "userId",
  "argumentValue": "{{user.id}}",
  "argumentDescription": "User ID from message"
}

V8 injection: var userId = user.id;

Common Reference Patterns

Pattern	Description
{{type}}	Message type field
{{payload.event.type}}	Nested event type
{{user.id}}	User ID from message
{{latestPromptResponse()}}	AI response text

---

Workflow Outcomes

Workflow outcomes are determined automatically based on execution:

Outcome	When it occurs	S3 Folder
Success	All entities execute without errors	success/
Error	A script throws an error or times out	fail/
Ignore	Event condition doesn't match	ignore/

---

Response Format

All successful entity operations return:

{
  "id": "uuid",
  "organizationId": "uuid",
  "environmentId": "uuid",
  "name": "string",
  "description": "string | null",
  "workflowEntityTypeId": "uuid",
  "workflowEntityType": {
    "id": "uuid",
    "name": "event | prompt | action",
    "showScript": true,
    "showPrompt": false,
    "showConditions": true,
    "showArguments": true,
    "showModel": false,
    "showLogic": true
  },
  "condition": { /* condition tree or null */ },
  "preScript": "string | null",
  "postScript": "string | null",
  "modelId": "uuid | null",
  "tfCondition": "Single Path | True/False | Multi | Iterable",
  "logicField": "string | null",
  "prompt": "string | null",
  "arguments": [
    {
      "argumentName": "string",
      "argumentValue": "string",
      "argumentDescription": "string | null"
    }
  ],
  "logic": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "createdAt": "2025-12-11T18:00:00.000Z",
  "updatedAt": "2025-12-11T18:00:00.000Z"
}

Error Responses

Authentication Errors

// 401 Unauthorized - Session expired or missing
{ "error": "Unauthorized: Please log in" }

Authorization Errors

// 403 Forbidden - User lacks permission
{ "error": "Forbidden: You do not have permission to create entities" }
{ "error": "Forbidden: You do not have permission to update entities" }
{ "error": "Forbidden: You do not have permission to delete entities" }

Validation Errors

// 400 Bad Request - Missing required fields
{ "error": "organizationId is required" }
{ "error": "environmentId is required" }

Not Found Errors

// 404 Not Found - Entity doesn't exist
{ "error": "Workflow entity not found" }

Server Errors

// 500 Server Error - Unexpected failure
{ "error": "Failed to create workflow entity" }
{ "error": "Failed to update workflow entity" }
{ "error": "Failed to delete workflow entity" }

List Entities Query Parameters

GET /api/workflow-entities?organizationId=uuid&environmentId=uuid&page=1&limit=10&search=touchdown

Parameter	Required	Description
organizationId	Yes	Filter by organization
environmentId	No	Filter by environment
page	No	Page number (default: 1)
limit	No	Items per page (default: 10)
search	No	Search by name (case-insensitive)

Related Topics

• Condition System — Condition tree structure and CRUD operations
• Event Entity — Event-specific configuration
• Prompt Entity — AI/LLM integration
• Action Entity — Script execution
• Script Runtime — How scripts execute
• RBAC Settings — Role permissions reference
• AI Assistant — Create entities with AI