Flows

SDK reference for flows operations

Overview

Internal automation system for time-based and event-based task execution

• Category: internal
• Auth Required: No
• Supported Modes: standard, delegated, service

Operations

createFlow

Create a flow (event-triggered or time-scheduled). This is the unified, simplified interface for flow creation.

TRIGGER TYPE (provide exactly one):

• schedule: Cron expression for time-based flows (e.g., "0 9 * * *"). Times are automatically in the user's local timezone.
• eventType: Event type shorthand for event flows (e.g., "telegram.message")
• eventFilter: Full filter object for complex event conditions
• trigger: Legacy nested structure (still supported)

SCRIPT (provide exactly one):

• code: Inline script code - will auto-create, deploy, and link the script
• scriptId: ID of an existing deployed script

EXAMPLES:

Time flow with inline code: { title: "Daily Report", schedule: "0 9 * * *", code: "export async function handler(event, context, mirra) { await mirra.telegram.sendMessage({...}); return { done: true }; }" }

Event flow with eventType shorthand: { title: "Handle Messages", eventType: "telegram.message", code: "export async function handler(event, context, mirra) { return { handled: true }; }" }

Event flow with existing script: { eventType: "gmail.email_received", scriptId: "existing-script-id" }

Arguments:

• title (string, optional): Flow title. Required if providing inline code.
• description (string, optional): Detailed description of what the flow does
• code (string, optional): Inline script code. If provided, auto-creates, deploys, and links the script. Cannot use with scriptId.
• scriptId (string, optional): ID of existing deployed script. Cannot use with code.
• schedule (string, optional): Cron expression for time-based flows. Times are automatically evaluated in the user's local timezone. Example: "0 9 * * *" runs at 9am in the user's timezone.
• eventType (string, optional): Event type shorthand (e.g., "telegram.message", "gmail.email_received"). Creates an eventFilter matching this type.
• eventFilter (object, optional): Full event filter with operator and conditions array for complex filtering.
• trigger (object, optional): Legacy nested trigger structure. Prefer eventType or eventFilter instead.
• scriptInput (object, optional): Optional static input data for the script
• enabled (boolean, optional): Whether the flow is enabled (default: true)

Returns:

NormalizedFlow - Returns FLAT flow object with: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, scriptInstallationId, scriptInput, executionCount, lastExecutedAt, createdAt, updatedAt, version, feedItemId, isActive, isTimeBased, isEventBased. No nested trigger object.

Response Fields:

Example:

const result = await mirra.flows.createFlow({});

createTimeFlow

Create a new time-based flow with cron schedule. NOTE: Consider using createFlow instead for a simpler interface with inline code support.

Arguments:

• title (string, required): Flow title
• description (string, required): Detailed description of what the flow does
• schedule (string, required): Cron expression for scheduling (e.g., "0 9 * * *" for daily at 9am)
• scriptId (string, required): ID of the script to execute when triggered
• scriptInput (object, optional): Optional static input data for the script

Returns:

NormalizedFlow - Returns FLAT flow object with: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, scriptInstallationId, scriptInput, executionCount, lastExecutedAt, createdAt, updatedAt, version, feedItemId, isActive, isTimeBased, isEventBased. No nested trigger object.

Response Fields:

Example:

const result = await mirra.flows.createTimeFlow({
  title: "example",
  description: "example",
  schedule: "example",
  scriptId: "abc123"
});

createEventFlow

Create an event-based flow with pre-filtering conditions. NOTE: Consider using createFlow instead for a simpler interface with inline code support.

EFFICIENCY RULE: Always filter in eventFilter, not the script.

• eventFilter conditions: FREE (evaluated in-memory before script runs)
• Script filtering: EXPENSIVE (invokes Lambda for every event)

BAD: Trigger on "telegram.message" with no filter → script checks sender GOOD: Trigger on "telegram.message" with eventFilter for sender

TRIGGER STRUCTURE: { type: "event", config: { eventFilter: { operator: "and" | "or", conditions: [ { operator: "equals", field: "type", value: "call.ended" }, { operator: "contains", field: "content.text", value: "urgent" } ] } } }

IMPORTANT: Use field: "type" (not "eventType") to filter by event type. This is required for testFlow to auto-generate test events.

VALID OPERATORS: equals, notEquals, contains, startsWith, endsWith, greaterThan, lessThan, exists, notExists, matchesRegex, and, or, not

COMMON EVENT TYPES (use with field: "type"): call.started, call.ended, call.action, telegram.message, gmail.email_received

Arguments:

• title (string, required): Flow title
• description (string, required): Detailed description of what the flow does
• trigger (object, required): Event filter conditions that determine WHEN the script runs. Add ALL filtering logic here to minimize Lambda invocations. Must have type:"event" and config.eventFilter with operator and conditions array.
• scriptId (string, required): ID of the script to execute when triggered
• scriptInput (object, optional): Optional static input data for the script

Returns:

NormalizedFlow - Returns FLAT flow object with: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, scriptInstallationId, scriptInput, executionCount, lastExecutedAt, createdAt, updatedAt, version, feedItemId, isActive, isTimeBased, isEventBased. No nested trigger object.

Response Fields:

Example:

const result = await mirra.flows.createEventFlow({
  title: "example",
  description: "example",
  trigger: {},
  scriptId: "abc123"
});

listFlows

List all flows for the user. Returns normalized flow summaries.

Arguments:

• status (string, optional): Filter by status: active, paused, completed, failed

Returns:

FlowListResult - Returns { count, flows[] }. Each flow has FLAT fields: id, title, description, status, userId, triggerType, cronExpression, scriptId, executionCount, lastExecutedAt, createdAt, isActive. No nested objects.

Response Fields:

Example:

const result = await mirra.flows.listFlows({});

getFlow

Get a specific flow by ID. Returns normalized flat structure.

Arguments:

• id (string, required): Flow ID

Returns:

NormalizedFlow - Returns FLAT flow object with: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, scriptInstallationId, scriptInput, executionCount, lastExecutedAt, createdAt, updatedAt, version, feedItemId, isActive, isTimeBased, isEventBased. No nested trigger object.

Response Fields:

Example:

const result = await mirra.flows.getFlow({
  id: "abc123"
});

updateFlow

Update an existing flow. Returns normalized flat structure.

Arguments:

• id (string, required): Flow ID to update
• title (string, optional): New title
• description (string, optional): New description
• trigger (object, optional): New trigger configuration
• scriptId (string, optional): New script ID
• scriptInput (object, optional): New script input data
• status (string, optional): New status: active, paused, completed, failed

Returns:

NormalizedFlow - Returns FLAT flow object with: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, scriptInstallationId, scriptInput, executionCount, lastExecutedAt, createdAt, updatedAt, version, feedItemId, isActive, isTimeBased, isEventBased. No nested trigger object.

Response Fields:

Example:

const result = await mirra.flows.updateFlow({
  id: "abc123"
});

deleteFlow

Delete a flow

Arguments:

• id (string, required): Flow ID to delete

Returns:

DeleteFlowResult - Returns { flowId, deleted: true }. Simple confirmation with no nested objects.

Response Fields:

Example:

const result = await mirra.flows.deleteFlow({
  id: "abc123"
});

pauseFlow

Pause an active flow. Returns normalized flat structure.

Arguments:

• id (string, required): Flow ID to pause

Returns:

NormalizedFlow - Returns FLAT flow object with status set to "paused". Fields: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, etc. No nested trigger object.

Response Fields:

Example:

const result = await mirra.flows.pauseFlow({
  id: "abc123"
});

resumeFlow

Resume a paused flow. Returns normalized flat structure.

Arguments:

• id (string, required): Flow ID to resume

Returns:

NormalizedFlow - Returns FLAT flow object with status set to "active". Fields: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, etc. No nested trigger object.

Response Fields:

Example:

const result = await mirra.flows.resumeFlow({
  id: "abc123"
});

searchFlows

Search flows with filters. Returns normalized flow summaries.

Arguments:

• status (string, optional): Filter by status (or array of statuses)
• triggerType (string, optional): Filter by trigger type: time or event
• limit (number, optional): Maximum number of results (default: 100)
• offset (number, optional): Pagination offset (default: 0)

Returns:

FlowSearchResult - Returns { count, flows[] }. Each flow has FLAT fields: id, title, description, status, userId, triggerType, cronExpression, scriptId, executionCount, lastExecutedAt, createdAt, isActive. No nested objects.

Response Fields:

Example:

const result = await mirra.flows.searchFlows({});

recordExecution

Record execution result for a flow. Returns normalized flat structure.

Arguments:

• id (string, required): Flow ID
• success (boolean, required): Whether execution succeeded
• result (object, optional): Execution result data
• error (string, optional): Error message if execution failed

Returns:

NormalizedFlow - Returns FLAT flow object with updated executionCount. Fields: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, executionCount, lastExecutedAt, etc. No nested trigger object.

Response Fields:

Example:

const result = await mirra.flows.recordExecution({
  id: "abc123",
  success: true
});

listEventTypes

List all available event types that can trigger automations. Returns normalized event types.

IMPORTANT: Use includeSchema: true when writing scripts to see available fields and correct access patterns.

Scripts receive an ExecutionRequest, NOT the raw IntegrationEvent. Correct access patterns:

• event.data.text (normalized text content)
• event.data.sender (normalized sender name)
• event.data.event (full IntegrationEvent object)
• event.trigger.event (also full IntegrationEvent)

Common WRONG patterns that don't work:

• event.summary (doesn't exist)
• event.content.text (wrong path)
• event.timestamp (wrong path)

Arguments:

• includeTemplates (boolean, optional): Include condition templates for each event type
• includeSchema (boolean, optional): Include field schema showing available paths for script access. RECOMMENDED when writing scripts to see correct field access patterns.

Returns:

EventTypeListResult - Returns { count, eventTypes[] }. Each event type has FLAT fields: constant, eventType, source, description, hasTemplates. When includeSchema=true, also includes fields[], accessExample, and commonMistakes.

Response Fields:

Example:

const result = await mirra.flows.listEventTypes({});

testFlow

Test a flow by generating an event that matches the trigger conditions.

REQUIREMENT: The flow's trigger conditions MUST include a condition with field: "type" or field: "source" so the system knows what kind of test event to generate.

CORRECT condition: { operator: "equals", field: "type", value: "telegram.message" } WRONG condition: { operator: "equals", field: "eventType", value: "telegram.message" }

If your flow lacks a "type" or "source" condition, use validateTrigger instead with a manually constructed event.

MODES:

• dryRun=true (DEFAULT): Validates trigger matching only. Safe, no side effects, no token consumption.
• dryRun=false: Executes the real script. WARNING: This causes real side effects (sends messages, makes API calls, consumes tokens).

Use dryRun=true first to verify trigger conditions work, then dryRun=false only when ready to test full execution.

WORKFLOW:

1. Generates a test event from the flow's trigger conditions (requires "type" or "source" field)
2. Validates the event matches the trigger (always)
3. If dryRun=false, executes the script with the test event

RESULT: Returns detailed information about trigger matching, including which conditions passed/failed, and optionally full execution results.

Arguments:

• flowId (string, required): ID of the flow to test
• dryRun (boolean, optional): If true (default), only validate trigger matching without executing script. If false, execute the script (causes side effects).
• eventOverrides (object, optional): Custom field values to merge into the generated test event (e.g., {"content.text": "custom message"})

Returns:

FlowTestResult - Returns FLAT test result with: success, flowId, mode, triggerMatched, conditionResults[] (each with field, operator, expected, actual, passed), testEvent (id, type, source, summary), executionId, executionStatus, executionDuration, executionError, tokensConsumed, recommendations[]. No nested triggerValidation or execution objects.

Response Fields:

| testEvent | TestEvent | Generated test event info |

| executionId | string | Execution ID (if executed) | | executionStatus | string | Execution status (success, error, timeout) | | executionDuration | number | Execution duration in ms | | executionError | string | Error message if failed | | tokensConsumed | number | Tokens consumed | | recommendations | string[] | Actionable recommendations |

Example:

const result = await mirra.flows.testFlow({
  flowId: "abc123"
});

validateTrigger

Check if a custom event would match a flow trigger without any execution. Useful for debugging trigger conditions or testing with real event data.

Arguments:

• flowId (string, required): ID of the flow
• event (object, required): Event object to test against the trigger (must match IntegrationEvent structure)

Returns:

TriggerValidationResult - Returns FLAT result with: flowId, matched (boolean), conditionResults[] (each with field, operator, expected, actual, passed). No nested objects.

Response Fields:

Example:

const result = await mirra.flows.validateTrigger({
  flowId: "abc123",
  event: {}
});

getFlowsByEventType

Get all active flows that are triggered by a specific event type. Used by frontend to show flow selection for targeted execution (e.g., call.action flows).

Arguments:

• eventType (string, required): Event type to filter by (e.g., "call.action", "call.ended", "telegram.message")

Returns:

FlowsByEventTypeResult - Returns { eventType, count, flows[] }. Each flow has FLAT fields: id, title, description, status, userId, triggerType, cronExpression, scriptId, executionCount, lastExecutedAt, createdAt, isActive. No nested objects.

Response Fields:

Example:

const result = await mirra.flows.getFlowsByEventType({
  eventType: "example"
});

createBatchOperation

Create a self-managing flow that processes multiple adapter operations over time, respecting rate limits. The flow automatically cleans up when complete and notifies the user via feed item.

Arguments:

• title (string, required): Human-readable title for this batch operation (e.g., "Leave 100 Telegram groups")
• operations (array, required): Array of operations to execute. Each item must have adapter, operation, and args properties.
• batchSize (number, optional): Number of operations to process per execution (default: 5)
• intervalSeconds (number, optional): Seconds between batch executions (default: 60, minimum: 60)

Returns:

BatchOperationResult - Returns FLAT result with: flowId, title, operationCount, batchSize, intervalSeconds, estimatedCompletionMinutes, message, createdAt. No nested objects.

Response Fields:

Example:

const result = await mirra.flows.createBatchOperation({
  title: "example",
  operations: []
});