mirra-scripts

name	mirra-scripts
description	Use Mirra to execute user-defined scripts in aws lambda. Covers all Scripts SDK operations via REST API.
allowed-tools	Read, Bash(curl:*, jq:*)

Mirra Scripts

Execute user-defined scripts in AWS Lambda

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": "scripts",
    "method": "{operation}",
    "params": { ...args }
  }' | jq .

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

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

Available Operations

Operation	Description
createScript	Create a new script with initial version and API key. Returns flat structure with id field for su...
deleteScript	Delete a script and all its versions. Returns flat deletion confirmation.
createVersion	Create a new version by replacing the ENTIRE script code. For small changes, prefer editScriptCod...
listVersions	List all versions of a script. Returns flat version structures.
deployScript	Deploy a script version to AWS Lambda. Must be called after createScript to make the script execu...
executeScript	Execute a deployed script with custom data. Script must be deployed first via deployScript. Retur...
getScript	Get details of a specific script. Returns flat normalized structure.
listScripts	List all scripts owned by the user. Returns flat script summaries.
getExecutions	Get execution history for a script. Returns flat execution summaries.
getExecution	Get details of a specific execution. Returns flat execution structure.
getMetrics	Get execution metrics for a script. Returns flat metrics structure.
getFlowScript	Get the script code for a specific flow. Returns flat flow script structure.
modifyFlowScript	Replace the ENTIRE script code for a flow. For small changes, prefer editScriptCode or editFlowSc...
readScriptCode	Read the active version's code for a script with line numbers. Supports optional line range. Use ...
editScriptCode	Apply surgical edits to a script's active code using oldText/newText pairs. Each edit replaces an...
lintScript	Validate script code BEFORE creating or deploying. Checks for: 1) Missing async handler wrapper (...

Operation Details

createScript

Create a new script with initial version and API key. Returns flat structure with id field for subsequent operations.

Arguments:

• name (string, required): Name of the script
• description (string, optional): Description of what the script does
• runtime (string, optional): Lambda runtime (default: nodejs18)
• config (object, optional): Script configuration (timeout, memory, maxCostPerExecution, etc.)
• code (string, optional): Initial JavaScript/TypeScript code for the script. Required unless path is provided.
• path (string, optional): Path to a script file in the workspace container (e.g., "/workspace/scripts/handler.js"). If provided, code is read from this file. Optionally reads mirra.json from the same directory for config.

Returns:

object: Returns FLAT structure: { id, name, description, runtime, timeout, memory, activeVersion, isPublished, isPrivate, status, deploymentStatus, apiKey, installationId, createdAt }. Use data.id as scriptId for deployScript.

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":"scripts","method":"createScript","params":{"name":"Daily Report","description":"Sends a daily summary report","path":"/workspace/scripts/daily-report.js"}}' | jq .

Example response:

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Daily Report",
  "description": "Sends a daily summary report",
  "runtime": "nodejs18",
  "timeout": 30,
  "memory": 256,
  "activeVersion": 1,
  "isPublished": false,
  "isPrivate": false,
  "status": "draft",
  "deploymentStatus": "pending",
  "apiKey": "mirra_script_abc123...",
  "installationId": "507f1f77bcf86cd799439012",
  "createdAt": "2024-12-08T10:00:00Z"
}

deleteScript

Delete a script and all its versions. Returns flat deletion confirmation.

Arguments:

• scriptId (string, required): ID of the script to delete

Returns:

object: Returns FLAT structure: { deleted, scriptId, hardDeleted, installationsRemoved, preservedInstallations }

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":"scripts","method":"deleteScript","params":{"scriptId":"507f1f77bcf86cd799439011"}}' | jq .

Example response:

{
  "deleted": true,
  "scriptId": "507f1f77bcf86cd799439011",
  "hardDeleted": true,
  "installationsRemoved": 1,
  "preservedInstallations": 0
}

createVersion

Create a new version by replacing the ENTIRE script code. For small changes, prefer editScriptCode instead — it only requires the changed portions. Returns flat version details.

Arguments:

• scriptId (string, required): ID of the script
• code (string, required): Updated code for the new version
• commitMessage (string, optional): Description of changes in this version

Returns:

object: Returns FLAT structure: { id, scriptId, version, isActive, commitMessage, codeHash, createdAt, deployedAt }

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":"scripts","method":"createVersion","params":{"scriptId":"507f1f77bcf86cd799439011","code":"export async function handler(event) { /* fixed code */ }","commitMessage":"Fixed error handling"}}' | jq .

Example response:

{
  "id": "507f1f77bcf86cd799439013",
  "scriptId": "507f1f77bcf86cd799439011",
  "version": 2,
  "isActive": false,
  "commitMessage": "Fixed error handling",
  "codeHash": "abc123...",
  "createdAt": "2024-12-08T10:30:00Z",
  "deployedAt": ""
}

listVersions

List all versions of a script. Returns flat version structures.

Arguments:

• scriptId (string, required): ID of the script

Returns:

object: Returns { count, versions[] }. Each version has FLAT fields: id, scriptId, version, isActive, commitMessage, codeHash, createdAt, deployedAt.

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":"scripts","method":"listVersions","params":{"scriptId":"507f1f77bcf86cd799439011"}}' | jq .

Example response:

{
  "count": 2,
  "versions": [
    {
      "id": "...",
      "scriptId": "507f1f77bcf86cd799439011",
      "version": 2,
      "isActive": true,
      "commitMessage": "Fixed error handling",
      "codeHash": "abc...",
      "createdAt": "2024-12-08T10:30:00Z",
      "deployedAt": "2024-12-08T11:00:00Z"
    },
    {
      "id": "...",
      "scriptId": "507f1f77bcf86cd799439011",
      "version": 1,
      "isActive": false,
      "commitMessage": "Initial version",
      "codeHash": "def...",
      "createdAt": "2024-12-08T10:00:00Z",
      "deployedAt": ""
    }
  ]
}

deployScript

Deploy a script version to AWS Lambda. Must be called after createScript to make the script executable.

Arguments:

• scriptId (string, required): ID of the script to deploy (from createScript response at data._id)
• version (number, optional): Version number to deploy (default: latest)

Returns:

object: Returns { success: true, data: { scriptId, version, lambdaFunctionName, lambdaArn, deployedAt } }

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":"scripts","method":"deployScript","params":{"scriptId":"507f1f77bcf86cd799439011"}}' | jq .

Example response:

{
  "scriptId": "507f1f77bcf86cd799439011",
  "version": 2,
  "lambdaFunctionName": "mirra-script-...",
  "lambdaArn": "arn:aws:lambda:...",
  "deployedAt": "2024-12-08T10:30:00Z"
}

executeScript

Execute a deployed script with custom data. Script must be deployed first via deployScript. Returns flat execution result.

Arguments:

• scriptId (string, required): ID of the script to execute (from createScript response at data.id)
• data (object, optional): Input data to pass to the script. Available inside the handler as event.data (also aliased to event.input, event.body, event.payload).
• trigger (object, optional): Trigger information (type, source, event)

Returns:

object: Returns FLAT structure: { executionId, scriptId, status, output, duration, logs[], error, 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":"scripts","method":"executeScript","params":{"scriptId":"507f1f77bcf86cd799439011","data":{"userId":"123","reportType":"weekly"}}}' | jq .

Example response:

{
  "executionId": "exec_507f1f77bcf86cd799439015",
  "scriptId": "507f1f77bcf86cd799439011",
  "status": "completed",
  "output": {
    "message": "Report generated"
  },
  "duration": 1250,
  "logs": [
    "Starting report generation...",
    "Report complete"
  ],
  "error": "",
  "createdAt": "2024-12-08T10:35:00Z"
}

getScript

Get details of a specific script. Returns flat normalized structure.

Arguments:

• scriptId (string, required): ID of the script

Returns:

object: Returns FLAT structure: { id, name, description, runtime, timeout, memory, activeVersion, isPublished, isPrivate, status, deploymentStatus, lambdaFunctionName, lambdaArn, totalExecutions, totalCost, avgDuration, errorRate, createdAt, deployedAt, publishedAt, lastExecutedAt }

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":"scripts","method":"getScript","params":{"scriptId":"507f1f77bcf86cd799439011"}}' | jq .

Example response:

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Daily Report",
  "description": "Sends a daily summary report",
  "runtime": "nodejs18",
  "timeout": 30,
  "memory": 256,
  "activeVersion": 2,
  "isPublished": false,
  "isPrivate": false,
  "status": "draft",
  "deploymentStatus": "deployed",
  "lambdaFunctionName": "mirra-script-...",
  "lambdaArn": "arn:aws:lambda:...",
  "totalExecutions": 150,
  "totalCost": 0.05,
  "avgDuration": 850,
  "errorRate": 0.02,
  "createdAt": "2024-12-08T10:00:00Z",
  "deployedAt": "2024-12-08T10:30:00Z",
  "publishedAt": "",
  "lastExecutedAt": "2024-12-08T15:00:00Z"
}

listScripts

List all scripts owned by the user. Returns flat script summaries.

Returns:

object: Returns { count, scripts[] }. Each script has FLAT fields: id, name, description, activeVersion, isPublished, status, deploymentStatus, totalExecutions, 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":"scripts","method":"listScripts","params":{}}' | jq .

Example response:

{
  "count": 2,
  "scripts": [
    {
      "id": "...",
      "name": "Daily Report",
      "description": "...",
      "activeVersion": 2,
      "isPublished": false,
      "status": "draft",
      "deploymentStatus": "deployed",
      "totalExecutions": 150,
      "createdAt": "2024-12-08T10:00:00Z"
    },
    {
      "id": "...",
      "name": "Data Processor",
      "description": "...",
      "activeVersion": 1,
      "isPublished": false,
      "status": "draft",
      "deploymentStatus": "pending",
      "totalExecutions": 0,
      "createdAt": "2024-12-09T10:00:00Z"
    }
  ]
}

getExecutions

Get execution history for a script. Returns flat execution summaries.

Arguments:

• scriptId (string, required): ID of the script
• status (string, optional): Filter by status (completed, failed, running)
• limit (number, optional): Maximum number of executions to return (default: 100)

Returns:

object: Returns { scriptId, count, executions[] }. Each execution has FLAT fields: executionId, scriptId, status, duration, createdAt, hasError.

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":"scripts","method":"getExecutions","params":{"scriptId":"507f1f77bcf86cd799439011","limit":10}}' | jq .

Example response:

{
  "scriptId": "507f1f77bcf86cd799439011",
  "count": 2,
  "executions": [
    {
      "executionId": "exec_001",
      "scriptId": "507f1f77bcf86cd799439011",
      "status": "completed",
      "duration": 1250,
      "createdAt": "2024-12-08T15:00:00Z",
      "hasError": false
    },
    {
      "executionId": "exec_002",
      "scriptId": "507f1f77bcf86cd799439011",
      "status": "failed",
      "duration": 500,
      "createdAt": "2024-12-08T14:00:00Z",
      "hasError": true
    }
  ]
}

getExecution

Get details of a specific execution. Returns flat execution structure.

Arguments:

• executionId (string, required): ID of the execution

Returns:

object: Returns FLAT structure: { executionId, scriptId, status, output, duration, logs[], error, 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":"scripts","method":"getExecution","params":{"executionId":"exec_123"}}' | jq .

Example response:

{
  "executionId": "exec_123",
  "scriptId": "507f1f77bcf86cd799439011",
  "status": "completed",
  "output": {
    "message": "Success"
  },
  "duration": 1250,
  "logs": [
    "Log line 1",
    "Log line 2"
  ],
  "error": "",
  "createdAt": "2024-12-08T15:00:00Z"
}

getMetrics

Get execution metrics for a script. Returns flat metrics structure.

Arguments:

• scriptId (string, required): ID of the script

Returns:

object: Returns FLAT structure: { scriptId, totalExecutions, totalCost, avgDuration, successRate, errorRate, lastExecutedAt }

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":"scripts","method":"getMetrics","params":{"scriptId":"507f1f77bcf86cd799439011"}}' | jq .

Example response:

{
  "scriptId": "507f1f77bcf86cd799439011",
  "totalExecutions": 1250,
  "totalCost": 0.45,
  "avgDuration": 850,
  "successRate": 0.98,
  "errorRate": 0.02,
  "lastExecutedAt": "2024-12-08T15:30:00Z"
}

getFlowScript

Get the script code for a specific flow. Returns flat flow script structure.

Arguments:

• flowId (string, required): ID of the flow to get script code for

Returns:

object: Returns FLAT structure: { code, version, scriptId, scriptName, description, isOwned }

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":"scripts","method":"getFlowScript","params":{"flowId":"507f1f77bcf86cd799439011"}}' | jq .

Example response:

{
  "code": "export async function handler(event) { ... }",
  "version": 1,
  "scriptId": "507f1f77bcf86cd799439012",
  "scriptName": "Call Summary Generator",
  "description": "Generates call summaries",
  "isOwned": false
}

modifyFlowScript

Replace the ENTIRE script code for a flow. For small changes, prefer editScriptCode or editFlowScript instead — they only require the changed portions. Use this only when rewriting more than ~50% of the code.

Arguments:

• flowId (string, required): ID of the flow to modify
• newCode (string, required): New code to deploy
• commitMessage (string, optional): Description of changes

Returns:

object: Returns FLAT structure: { copied, 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":"scripts","method":"modifyFlowScript","params":{"flowId":"507f1f77bcf86cd799439011","newCode":"export async function handler(event) { /* modified */ }","commitMessage":"Filter by current user only"}}' | jq .

Example response:

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

readScriptCode

Read the active version's code for a script with line numbers. Supports optional line range. Use this before editScriptCode to see the current code.

Arguments:

• scriptId (string, required): Script ID
• 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":"scripts","method":"readScriptCode","params":{"scriptId":"507f1f77bcf86cd799439011"}}' | jq .

Example response:

{
  "scriptId": "507f1f77bcf86cd799439011",
  "version": 2,
  "totalLines": 30,
  "startLine": 1,
  "endLine": 30,
  "code": " 1\texport async function handler(event, context, mirra) {\n 2\t  ..."
}

editScriptCode

Apply surgical edits to a script's active code using oldText/newText pairs. Each edit replaces an exact text match. Much more efficient than createVersion for small changes. Use readScriptCode first to see current code.

Arguments:

• scriptId (string, required): Script ID
• edits (array, required): Array of edits. Each: { oldText: string (exact match in current code), newText: string (replacement) }. Applied sequentially.
• commitMessage (string, optional): Description of changes

Returns:

object: Returns: { 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":"scripts","method":"editScriptCode","params":{"scriptId":"507f1f77bcf86cd799439011","edits":[{"oldText":"cosnt result","newText":"const result"}],"commitMessage":"Fix typo"}}' | jq .

Example response:

{
  "versionId": "507f1f77bcf86cd799439016",
  "version": 3,
  "linesChanged": 1
}

lintScript

Validate script code BEFORE creating or deploying. Checks for: 1) Missing async handler wrapper (top-level await errors), 2) Invalid adapter operations, 3) Invalid event.data field access (when eventType provided). Returns flat validation results with suggestions for fixes. ALWAYS use this before createScript/modifyFlowScript.

Arguments:

• code (string, required): The script code to validate
• eventType (string, optional): Event type for event.data field validation (e.g., "telegram.message", "call.ended"). When provided, validates that event.data.fieldName accesses match the event type schema.
• scriptInputSchema (object, optional): Schema of scriptInput fields that will be on event.data at runtime. Keys are field names, values are { type: "string"|"number"|"boolean"|"object"|"array" }. When provided, event.data field errors are reported as errors instead of warnings.

Returns:

object: Returns FLAT structure: { valid, issueCount, issues[], callAdapterCallsCount, mirraSDKCallsCount }. Each issue has: severity, message, line, suggestion.

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":"scripts","method":"lintScript","params":{"code":"export async function handler(event, context, mirra) { const messages = await mirra.telegram.getChatMessages({ chatId: \"123\" }); return { messages }; }"}}' | jq .

Example response:

{
  "valid": true,
  "issueCount": 0,
  "issues": [],
  "callAdapterCallsCount": 0,
  "mirraSDKCallsCount": 1
}

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"