mirra-flows

name	mirra-flows
description	Use Mirra to internal automation system for time-based and event-based task execution. Covers all Flows SDK operations via REST API.
allowed-tools	Read, Bash(curl:*, jq:*)

Mirra Flows

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

Prerequisites

You need the user's API key. Ask for these if not provided:

• API_KEY: Mirra API key (generated in Mirra app > Settings > API Keys)
• API_URL: Defaults to https://api.fxn.world (only ask if they mention a custom server)

API Call Pattern

All operations use a single POST endpoint with the resource ID and method in the body:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{
    "resourceId": "flows",
    "method": "{operation}",
    "params": { ...args }
  }' | jq .

Replace {operation} with the operation name from the table below.

Legacy alternative: POST ${API_URL}/api/sdk/v1/flows/{operation} with args as the request body also works but is not recommended for new integrations.

Available Operations

Operation	Description
createFlow	Create a flow (event-triggered or time-scheduled). This is the unified, simplified interface for ...
createTimeFlow	Create a new time-based flow with cron schedule. NOTE: Consider using createFlow instead for a si...
createEventFlow	Create an event-based flow with pre-filtering conditions. NOTE: Consider using createFlow instead...
getFlow	Get a specific flow by ID. Returns normalized flat structure. Use includeScript=true to also retu...
updateFlow	Update an existing flow. Returns normalized flat structure.
modifyFlowScript	Replace the ENTIRE script code for a flow. For small changes, prefer editFlowScript instead — it ...
readFlowScript	Read the script code for a flow with line numbers. Supports optional line range to read a portion...
editFlowScript	Apply surgical edits to a flow's script code using oldText/newText pairs. Each edit replaces an e...
executeFlow	Execute a flow on-demand with custom input. The input object is merged into the flow's scriptInpu...
deleteFlow	Delete a flow
pauseFlow	Pause an active flow. Returns normalized flat structure.
resumeFlow	Resume a paused flow. Returns normalized flat structure.
searchFlows	Search flows with filters. Default returns minimal info (id, title, status, triggerType, isActive...
recordExecution	Record execution result for a flow. Returns normalized flat structure.
listEventTypes	List available event types that can trigger automations. Returns normalized event types. Filter b...
testFlow	Test a flow by generating an event that matches the trigger conditions.
validateTrigger	Check if a custom event would match a flow trigger without any execution. Useful for debugging tr...
getFlowsByEventType	Get all active flows triggered by a specific event type. Default returns minimal info (id, title,...
createBatchOperation	Create a self-managing flow that processes multiple adapter operations over time, respecting rate...
publishFlow	Publish a flow to the marketplace so other users can discover and install it. The flow must have ...
unpublishFlow	Remove a flow from the marketplace. Existing installations will continue to work.

Operation Details

createFlow

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

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 or path.
• path (string, optional): Path to a script file in the workspace container (e.g., "/workspace/flows/handler.js"). If provided, code is read from this file. Optionally reads flow.json from the same directory for trigger config. Cannot use with code or scriptId.
• scriptId (string, optional): ID of existing deployed script. Cannot use with code or path.
• 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"). Use ONLY when you need to process every single event of this type. For filtering a subset of events, use eventFilter instead.
• eventFilter (object, optional): Event filter for pre-filtering events before the script runs (evaluated in-memory, free).

SIMPLE FORMAT (recommended): Pass a flat object with "when" set to the event type, then field aliases as keys. { "when": "telegram.bot_message", "chat_id": "-1001234567890", "message_text_contains": "urgent" }

Add _contains, _gt, _lt, _not, _starts_with, _ends_with, _matches, _in suffixes for non-equals operators. Default operator is equals when no suffix is given. Arrays auto-detect as "in" operator.

VALID FIELD ALIASES per event type (use these — do NOT use event.data.* paths here): telegram.bot_message: chat_id, chat_type, sender_username, sender_user_id, message_text, bot_username, has_media, media_type telegram.bot_command: command, chat_id, chat_type, sender_username, sender_user_id, bot_username telegram.bot_callback_query: chat_id, callback_data, sender_username, bot_username telegram.message: chat_id, is_group_chat, has_media, message_text gmail.email_received: from_email, from_name, subject, has_attachments, is_unread, body_text call.ended: duration_seconds, was_recorded, scope crypto_price_update: price_usd, token_address, chain recording.transcribed: duration_seconds, speaker_count, transcript_text flow.complete: flow_title, flow_success, flow_type All event types: event_type, sender_name, sender_id, content_text, channel_id, channel_name

ADVANCED FORMAT (full condition tree — for OR logic, regex, or nested conditions): { "operator": "or", "conditions": [ { "operator": "equals", "field": "bot.chatId", "value": "123" }, { "operator": "equals", "field": "bot.chatId", "value": "456" } ]}

Valid operators: equals, notEquals, contains, startsWith, endsWith, greaterThan, lessThan, in, notIn, exists, notExists, matchesRegex, and, or, not

• trigger (object, optional): Legacy nested trigger structure. Prefer eventType or eventFilter instead.
• scriptInput (object, optional): Static input data passed to the script. Fields are spread into event.data, so scriptInput: { apiKey: "sk-123" } is accessed as event.data.apiKey in handler code. The linter validates code against these fields.
• scriptInputSchema (object, optional): Schema describing scriptInput fields (auto-inferred from scriptInput values if not provided). Keys are field names, values are { type: "string"|"number"|"boolean"|"object"|"array", required?: boolean, description?: string }. When provided, the linter can catch typos in event.data.fieldName access as errors instead of warnings.
• enabled (boolean, optional): Whether the flow is enabled (default: true)
• webhook (boolean, optional): Set to true to create a webhook-triggered flow. Returns a webhookUrl in the response. External services POST to this URL to trigger the flow. The request body is available as event.fields.body in the handler (event.data.body is NOT populated for webhook flows).
• parentSpaceId (string, optional): Group/space ID to scope this flow to. When set, the flow executes with group context and accesses the group's data instead of the user's personal data. If omitted, auto-inherited from the current group context (if any).

Returns:

NormalizedFlow: Returns FLAT flow object with: id, title, description, status, scope, userId, parentSpaceId, triggerType, cronExpression, timezone, eventFilter, scriptId, scriptInstallationId, scriptInput, scriptInputSchema, executionCount, lastExecutedAt, createdAt, updatedAt, version, feedItemId, isActive, isTimeBased, isEventBased. For webhook flows, also includes webhookUrl and webhookId. No nested trigger object.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"createFlow","params":{"path":"/workspace/flows/weather-bot/handler.js"}}' | jq .

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): Static input data passed to the script. Fields are spread into event.data (e.g., scriptInput: { apiKey: "sk-123" } → event.data.apiKey in handler).
• scriptInputSchema (object, optional): Schema describing scriptInput fields (auto-inferred from scriptInput values if not provided). Keys are field names, values are { type, required?, description? }.

Returns:

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"createTimeFlow","params":{"title":"<value>","description":"<value>","schedule":"<value>","scriptId":"<ID>"}}' | jq .

createEventFlow

Create an event-based flow with pre-filtering conditions. 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
• 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): Static input data passed to the script. Fields are spread into event.data (e.g., scriptInput: { apiKey: "sk-123" } → event.data.apiKey in handler).
• scriptInputSchema (object, optional): Schema describing scriptInput fields (auto-inferred from scriptInput values if not provided). Keys are field names, values are { type, required?, description? }.

Returns:

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"createEventFlow","params":{"title":"VIP Message Handler","description":"Process messages from VIP contact","trigger":{"type":"event","config":{"eventFilter":{"operator":"and","conditions":[{"operator":"equals","field":"type","value":"telegram.message"},{"operator":"equals","field":"actor.id","value":"12345"}]}}},"scriptId":"script-id-here"}}' | jq .

getFlow

Get a specific flow by ID. Returns normalized flat structure. Use includeScript=true to also return the flow's script code.

Arguments:

• id (string, required): Flow ID (24-character hex string returned by createFlow/createEventFlow). Get IDs from the flow creation response or by searching flows.
• includeScript (boolean, optional): Include the flow's script code in the response. Default: false.

Returns:

NormalizedFlow: Returns FLAT flow object with: id, title, description, status, scope, userId, triggerType, cronExpression, timezone, eventFilter, scriptId, scriptInstallationId, scriptInput, scriptInputSchema, executionCount, lastExecutedAt, createdAt, updatedAt, version, feedItemId, isActive, isTimeBased, isEventBased. No nested trigger object. When includeScript=true, also includes scriptCode.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"getFlow","params":{"id":"<ID>"}}' | jq .

updateFlow

Update an existing flow. Returns normalized flat structure.

Arguments:

• id (string, required): Flow ID to update (24-character hex string returned by createFlow/createEventFlow)
• 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 static input data for the script. Fields are spread into event.data in handler code.
• scriptInputSchema (object, optional): Schema describing scriptInput fields. Keys are field names, values are { type, required?, description? }.
• status (string, optional): New status: active, paused, completed, failed
• parentSpaceId (string, optional): Group/space ID to scope this flow to. When set, the flow executes with group context and accesses the group's data instead of the user's personal data. Set to empty string to remove group scope.
• 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"). Use ONLY when you need to process every single event of this type. For filtering a subset of events, use eventFilter instead.
• eventFilter (object, optional): Event filter with operator and conditions array. RECOMMENDED for most event flows — lets you pre-filter events before Lambda invocation (free, in-memory). Example: { operator: "and", conditions: [{ operator: "equals", field: "type", value: "telegram.message" }, { operator: "startsWith", field: "content.text", value: "/" }] }

Returns:

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"updateFlow","params":{"id":"<ID>"}}' | jq .

modifyFlowScript

Replace the ENTIRE script code for a flow. For small changes, prefer editFlowScript instead — it only requires the changed portions. Use modifyFlowScript only when rewriting more than ~50% of the code or creating a script from scratch.

Arguments:

• flowId (string, required): Flow ID to modify (24-character hex string)
• newCode (string, optional): New handler code. Must include export async function handler(event, context, mirra) wrapper. Required unless path is provided.
• path (string, optional): Path to a script file in the workspace container (e.g., "/workspace/flows/my-handler/handler.js"). If provided, code is read from this file instead of newCode.
• commitMessage (string, optional): Description of changes (optional)

Returns:

object: Returns: { copied (boolean - true if a private copy was created), scriptId, versionId, version }

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"modifyFlowScript","params":{"flowId":"507f1f77bcf86cd799439011","path":"/workspace/flows/my-handler/handler.js","commitMessage":"Rewrite handler to filter by current user only"}}' | jq .

Example response:

{
  "copied": true,
  "scriptId": "507f1f77bcf86cd799439015",
  "versionId": "507f1f77bcf86cd799439016",
  "version": 1
}

readFlowScript

Read the script code for a flow with line numbers. Supports optional line range to read a portion of the script. Use this before editFlowScript to see the current code.

Arguments:

• flowId (string, required): Flow ID (24-character hex string)
• startLine (number, optional): First line to return (1-indexed). Default: 1
• endLine (number, optional): Last line to return (inclusive). Default: end of file

Returns:

object: Returns: { scriptId, version, totalLines, startLine, endLine, code (with line numbers) }

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"readFlowScript","params":{"flowId":"507f1f77bcf86cd799439011"}}' | jq .

Example response:

{
  "scriptId": "507f1f77bcf86cd799439012",
  "version": 2,
  "totalLines": 25,
  "startLine": 1,
  "endLine": 25,
  "code": " 1\texport async function handler(event, context, mirra) {\n 2\t  const data = event.data;\n..."
}

editFlowScript

Apply surgical edits to a flow's script code using oldText/newText pairs. Each edit replaces an exact text match. Much more efficient than modifyFlowScript for small changes — avoids rewriting the entire script. Use readFlowScript first to see current code.

Arguments:

• flowId (string, required): Flow ID (24-character hex string)
• edits (array, required): Array of edits. Each: { oldText: string (exact match in current code), newText: string (replacement) }. Applied sequentially. oldText must be unique in the code — include enough surrounding context.
• commitMessage (string, optional): Description of changes

Returns:

object: Returns: { copied, scriptId, versionId, version, linesChanged }

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"editFlowScript","params":{"flowId":"507f1f77bcf86cd799439011","edits":[{"oldText":"  const data = event.data.payload;","newText":"  const data = event.data.payload;\n  if (!data) return { success: false, noOp: true, reason: 'No payload' };"}],"commitMessage":"Add null check for payload"}}' | jq .

Example response:

{
  "copied": false,
  "scriptId": "507f1f77bcf86cd799439012",
  "versionId": "507f1f77bcf86cd799439016",
  "version": 3,
  "linesChanged": 2
}

executeFlow

Execute a flow on-demand with custom input. The input object is merged into the flow's scriptInput and passed to the handler as event.data fields. Returns the handler's return value along with execution metadata.

Arguments:

• flowId (string, required): Flow ID to execute (24-character hex string)
• input (object, optional): Dynamic input object passed to the flow handler via event.data. Fields are merged with the flow's static scriptInput (dynamic input takes precedence).

Returns:

FlowExecutionResult: Returns { success, result (handler return value), error, duration, executionId }

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"executeFlow","params":{"flowId":"507f1f77bcf86cd799439011","input":{"question":"How do I get started?","productId":"product_123"}}}' | jq .

Example response:

{
  "success": true,
  "executionId": "exec_abc123",
  "duration": 2340,
  "result": {
    "response": "To get started...",
    "sources": []
  }
}

deleteFlow

Delete a flow

Arguments:

• id (string, required): Flow ID to delete (24-character hex string returned by createFlow/createEventFlow)

Returns:

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

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"deleteFlow","params":{"id":"<ID>"}}' | jq .

pauseFlow

Pause an active flow. Returns normalized flat structure.

Arguments:

• id (string, required): Flow ID to pause (24-character hex string)

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.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"pauseFlow","params":{"id":"<ID>"}}' | jq .

resumeFlow

Resume a paused flow. Returns normalized flat structure.

Arguments:

• id (string, required): Flow ID to resume (24-character hex string)

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.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"resumeFlow","params":{"id":"<ID>"}}' | jq .

searchFlows

Search flows with filters. Default returns minimal info (id, title, status, triggerType, isActive). Use detail: "summary" for execution stats. Use getFlow for full details on a specific flow.

Arguments:

• status (string, optional): Filter by status (or array of statuses)
• triggerType (string, optional): Filter by trigger type: time or event
• parentSpaceId (string, optional): Filter flows by space/group ID. Only returns flows assigned to this space.
• detail (string, optional): Detail level: "minimal" (default) returns id, title, status, triggerType, isActive. "summary" adds description, cronExpression, scriptId, executionCount, lastExecutedAt, createdAt.
• limit (number, optional): Maximum number of results (default: 20)
• offset (number, optional): Pagination offset (default: 0)

Returns:

FlowSearchResult: Returns { count: number, flows: FlowListItem[] }. This is an OBJECT, not an array. Always use result.flows to access the array and result.count for the total. Do NOT use result.length or Array.isArray(result). Default minimal fields per flow: id, title, status, triggerType, isActive. With detail: "summary": adds description, userId, cronExpression, scriptId, executionCount, lastExecutedAt, createdAt.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"searchFlows","params":{}}' | jq .

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.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"recordExecution","params":{"id":"<ID>","success":true}}' | jq .

listEventTypes

List available event types that can trigger automations. Returns normalized event types. Filter by source or sources to narrow results (e.g., source: "telegram" or sources: ["telegram", "gmail"]).

Arguments:

• source (string, optional): Filter by source/category (e.g., "telegram", "gmail", "calendar"). Returns only event types from this source.
• sources (array, optional): Array of sources to filter by (e.g., ["telegram", "gmail"]). More efficient than separate calls.
• 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. Filter by source or sources to narrow results.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"listEventTypes","params":{}}' | jq .

testFlow

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

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.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"testFlow","params":{"flowId":"<ID>"}}' | jq .

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.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"validateTrigger","params":{"flowId":"<ID>","event":{}}}' | jq .

getFlowsByEventType

Get all active flows triggered by a specific event type. Default returns minimal info (id, title, status, triggerType, isActive). Use detail: "summary" for execution stats.

Arguments:

• eventType (string, required): Event type to filter by (e.g., "call.action", "call.ended", "telegram.message")
• detail (string, optional): Detail level: "minimal" (default) returns id, title, status, triggerType, isActive. "summary" adds description, cronExpression, scriptId, executionCount, lastExecutedAt, createdAt.

Returns:

FlowsByEventTypeResult: Returns { eventType: string, count: number, flows: FlowListItem[] }. This is an OBJECT, not an array. Always use result.flows to access the array. Do NOT use result.length.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"getFlowsByEventType","params":{"eventType":"<value>"}}' | jq .

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.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"createBatchOperation","params":{"title":"Leave old Telegram groups","operations":[{"adapter":"telegram","operation":"leaveGroup","args":{"groupId":"-100123"}},{"adapter":"telegram","operation":"leaveGroup","args":{"groupId":"-100456"}}],"batchSize":5,"intervalSeconds":60}}' | jq .

publishFlow

Publish a flow to the marketplace so other users can discover and install it. The flow must have a deployed script.

Arguments:

• flowId (string, required): ID of the flow to publish
• pricing (object, optional): Pricing configuration. Defaults to { model: "free" }. Supported models: "free", "pay-per-execution". For paid models, include basePrice.
• tags (array, optional): Tags for marketplace discovery (e.g., ["telegram", "automation"])
• category (string, optional): Marketplace category (e.g., "messaging", "productivity"). Defaults to "uncategorized".

Returns:

PublishFlowResult: Returns FLAT result with: flowId, isPublished, status, publishedAt, pricing, category, tags. No nested objects.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"publishFlow","params":{"flowId":"507f1f77bcf86cd799439011","tags":["telegram","notifications"],"category":"messaging"}}' | jq .

unpublishFlow

Remove a flow from the marketplace. Existing installations will continue to work.

Arguments:

• flowId (string, required): ID of the flow to unpublish

Returns:

UnpublishFlowResult: Returns FLAT result with: flowId, isPublished (false), status (archived). No nested objects.

Example:

curl -s -X POST "${API_URL}/api/sdk/v2/resources/call" \
  -H "Content-Type: application/json" \
  -H "x-api-key: ${API_KEY}" \
  -d '{"resourceId":"flows","method":"unpublishFlow","params":{"flowId":"<ID>"}}' | jq .

Response Format

All SDK responses return the operation payload wrapped in a standard envelope:

{
  "success": true,
  "data": { ... }
}

The data field contains the operation result. Error responses include:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Tips

• Use jq . to pretty-print responses, jq .data to extract just the payload
• For list operations, results are in data.results or directly in data (check examples)
• Pass --fail-with-body to curl to see error details on HTTP failures
• Store the API key in a variable: export API_KEY="your-key"