Flow Endpoints

Complete API reference for flow operations

This page documents all available operations for creating, managing, and monitoring flows on the Mirra platform.

Create Time-Based Flow

Create a new flow with a cron schedule trigger.

Endpoint

POST /api/sdk/v1/flows/createTimeFlow

Request Body

{
  "title": "Daily Report Generator",
  "description": "Generates daily analytics report and sends via email",
  "schedule": "0 9 * * *",
  "scriptId": "script_abc123",
  "scope": "user"
}

Parameters

title *: Flow name for identification and organization.
description *: Detailed description of what the flow does and when it runs.
schedule *: Cron expression defining when the flow executes. Must be a valid cron pattern.
scriptId *: The ID of the script to execute. All flows are script-based.
scope: Execution scope. One of: "user" (default), "team", "global".

Response

{
  "success": true,
  "data": {
    "id": "693439915ceadf632e2cfc9a",
    "userId": "507f1f77bcf86cd799439011",
    "title": "Daily Report Generator",
    "description": "Generates daily analytics report and sends via email",
    "status": "active",
    "scope": "user",
    "trigger": {
      "type": "time",
      "config": {
        "cronExpression": "0 9 * * *"
      }
    },
    "scriptId": "script_abc123",
    "executionCount": 0,
    "executionResults": [],
    "createdAt": "2025-12-06T14:11:29.385Z",
    "updatedAt": "2025-12-06T14:11:29.385Z"
  }
}

Create Event-Based Flow

Create a new flow that executes when matching events occur.

Endpoint

POST /api/sdk/v1/flows/createEventFlow

Request Body

{
  "title": "Urgent Message Handler",
  "description": "Auto-respond to urgent messages in Telegram",
  "eventType": "telegram.message",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "text",
        "operator": "contains",
        "value": "urgent"
      },
      {
        "field": "isGroupChat",
        "operator": "equals",
        "value": false
      }
    ]
  },
  "prompt": "Acknowledge the urgent message and create a high-priority reminder",
  "recommendedTools": ["telegram", "memory"],
  "scope": "user",
  "executionType": "llm"
}

Parameters

title *: Flow name for identification and organization.
description *: Detailed description of what the flow does and which events trigger it.
eventType *: Type of event to subscribe to (e.g., "telegram.message", "gmail.email_received", "calendar.event_created").
conditions *: Condition tree defining when the flow executes. Supports nested AND/OR logic with field comparisons.
prompt *: Natural language instructions for the AI agent (when using LLM execution mode).
recommendedTools: Array of tool names the flow should prioritize.
scope: Execution scope. One of: "user" (default), "team", "global".
executionType: How the flow executes. One of: "llm" (default), "direct".

Response

{
  "success": true,
  "data": {
    "id": "693439aa5ceadf632e2cfcb2",
    "userId": "507f1f77bcf86cd799439011",
    "title": "Urgent Message Handler",
    "description": "Auto-respond to urgent messages in Telegram",
    "status": "active",
    "scope": "user",
    "trigger": {
      "type": "event",
      "config": {
        "eventType": "telegram.message",
        "rootCondition": {
          "operator": "AND",
          "conditions": [
            {
              "field": "text",
              "operator": "contains",
              "value": "urgent"
            },
            {
              "field": "isGroupChat",
              "operator": "equals",
              "value": false
            }
          ]
        }
      }
    },
    "executionType": "llm",
    "prompt": "Acknowledge the urgent message and create a high-priority reminder",
    "recommendedTools": ["telegram", "memory"],
    "executionCount": 0,
    "executionResults": [],
    "createdAt": "2025-12-06T14:15:42.100Z",
    "updatedAt": "2025-12-06T14:15:42.100Z"
  }
}

List Flows

Retrieve all flows for the authenticated user.

Endpoint

POST /api/sdk/v1/flows/listFlows

Request Body

{
  "status": "active",
  "limit": 20,
  "offset": 0
}

Parameters

status: Filter by flow status. One of: "active", "paused", "completed". Omit to include all statuses.
limit: Maximum number of flows to return. Default: 50. Max: 100.
offset: Number of flows to skip for pagination. Default: 0.

Response

{
  "success": true,
  "data": [
    {
      "id": "693439915ceadf632e2cfc9a",
      "title": "Daily Report Generator",
      "description": "Generates daily analytics report",
      "status": "active",
      "trigger": {
        "type": "time",
        "config": {
          "cronExpression": "0 9 * * *"
        }
      },
      "executionCount": 45,
      "lastExecutedAt": "2025-12-06T09:00:00Z",
      "createdAt": "2025-11-01T10:00:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "limit": 20,
    "offset": 0
  }
}

Get Flow

Retrieve detailed information about a specific flow.

Endpoint

POST /api/sdk/v1/flows/getFlow

Request Body

{
  "assignmentId": "693439915ceadf632e2cfc9a"
}

Response

{
  "success": true,
  "data": {
    "id": "693439915ceadf632e2cfc9a",
    "userId": "507f1f77bcf86cd799439011",
    "title": "Daily Report Generator",
    "description": "Generates daily analytics report and sends via email",
    "status": "active",
    "scope": "user",
    "trigger": {
      "type": "time",
      "config": {
        "cronExpression": "0 9 * * *"
      }
    },
    "executionType": "llm",
    "prompt": "Generate yesterday's analytics report and send it via Gmail",
    "recommendedTools": ["memory", "gmail"],
    "executionCount": 45,
    "executionResults": [
      {
        "timestamp": "2025-12-06T09:00:00Z",
        "status": "success",
        "duration": 3421,
        "cost": 0.042
      }
    ],
    "lastExecutedAt": "2025-12-06T09:00:00Z",
    "createdAt": "2025-11-01T10:00:00Z",
    "updatedAt": "2025-12-06T09:00:05Z"
  }
}

Update Flow

Update a flow's configuration, schedule, or execution parameters.

Endpoint

POST /api/sdk/v1/flows/updateFlow

Request Body

{
  "assignmentId": "693439915ceadf632e2cfc9a",
  "title": "Updated Daily Report",
  "description": "Updated description",
  "schedule": "0 10 * * *",
  "prompt": "Updated execution prompt",
  "recommendedTools": ["memory", "gmail", "telegram"]
}

Parameters

assignmentId *: ID of the flow to update.
title: Updated flow name.
description: Updated description.
schedule: Updated cron expression (for time-based flows).
prompt: Updated execution prompt.
recommendedTools: Updated tool recommendations.
conditions: Updated event conditions (for event-based flows).

Response

{
  "success": true,
  "data": {
    "id": "693439915ceadf632e2cfc9a",
    "title": "Updated Daily Report",
    "description": "Updated description",
    "trigger": {
      "type": "time",
      "config": {
        "cronExpression": "0 10 * * *"
      }
    },
    "updatedAt": "2025-12-06T14:20:00Z"
  }
}

Pause Flow

Temporarily disable a flow without deleting it.

Endpoint

POST /api/sdk/v1/flows/pauseFlow

Request Body

{
  "assignmentId": "693439915ceadf632e2cfc9a"
}

Response

{
  "success": true,
  "data": {
    "id": "693439915ceadf632e2cfc9a",
    "status": "paused",
    "pausedAt": "2025-12-06T14:25:00Z"
  }
}

Resume Flow

Re-enable a paused flow.

Endpoint

POST /api/sdk/v1/flows/resumeFlow

Request Body

{
  "assignmentId": "693439915ceadf632e2cfc9a"
}

Response

{
  "success": true,
  "data": {
    "id": "693439915ceadf632e2cfc9a",
    "status": "active",
    "resumedAt": "2025-12-06T14:30:00Z"
  }
}

Delete Flow

Permanently delete a flow and all associated execution history.

Endpoint

POST /api/sdk/v1/flows/deleteFlow

Request Body

{
  "assignmentId": "693439915ceadf632e2cfc9a"
}

Response

{
  "success": true,
  "data": {
    "id": "693439915ceadf632e2cfc9a",
    "deleted": true,
    "deletedAt": "2025-12-06T14:35:00Z"
  }
}

This action cannot be undone! Deleting a flow removes all execution history and cannot be recovered.

Search Flows

Search and filter flows by status, trigger type, execution results, and metadata.

Endpoint

POST /api/sdk/v1/flows/searchFlows

Request Body

{
  "query": "daily report",
  "status": "active",
  "trigger": {
    "type": "time"
  },
  "scope": "user",
  "limit": 20,
  "offset": 0
}

Parameters

query: Search term to match against flow titles and descriptions.
status: Filter by flow status.
trigger: Filter by trigger configuration (type, eventType, etc.).
scope: Filter by execution scope.
limit: Maximum results to return. Default: 50. Max: 100.
offset: Number of results to skip for pagination.

Response

{
  "success": true,
  "data": [
    {
      "id": "693439915ceadf632e2cfc9a",
      "title": "Daily Report Generator",
      "description": "Generates daily analytics report",
      "status": "active",
      "trigger": {
        "type": "time",
        "config": {
          "cronExpression": "0 9 * * *"
        }
      },
      "executionCount": 45,
      "lastExecutedAt": "2025-12-06T09:00:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "limit": 20,
    "offset": 0
  }
}

Error Responses

All endpoints return consistent error responses:

Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid cron expression: Expected 5 or 6 fields, got 4",
    "details": {
      "field": "schedule",
      "value": "0 9 * *"
    }
  }
}

Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Flow not found",
    "details": {
      "assignmentId": "693439915ceadf632e2cfc9a"
    }
  }
}

Internal Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal error occurred"
  }
}

Rate Limits

API requests are subject to rate limiting:

Authenticated requests: 1000 requests per minute
Flow creation: 100 flows per day
Flow execution: 10,000 executions per day per flow

Rate limit information is included in response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1638360000

Flow Endpoints

On this page