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, script
Prompt	LLM/AI model execution	prompt, modelId, arguments, script
Action	Custom script execution	script, 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": "message.payload.metadata.league",
        "comparison": "equals",
        "value": "nfl"
      },
      {
        "type": "rule",
        "field": "message.payload.event.play_type",
        "comparison": "equals",
        "value": "touchdown"
      }
    ]
  },
  "tfCondition": "Single Path",
  "logicField": null,
  "script": "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": "message.user.premium",
    "comparison": "equals",
    "value": true
  },
  "tfCondition": "True/False",
  "script": null
}

Event with Multi Branching

{
  "organizationId": "...",
  "environmentId": "...",
  "name": "Route by Region",
  "workflowEntityTypeId": "<event-type-uuid>",
  "condition": {
    "type": "rule",
    "field": "message.type",
    "comparison": "equals",
    "value": "order.created"
  },
  "tfCondition": "Multi",
  "logicField": "region",
  "script": "var region = message.shipping.country === 'US' ? 'us' : 'intl';",
  "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": "message.type",
    "comparison": "equals",
    "value": "notification.broadcast"
  },
  "tfCondition": "Iterable",
  "logicField": "message.recipients",
  "script": "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

Iterable Mode Details

When using Iterable mode:

• logicField should point to an array in the message (e.g., message.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: "message.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",
  "script": "// Script runs AFTER prompt execution\nprint('AI Response:', latestPromptResponse());",
  "arguments": [
    {
      "argumentName": "playType",
      "argumentValue": "{{message.payload.event.play_type}}",
      "argumentDescription": "Type of play from message"
    },
    {
      "argumentName": "playerName",
      "argumentValue": "{{message.payload.event.player.name}}",
      "argumentDescription": "Player name"
    },
    {
      "argumentName": "teamName",
      "argumentValue": "{{message.payload.event.team.name}}",
      "argumentDescription": "Team name"
    }
  ]
}

Prompt Execution Flow

1. Inject message into V8 context
2. Inject prompt text and model credentials
3. Inject arguments (with handlebar resolution)
4. Run pre-script (if exists)
5. Auto-execute: await executePromptWithModel()
6. Capture response in latestPromptResponse()
7. Run post-script (if exists)
8. 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)
promptCallToken(token, prompt, url)	Manual prompt call with bearer token
promptCallKeys(key, secret, prompt, url)	Manual prompt call with key/secret

---

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>",
  "script": "// 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 into V8 context
2. Inject arguments
3. Run script
4. Capture context variables
5. 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
message	Object	Incoming message payload
___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": "{{message.user.id}}",
  "argumentDescription": "User ID from message"
}

V8 injection: var userId = message.user.id;

Common Reference Patterns

Pattern	Description
{{message.type}}	Message type field
{{message.payload.event.type}}	Nested event type
{{message.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 */ },
  "script": "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