Canvas REST API Documentation

Overview

The Canvas REST API enables your organization to interact with Canvas programmatically. Use this API to register new accounts and build integration workflows between third-party applications.

This page documents the REST resources available in Canvas, including the HTTP response codes and example requests and responses.

Base URL:

DEV - https://canvastest.connectmyapps.com/api

PRD - https://canvas.connectmyapps.com/api

Authentication: API Key authentication (Public/Private key pairs)

Generate Your API Keys and IP restriction: https://canvas.connectmyapps.com/account/security/api-keys

You can send Canvas REST API requests from any server by default. If you want to restict access by IP addresses, then click edit on your api-keyes and enter your IP addresses to restriction list.

Content-Type: application/json

Getting Started
Authentication
API Metadata
Application Management
Workflow Templates
Block Templates
Account Management
Registered Applications
Workflow Management
Workflow Execution
Scheduler Management
Webhook Management
Vault Operations
JavaScript Functions
Remote API Calls
Results & Logs
Tag Management
Error Handling

Getting Started

Generate API Keys

Before you can use the Canvas API, you need to generate API keys:

Log in to your Canvas account
Navigate to: https://canvas.connectmyapps.com/account/security/api-keys
Click "Create secret key"
Set IP restriction list, if it is needed
Copy your Consumer and Secret Key and save it in secure store. Important: Store your secret key securely - it won't be shown again!
Click Apply button

Authentication Headers

All API requests require authentication headers:

SecretKey: {your-secret-key}
Consumer: {your-public-key}

If you have access to another accounts of your organization then you can manage it by ManagedAccountId header

ManagedAccountId: {managed-account-Id}

Call the endpoints from the (#account-management) section to retrieve a list of accounts you have access to.

Quick Start Example

curl -X GET "https://<base-url>/api/Authenticate" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Authentication

Authenticate

Endpoint: GET /api/Authenticate

Description: Authenticates the current account using API keys and returns account information.

Request Example 1:

curl -X GET "https://<base-url>/api/Authenticate" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK:

{
  "myAccount": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "user@example.com",
    "organizationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "organizationName": "Acme Corp",
    "role": "User"
  }
}

Request Example 2:

curl -X GET "https://<base-url>/api/Authenticate" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "ManagedAccountId: managed-account-Id"

Response 200 OK:

{
  "myAccount": {
    "id": "9c2866fa-4c48-44ea-878e-22a5b794e66e",
    "email": "superPartner@example.com",
    "organizationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "organizationName": "Acme Corp",
    "role": "SuperPartner"
  },
  "managedAccount": {
    "id": "8b7a5632-8941-4873-a3dc-3f962c88bcd4",
    "email": "client@example.com",
    "organizationId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "organizationName": "Acme Corp",
    "role": "User"
  }
}

Notes:

myAccount: Your authenticated user account
managedAccount: The account you're currently managing (for partner/manager scenarios)
If you're not managing another account, only myAccount is returned

Response 401 Unauthorized: Invalid or missing API keys

API Metadata

GetMetaData

Endpoint: GET /api/GetMetaData

Description: Returns metadata about all available API endpoints including routes, parameters, and response schemas.

Request Example:

curl -X GET "https://<base-url>/api/GetMetaData" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Array of endpoint metadata objects

Response Structure:

[
  {
    "name": "WorkflowTemplate",
    "route": "/api/WorkflowTemplate/{id}",
    "verb": "GET",
    "description": "Retrieves workflow template details",
    "authenticate": true,
    "parameters": "id={guid}&isDraft={bool}",
    "parametersSchema": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "format": "uuid",
          "required": true
        },
        "isDraft": {
          "type": "boolean",
          "required": false
        }
      }
    },
    "requestBodySchema": { },
    "requestBodyExample": { },
    "responseSchema": { },
    "responseExample": { },
    "responseCodes": {
      "200": "OK",
      "404": "Not Found"
    }
  }
]

Metadata Fields:

name: Method name
route: Full API route with path parameters
verb: HTTP method (GET, POST, PUT, PATCH, DELETE)
description: Human-readable description
authenticate: Whether authentication is required (optional)
parameters: Simple parameter string format param1={type}&param2={type} (optional)
parametersSchema: Detailed JSON schema for parameters (optional)
requestBodySchema: JSON schema for request body (optional)
requestBodyExample: Example request body (optional)
responseSchema: JSON schema for response (optional)
responseExample: Example response (optional)
responseCodes: HTTP status codes with descriptions

Use Case: Dynamic API discovery and documentation generation

Describe

Endpoint: GET /api/Describe?name={dtoName}

Description: Returns property descriptions for a specific DTO (Data Transfer Object).

Parameters:

name (query, required): DTO class name (e.g., "WorkflowApiDto")

Request Example:

curl -X GET "https://<base-url>/api/Describe?name=WorkflowApiDto" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Array of property definitions with types and descriptions

Response 404 Not Found: DTO name not found

GetSchema

Endpoint: GET /api/GetSchema?name={dtoName}

Description: Returns JSON schema definition for a specific DTO.

Parameters:

name (query, required): DTO class name

Request Example:

curl -X GET "https://<base-url>/api/GetSchema?name=WorkflowApiDto" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: JSON Schema object

Response 404 Not Found: DTO name not found

Use Case: Client-side validation, form generation, API contract verification

Application Management

Applications (List)

Endpoint: GET /api/Applications

Description: Retrieves all published applications available for registration.

Request Example:

curl -X GET "https://<base-url>/api/Applications" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "shortName": "salesforce",
    "name": "Salesforce",
    "tag": "CRM",
    "description": "Customer relationship management platform",
    "logoImage": "base64-encoded-image",
    "credentialFields": [
      {
        "ShortName": "username",
        "DisplayName": "Username",
        "Type": "text",
        "Required": true
      },
      {
        "ShortName": "password",
        "DisplayName": "Password",
        "Type": "password",
        "Required": true
      }
    ],
    "credentialsJson": {
      "username": null,
      "password": null
    }
  }
]

Use Case: Discover available applications before registering them

Applications (Search)

Endpoint: POST /api/Applications

Description: Search applications with pagination and filtering.

Request Body:

{
  "page": 0,
  "size": 50,
  "searchTerm": "salesforce",
  "includeLogo": true
}

Request Example:

curl -X POST "https://<base-url>/api/Applications" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 0,
    "size": 50,
    "searchTerm": "salesforce",
    "includeLogo": false
  }'

Response 200 OK:

{
  "applications": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "shortName": "salesforce",
      "name": "Salesforce",
      "tag": "CRM",
      "description": "Customer relationship management platform",
      "logo": null
    }
  ],
  "total": 1
}

Parameters:

page: Page number (zero-based)
size: Number of results per page
searchTerm: Search across name and description (optional)
includeLogo: Include base64-encoded logo (optional, default: false)

Response 400 Bad Request: Invalid request parameters

Workflow Templates

WorkflowTemplates (List)

Endpoint: GET /api/WorkflowTemplates?filterByHostedTemplates={bool}

Description: Retrieves all available workflow templates including published versions and drafts.

Parameters:

filterByHostedTemplates (optional): Filter by partner-hosted templates

Request Example:

curl -X GET "https://<base-url>/api/WorkflowTemplates" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Array of workflow template summary objects

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "name": "Sync Salesforce to Slack",
    "description": "Automatically post Salesforce updates to Slack",
    "version": "1.2.0",
    "state": "Published",
    "applications": ["salesforce", "slack"],
    "variables": [
      {
        "shortName": "slackChannel",
        "displayName": "Slack Channel",
        "type": "string",
        "required": true
      }
    ]
  },
  {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "name": "Custom Integration",
    "description": "Draft template",
    "version": null,
    "state": "Draft"
  }
]

Notes:

Published templates have version numbers
Draft templates have state: "Draft" and version: null
Templates include variable definitions for customization

WorkflowTemplate (Get Details)

Endpoint: GET /api/WorkflowTemplate/{id}?isDraft={bool}

Description: Retrieves detailed information about a specific workflow template including complete block chain configuration.

Parameters:

id (path, required): Template GUID
isDraft (query, optional): Fetch draft version instead of published (default: false)

Request Example:

curl -X GET "https://<base-url>/api/WorkflowTemplate/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Complete workflow template details with block chain, variables, and configuration

Response 404 Not Found: Template not found or access denied

Block Templates

BlockTemplates (List)

Endpoint: GET /api/BlockTemplates?filterByHostedTemplates={bool}

Description: Retrieves all available block templates (function blocks) for custom workflow construction.

Parameters:

filterByHostedTemplates (optional): Filter by partner-hosted templates

Request Example:

curl -X GET "https://<base-url>/api/BlockTemplates" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Array of block template summary objects

Use Case: Build custom workflows by composing individual block templates

BlockTemplate (Get Details)

Endpoint: GET /api/BlockTemplate/{id}?isDraft={bool}

Description: Retrieves detailed information about a specific block template.

Parameters:

id (path, required): Block template GUID
isDraft (query, optional): Fetch draft version (default: false)

Request Example:

curl -X GET "https://<base-url>/api/BlockTemplate/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Complete block template details with script, variables, and configuration

Response 404 Not Found: Block template not found or access denied

Account Management

Accounts (List)

Endpoint: GET /api/Accounts

Description: Retrieves all accounts accessible by the current user.

Authorization: Requires Manager role or higher

Request Example:

curl -X GET "https://<base-url>/api/Accounts" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK:

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "email": "user@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "role": "User",
    "accountState": "Active",
    "organizationName": "Acme Corp",
    "tags": ["tag1", "tag2"]
  }
]

Response 403 Forbidden: User does not have Manager role

Accounts (Search)

Endpoint: POST /api/Accounts

Description: Search accounts with advanced filtering and pagination.

Authorization: Requires Manager role or higher

Request Body:

{
  "page": 0,
  "size": 50,
  "searchTerm": "john",
  "accountState": ["Active", "Inactive", "Locked"],
  "tags": ["tag1", "tag2"]
}

Request Example:

curl -X POST "https://<base-url>/api/Accounts" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 0,
    "size": 50,
    "searchTerm": "john",
    "accountState": ["Active"]
  }'

Response 200 OK:

{
  "accounts": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "john.doe@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "role": "User",
      "accountState": "Active",
      "tags": ["customer"]
    }
  ],
  "total": 1
}

Parameters:

page: Page number (zero-based)
size: Number of results per page
searchTerm: Search by name or email (optional)
accountState: Filter by account states (optional)
tags: Filter by tags (optional)

Response 400 Bad Request: Invalid parameters

Response 403 Forbidden: Insufficient permissions

Account (Create)

Endpoint: POST /api/Account

Description: Creates a new account in your organization.

Authorization: Requires DevPartner, SuperPartner, or Manager role

Request Body:

{
  "email": "newuser@example.com",
  "firstName": "Jane",
  "lastName": "Smith",
  "roleName": "User",
  "countryKey": "US",
  "activated": false
}

Request Example:

curl -X POST "https://<base-url>/api/Account" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "roleName": "User",
    "countryKey": "US",
    "activated": false
  }'

Response 200 OK: Returns new account GUID

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Parameters:

email: User email address (required, must be unique)
firstName: User first name (required)
lastName: User last name (required)
roleName: User role - "User", "DevPartner", or "SuperPartner" (required)
countryKey: ISO country code (optional, inherits from your account if not provided)
activated: Create as activated account (optional, default: false, requires special permission)

Account Activation:

activated: false: User receives activation email
activated: true: Account ready immediately, API keys auto-generated (requires permission)

Response 400 Bad Request:

Email already exists
Invalid role specified
Insufficient permissions to create activated accounts
User role cannot create accounts

Response 403 Forbidden: Insufficient permissions

Registered Applications

RegApplications (List)

Endpoint: GET /api/RegApplications

Description: Retrieves all authenticated registered applications for the current account.

Response: Array of RegApplicationListApiDto objects

RegApplications (Search)

Endpoint: POST /api/RegApplications

Description: Search registered applications with advanced filtering.

Request Body:

{
  "page": 0,
  "size": 50,
  "searchTerm": "string",
  "tags": ["tag1"],
  "isFaulted": false,
  "appIds": ["guid1", "guid2"]
}

Response Schema:

{
  "regApplications": [],
  "total": 100
}

RegApplication (Create)

Endpoint: POST /api/RegApplication

Description: Registers a new application instance for the current account.

Request Body:

{
  "applicationId": "guid",
  "tagText": "My App Instance",
  "credentialsJson": "{\"apiKey\":\"xxx\",\"secret\":\"yyy\"}"
}

Response:

OAuth apps: Returns OAuth authorization URL
Basic/API Key apps: Returns registered application GUID

RegApplication (Update)

Endpoint: POST /api/RegApplication/{id}

Description: Updates an existing registered application.

Parameters:

id (path): Registered application GUID

Request Body:

{
  "tagText": "Updated Name",
  "credentialsJson": "{\"apiKey\":\"new-key\"}"
}

Response: OAuth URL (if OAuth app) or empty string

DeleteRegApplication

Endpoint: GET /api/DeleteRegApplication/{id}

Description: Deletes a registered application.

Parameters:

id (path): Registered application GUID

Response: Boolean success indicator

Validation:

Checks account ownership
Prevents deletion if application is used in active workflows
Returns detailed error with workflow IDs if deletion blocked

Workflow Management

Workflows (List)

Endpoint: GET /api/Workflows

Description: Retrieves all workflows (InDevelopment and Deployed).

Response: Array of WorkflowListApiDto objects

Workflows (Search)

Endpoint: POST /api/Workflows

Description: Advanced workflow search with multiple filter criteria.

Request Body:

{
  "page": 0,
  "size": 50,
  "searchTerm": "string",
  "appIds": ["guid"],
  "regAppIds": ["guid"],
  "blockTemplateIds": ["guid"],
  "workflowTemplateId": "guid",
  "workflowState": ["InDevelopment", "Deployed"],
  "tags": ["tag1"],
  "isScheduled": true,
  "isAutoRunPaused": false,
  "isWebhookActive": true
}

Response Schema:

{
  "workflows": [],
  "total": 100
}

Filter Capabilities:

Application usage
Registered application usage
Block template usage
Based on workflow template
Workflow state
Scheduler status
Autorun status
Webhook status
Tags
Full-text search

Workflow (Get Details)

Endpoint: GET /api/Workflow/{id}?runNumber={int}

Description: Retrieves complete workflow configuration and state.

Parameters:

id (path): Workflow GUID
runNumber (query, optional): Specific run number to load historical state

Response: WorkflowApiDto containing:

Workflow metadata
Complete block configuration
Variable values
Application mappings
Execution history (if runNumber specified)

Workflow (Create from Template)

Endpoint: POST /api/Workflow

Description: Creates a new workflow instance from a template.

Request Body:

{
  "workflowTemplateId": "guid",
  "name": "My Workflow",
  "description": "Workflow description",
  "applications": {
    "salesforce": "regAppGuid1",
    "slack": "regAppGuid2"
  },
  "variables": {
    "apiKey": {"value": "xxx"},
    "domain": "example.com"
  },
  "unboundFromTemplate": false,
  "chain": [
    {
      "uniqueBlockId": "guid",
      "blockName": "Custom Name",
      "script": "// custom script",
      "dataSources": ["blockGuid1"],
      "variables": {
        "varName": {
          "variableSource": "Value",
          "value": "xxx"
        }
      }
    }
  ]
}

Response: Workflow GUID

Variable Value Formats (both supported):

{"variableName": {"value": "actualValue"}}
{"variableName": "actualValue"}

UnboundFromTemplate:

When true: Disconnects workflow from template
Allows structural changes to blocks
Sets isCustomizedStructure = true
Marks all blocks as customized

Chain Customization:

Modify block scripts
Change data sources (inputs)
Override block variables
Link to workflow variables

Workflow (Update)

Endpoint: POST /api/Workflow/{id}

Description: Updates an existing workflow configuration.

Parameters:

id (path): Workflow GUID

Request Body: Same structure as Create, but all fields optional:

{
  "name": "Updated Name",
  "description": "Updated description",
  "applications": {
    "salesforce": "newRegAppGuid"
  },
  "variables": {
    "apiKey": "newValue"
  },
  "chain": [
    {
      "uniqueBlockId": "guid",
      "variables": {
        "varName": {
          "variableSource": "Workflow",
          "variableName": "workflowVar"
        }
      }
    }
  ],
  "unboundFromTemplate": false
}

Response: 200 OK

Restrictions:

Cannot change block structure (dataSources) on template-based workflows unless unboundFromTemplate=true
Cannot add undeclared variables
Cannot modify blocks that don't exist

DeployWorkflow

Endpoint: GET /api/DeployWorkflow/{id}

Description: Deploys a workflow from InDevelopment to Deployed state.

Parameters:

id (path): Workflow GUID

Response: Workflow GUID

ArchiveWorkflow

Endpoint: GET /api/ArchiveWorkflow/{id}

Description: Archives a workflow (soft delete).

Parameters:

id (path): Workflow GUID

Response: Boolean success

DeleteWorkflow

Endpoint: GET /api/DeleteWorkflow/{id}

Description: Permanently deletes a workflow.

Parameters:

id (path): Workflow GUID

Response: Boolean success

Warning: This is a hard delete operation. Consider using ArchiveWorkflow instead.

Workflow Execution

RunWorkflow

Endpoint: POST /api/RunWorkflow

Description: Executes a workflow immediately.

Request Body:

{
  "workflowId": "guid",
  "webhookId": "guid",
  "runFromBlock": "block#",
  "runTillBlock": "block#"
}

Response: "Workflow will now run" or error message

Parameters:

workflowId: Required. Workflow to execute
webhookId: Optional. Rerun a specific webhook request
runFromBlock: Optional. Start execution from specific block number (partial run)
runTillBlock: Optional. Stop execution at specific block number (partial run)

Validation Errors:

Workflow not found
Workflow not deployed
Missing required registered applications
Invalid block IDs

Scheduler Management

WorkflowScheduler

Endpoint: POST /api/WorkflowScheduler

Description: Configures or updates workflow scheduler settings.

Request Body:

{
  "workflowId": "guid",
  "isScheduled": true,
  "scheduleFrequency": "0 9 * * *"
}

Response: "Workflow Scheduler enabled" or "disabled"

Schedule Frequency Formats:

Cron expression: "0 9 * * *" (9 AM daily)
Named frequency: "hourly", "daily", "weekly", "monthly"

Cron Expression Examples:

"0 9 * * *"     → Daily at 9:00 AM
"0 */2 * * *"   → Every 2 hours
"0 0 * * 0"     → Weekly on Sunday
"0 0 1 * *"     → Monthly on 1st

Webhook Management

WebhookSettings (Get)

Endpoint: GET /api/WebhookSettings/{id}

Description: Retrieves webhook configuration for a workflow.

Parameters:

id (path): Workflow GUID

Response:

{
  "isActive": true,
  "ipRestriction": ["192.168.1.0/24"],
  "urlParameters": "key=value",
  "strictOrderProcessing": true,
  "skipProcessingAfterErrors": 3,
  "skipScript": "// validation script",
  "isBatch": true,
  "batchSize": 10,
  "updateDateLastRun": true,
  "modifyAccountId": "guid",
  "modifyDateTimeUTC": "2024-01-01T00:00:00Z"
}

Returns: 204 No Content if webhook not configured

WebhookSettingsEnable

Endpoint: POST /api/WebhookSettingsEnable/{id}

Description: Enables and configures webhook for a workflow.

Parameters:

id (path): Workflow GUID

Request Body:

{
  "secret": "optional-custom-secret",
  "ipRestriction": ["192.168.1.0/24"],
  "urlParameters": "key=value",
  "strictOrderProcessing": true,
  "skipProcessingAfterErrors": 3,
  "skipScript": "// custom validation",
  "isBatch": true,
  "batchSize": 10,
  "updateDateLastRun": true
}

Response (First Time):

{
  "url": "https://webhook.example.com/{workflowId}?key=value",
  "secret": "generated-secret-or-custom",
  "message": "Webhook settings are enabled. Please save the secret value as it will not be shown again"
}

Response (Updates):

{
  "url": "https://webhook.example.com/{workflowId}?key=value"
}

Configuration Options:

secret: HMAC secret for webhook validation (generated if not provided)
ipRestriction: Array of allowed IP addresses/CIDR ranges
urlParameters: Query string parameters appended to webhook URL
strictOrderProcessing: FIFO queue processing (prevents parallel execution)
skipProcessingAfterErrors: Number of consecutive errors before skipping request
skipScript: JavaScript code to validate/filter webhook requests
isBatch: Enable batch processing of multiple webhook requests
batchSize: Number of requests to batch together
updateDateLastRun: Update workflow's last run timestamp on webhook execution

WebhookSettingsDisable

Endpoint: POST /api/WebhookSettingsDisable/{id}?disableWithCleanSettings={bool}

Description: Disables webhook for a workflow.

Parameters:

id (path): Workflow GUID
disableWithCleanSettings (query): If true, deletes all webhook settings

Response: "Webhook settings are disabled" or "disabled and cleaned up"

GetWebhookQueue

Endpoint: POST /api/GetWebhookQueue/{workflowId}

Description: Retrieves pending webhook requests in queue.

Parameters:

workflowId (path): Workflow GUID

Request Body:

{
  "page": 0,
  "size": 50,
  "searchFrom": "2024-01-01T00:00:00Z",
  "searchTo": "2024-12-31T23:59:59Z"
}

Response:

{
  "items": [
    {
      "webhookId": "guid",
      "status": "Pending",
      "createDateTimeUTC": "2024-01-01T10:00:00Z",
      "errorCounter": 0,
      "nextScheduleDateTimeUTC": "2024-01-01T10:05:00Z",
      "no": 1
    }
  ],
  "length": 100,
  "isLast": false,
  "workflowSettings": {
    "isAutoRunPaused": false,
    "isWebhookActive": true
  }
}

Queue Statuses:

Pending: Waiting to be processed
Processing: Currently executing
Failed: Execution failed (will retry)
Skipped: Skipped due to error threshold

GetWebhookHistory

Endpoint: POST /api/GetWebhookHistory/{workflowId}

Description: Retrieves processed webhook execution history.

Parameters: Same as GetWebhookQueue

Response: Similar structure with additional fields:

deleteFromQueueDateTimeUTC: When removed from queue
Historical status information

GetWebhook

Endpoint: GET /api/GetWebhook/{webhookId}

Description: Retrieves specific webhook request details.

Parameters:

webhookId (path): Webhook request GUID

Response:

{
  "id": "guid",
  "webhookValue": {"payload": "data"},
  "createDateTimeUTC": "2024-01-01T10:00:00Z",
  "modifyDateTimeUTC": "2024-01-01T10:05:00Z",
  "workflowId": "guid"
}

Returns: 204 No Content if not found

GetSandboxWebhookValue

Endpoint: GET /api/GetSandboxWebhookValue/{id}

Description: Retrieves sandbox webhook test data.

Parameters:

id (path): Workflow GUID

Response: Webhook payload object or 204 No Content

Use Case: Testing webhook configuration before production

Vault Operations

The Vault provides secure, encrypted storage for sensitive data at workflow and account levels.

MyVaultSet (Workflow-Level)

Endpoint: POST /api/MyVaultSet/{workflowId}/{key}

Description: Stores a value in workflow-specific vault.

Parameters:

workflowId (path): Workflow GUID
key (path): Vault key name

Request Body:

{
  "jsonData": "sensitive-data"
}

Response: Success indicator

Scope: Data accessible only within the specific workflow

MyVaultGet (Workflow-Level)

Endpoint: GET /api/MyVaultGet/{workflowId}/{key}

Description: Retrieves a value from workflow vault.

Parameters:

workflowId (path): Workflow GUID
key (path): Vault key name

Response: Stored value

MyVaultSetGlobal (Account-Level)

Endpoint: POST /api/MyVaultSetGlobal/{accountId}/{key}

Description: Stores a value in account-level vault.

Parameters:

accountId (path): Account GUID
key (path): Vault key name

Request Body:

{
  "jsonData": "sensitive-data"
}

Scope: Data accessible across all workflows for the account

MyVaultGetGlobal (Account-Level)

Endpoint: GET /api/MyVaultGetGlobal/{accountId}/{key}

Description: Retrieves a value from account vault.

MyVaultRemove (Workflow-Level)

Endpoint: GET /api/MyVaultRemove/{workflowId}/{key}

Description: Deletes a key from workflow vault.

MyVaultRemoveGlobal (Account-Level)

Endpoint: GET /api/MyVaultRemoveGlobal/{accountId}/{key}

Description: Deletes a key from account vault.

MyVaultContains (Workflow-Level)

Endpoint: GET /api/MyVaultContains/{workflowId}/{key}

Description: Checks if a key exists in workflow vault.

Response: Boolean

MyVaultContainsGlobal (Account-Level)

Endpoint: GET /api/MyVaultContainsGlobal/{accountId}/{key}

Description: Checks if a key exists in account vault.

Response: Boolean

JavaScript Functions

GetFunctions

Endpoint: GET /api/GetFunctions

Description: Retrieves available JavaScript functions for use in workflows.

Response:

[
  {
    "id": "guid",
    "name": "functionName",
    "description": "Function description",
    "category": "String Manipulation",
    "package": "lodash",
    "isAsync": true,
    "arguments": {
      "param1": {"type": "string"},
      "param2": {"type": "number"}
    },
    "script": "// function implementation"
  }
]

Use Case: Dynamic function library for custom block development

Remote API Calls

These endpoints proxy API calls to registered applications.

ApiAuth

Endpoint: GET /api/ApiAuth

Description: Authenticates with a registered application's API.

Headers: Requires registered application credentials

Response: Authentication token/response from target API

ApiAppVault

Endpoint: GET /api/ApiAppVault

Description: Retrieves application-specific vault data.

Response: Vault contents for the specified application

ApiGet

Endpoint: GET /api/ApiGet?url={appShortName}/{endpoint}&srv={baseUrl}

Description: Proxies a GET request to a registered application's API.

Parameters:

url: Format: {appShortName}/{apiEndpoint}
srv: Optional base URL override

Example: /api/ApiGet?url=salesforce/accounts&srv=https://custom.salesforce.com

Response: API response from target application

ApiPost

Endpoint: POST /api/ApiPost?url={appShortName}/{endpoint}&srv={baseUrl}

Description: Proxies a POST request to a registered application's API.

Request Body:

{
  "jsonData": {"field": "value"}
}

ApiSend

Endpoint: POST /api/ApiSend/{shortName}?newVersion={bool}

Description: Sends a custom API request to a registered application.

Parameters:

shortName (path): Application short name
newVersion (query): Use new response format (default: false)

Request Body:

{
  "verb": "POST",
  "requestUrl": "endpoint/path",
  "baseUrl": "https://api.example.com",
  "data": {"field": "value"},
  "headers": {"Custom-Header": "value"},
  "responseType": "Json",
  "responseCodes": [200, 201]
}

Response Types:

Json: Parses response as JSON
Text: Returns as plain text
Binary: Returns as base64

ApiProxyEmail

Endpoint: POST /api/ApiProxyEmail

Description: Sends an email through Canvas email service. Supports HTML/plain text emails with optional attachments.

Request Body:

{
  "subject": "Email Subject",
  "to": ["recipient1@example.com", "recipient2@example.com"],
  "cc": ["cc@example.com"],
  "bcc": ["bcc@example.com"],
  "body": "Email body content",
  "bodyIsHtml": true,
  "attachmentName": "document.pdf",
  "attachment": "base64-encoded-content",
  "attachmentEncoding": "base64",
  "attachmentContentType": "application/pdf",
  "toAccountEmail": false
}

Request Parameters:

subject (required): Email subject line
to (required): Array of recipient email addresses
cc (optional): Array of carbon copy email addresses
bcc (optional): Array of blind carbon copy email addresses
body (required): Email body content
bodyIsHtml (optional): Whether the body contains HTML (default: false)
attachmentName (optional): Name of the attachment file
attachment (optional): Base64-encoded attachment content
attachmentEncoding (optional): Encoding type for attachment (e.g., "base64")
attachmentContentType (optional): MIME type of attachment (e.g., "application/pdf")
toAccountEmail (optional): Send to the authenticated account's email address

Request Example:

curl -X POST "https://<base-url>/api/ApiProxyEmail" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Monthly Report",
    "to": ["manager@example.com"],
    "body": "<h1>Report</h1><p>Please find the monthly report attached.</p>",
    "bodyIsHtml": true,
    "attachmentName": "report.pdf",
    "attachment": "JVBERi0xLjQKJeLjz9MK...",
    "attachmentEncoding": "base64",
    "attachmentContentType": "application/pdf"
  }'

Response 200 OK:

{
  "Success": true
}

Response 400 Bad Request:

{
  "Error": "Error message description"
}

Use Case: Send automated notifications, reports, or alerts via email from workflows

Notes:

All recipient fields (to, cc, bcc) accept arrays of email addresses
Attachments must be base64-encoded
Use toAccountEmail: true to send to the authenticated user's email address
HTML emails should set bodyIsHtml: true

ProxySecureShare

Endpoint: POST /api/ProxySecureUpload

Description: Uploads files to Canvas secure share service and sends email notification with download link. Files are encrypted and protected with optional access code.

Content-Type: multipart/form-data

Request Parameters (Form Data):

files (required): One or more files to upload
notificationEmail (required): Email address to receive the secure share link
email (optional): Sender name/email display (default: "ConnectMyApps")
copy (optional): CC email address for notification
subject (optional): Email subject line (default: "ConnectMyApps - New Secure Share")
secureNote (optional): Note to include with the secure share
code (optional): Custom access code for file access
bodyIsHtml (optional): Send HTML formatted email (default: true)

Request Example (curl):

curl -X POST "https://<base-url>/api/ProxySecureUpload" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -F "files=@/path/to/document.pdf" \
  -F "files=@/path/to/image.jpg" \
  -F "notificationEmail=recipient@example.com" \
  -F "email=sender@example.com" \
  -F "subject=Secure Document Share" \
  -F "secureNote=Please find the requested documents attached" \
  -F "code=MySecret123"

Request Example (JavaScript):

const formData = new FormData();
formData.append('Files', new Blob(['some_text_data']), 'securefile.txt');
formData.append('notificationEmail', 'recipient@example.com');
formData.append('email', 'sender@example.com');
formData.append('subject', 'Secure File Transfer');
formData.append('secureNote', 'Confidential documents');
formData.append('code', 'AccessCode123');

fetch('https://<base-url>/api/ProxySecureUpload', {
  method: 'POST',
  headers: {
    'SecretKey': 'your-secret-key',
    'Consumer': 'your-public-key',
    "Content-Type": "multipart/form-data"
  },
  body: formData
});

Response 200 OK:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Returns the secure share ID (GUID) of the uploaded files.

Response 400 Bad Request: Upload failed or invalid parameters

Secure Share Features:

Files are encrypted during storage
Access protected with optional custom code
Email notification sent automatically with download link
Download link format: {baseUrl}/secure-share/secure-download?shareid={id}&code={code}
Recipients receive email with access instructions

Use Case:

Send sensitive documents securely
Share large files with external parties
Distribute confidential reports from workflows
Automated document delivery with access control

Notes:

Multiple files can be uploaded in a single request
Files are stored securely and encrypted
The endpoint automatically sends an email notification with the download link
Custom access codes provide additional security
The secure share ID is returned for tracking purposes
No file size limit is enforced on this endpoint (DisableRequestSizeLimit)

Results & Logs

GetRunHistory

Endpoint: POST /api/GetRunHistory/{workflowId}

Description: Search workflow run history with pagination and filtering. Returns detailed execution records including status, duration, and error information.

Parameters:

workflowId (path, required): Workflow GUID

Request Body:

{
  "page": 0,
  "size": 50,
  "lockVersionNumber": 42,
  "status": "Ready",
  "searchFrom": "2024-01-01T00:00:00Z",
  "searchTo": "2024-12-31T23:59:59Z",
  "orderByAsc": false,
  "orderField": "startDateTimeUTC"
}

Request Parameters:

page (required): Page number (zero-based)
size (required): Number of results per page
lockVersionNumber (optional): Filter by specific run number
status (optional): Filter by workflow status. Valid values:
- Ready - Completed successfully
- Error - Failed with error
searchFrom (optional): Filter runs starting from this date (ISO 8601 format)
searchTo (optional): Filter runs ending before this date (ISO 8601 format)
orderByAsc (optional): Sort order - true for ascending, false for descending (default: false)
orderField (optional): Field to sort by (default: lockVersionNumber). Not case-sensitive. Valid values:
- lockVersionNumber - Run number
- status - Execution status
- startDateTimeUTC - Run start time
- endDateTimeUTC - Run end time
- durationInMilliSec - Execution duration
- pauseInMilliSec - Time spent in pause/wait states
- processorType - Execution environment
- Any other value falls back to lockVersionNumber

Request Example:

curl -X POST "https://<base-url>/api/GetRunHistory/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 0,
    "size": 50,
    "status": "Ready",
    "searchFrom": "2026-09-01T00:00:00Z",
    "orderByAsc": false
  }'

Response 200 OK:

{
  "items": [
    {
      "lockVersionNumber": 42,
      "status": "Ready",
      "startDateTimeUTC": "2026-09-05T10:30:00Z",
      "endDateTimeUTC": "2026-09-05T10:32:15Z",
      "durationInMilliSec": 135000,
      "pauseInMilliSec": 0,
      "runBy": "API",
      "processorType": "Standard-4GB",
      "isExpiredByTime": false,
      "errorMessage": null,
      "lastExecutedBlockId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "lastExecutedBlockTitle": "Send Email"
    }
  ],
  "total": {
    "totalNumber": 127,
    "totalDurationMilliSec": 17145000,
    "avgDurationMilliSec": 135000,
    "totalPauseMilliSec": 0,
    "avgPauseMilliSec": 0
  }
}

Response Fields:

items: Page of matching workflow runs
- lockVersionNumber: Unique run number (increments with each execution)
- status: Execution status (Ready, Error, Stopped, etc.)
- startDateTimeUTC: When the workflow run started
- endDateTimeUTC: When the workflow run completed (null if still running)
- durationInMilliSec: Total execution time in milliseconds
- pauseInMilliSec: Time spent in pause/wait states
- runBy: Trigger source (API, Scheduler, Webhook, Manual, etc.)
- processorType: Execution environment (Standart or Dedicated processors, Debug, etc.)
- isExpiredByTime: Whether execution results exceeded timeout limit
- errorMessage: Error description if status is Error
- lastExecutedBlockId: GUID of the last executed block
- lastExecutedBlockTitle: Name of the last executed block
total: Aggregated statistics for all runs matching the filters (not only the current page); null when nothing matches
- totalNumber: Total number of matching runs
- totalDurationMilliSec: Sum of run durations in milliseconds
- avgDurationMilliSec: Average run duration in milliseconds
- totalPauseMilliSec: Sum of pause times in milliseconds
- avgPauseMilliSec: Average pause time in milliseconds

Response 400 Bad Request: Invalid workflow ID or request parameters

Response 404 Not Found: Workflow not found or access denied

SearchRunNewTask

Endpoint: POST /api/SearchRunNewTask/{workflowId}

Description: Starts an advanced (content) search over the run history of a workflow. The search looks for text inside run data (block responses, user logs, errors, webhook payloads, session data) and is executed asynchronously in batches. The endpoint returns the ID of the created search task immediately; use it with SearchRunViewTask to retrieve the matching runs.

Parameters:

workflowId (path, required): Workflow GUID

Request Body:

{
  "searchCriteria": {
    "uniqueBlockIds": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
    "searchInResponse": true,
    "searchInUserLog": true,
    "searchInError": false,
    "searchInWebhook": false,
    "searchInSession": false,
    "searchTerm": [
      {
        "searchBy": "order-12345",
        "isCaseSensitive": false
      }
    ]
  },
  "batchSize": 100,
  "searchFrom": "2026-09-01T00:00:00Z",
  "searchTo": "2026-09-30T23:59:59Z",
  "orderByAsc": false,
  "orderField": "lockVersionNumber"
}

Request Parameters:

searchCriteria (required): What to search for and where
- searchTerm (required): Array of search terms. At least one item with a non-empty searchBy is required
  - searchBy (required): Text to search for
  - isCaseSensitive (optional): Whether the match is case-sensitive (default: false)
- searchInResponse (optional): Search in block responses (default: false)
- searchInUserLog (optional): Search in user log messages (default: false)
- searchInError (optional): Search in error messages (default: false)
- searchInWebhook (optional): Search in webhook data (default: false)
- searchInSession (optional): Search in session data (default: false)
- uniqueBlockIds (optional): Restrict the search to the specified blocks (GUIDs). If omitted or empty, all blocks are searched
- At least one of the searchIn* flags must be true
batchSize (required): Number of runs processed per batch. Must be greater than 0
searchFrom (optional): Search runs starting from this date (ISO 8601 format). Default: one month before the request time
searchTo (optional): Search runs up to this date (ISO 8601 format). Default: request time (UTC)
orderByAsc (optional): Sort order - true for ascending, false for descending (default: false)
orderField (optional): Field to sort by (default: lockVersionNumber). Not case-sensitive. Valid values:
- lockVersionNumber - Run number
- status - Execution status
- startDateTimeUTC - Run start time
- endDateTimeUTC - Run end time
- durationInMilliSec - Execution duration
- pauseInMilliSec - Time spent in pause/wait states
- processorType - Execution environment
- Any other value falls back to lockVersionNumber

Request Example:

curl -X POST "https://<base-url>/api/SearchRunNewTask/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "searchCriteria": {
      "searchInResponse": true,
      "searchInUserLog": true,
      "searchTerm": [
        { "searchBy": "order-12345", "isCaseSensitive": false }
      ]
    },
    "batchSize": 100,
    "searchFrom": "2026-09-01T00:00:00Z",
    "searchTo": "2026-09-30T23:59:59Z"
  }'

Response 200 OK:

"b2f6c1a4-8d3e-4f0a-9c57-1e2d3a4b5c6d"

Response: A JSON string containing the GUID of the created search task (searchRunTaskId). Pass it in searchRunTaskIds of SearchRunViewTask.

Response 400 Bad Request: Invalid request (e.g. the workflow does not belong to the account, batchSize is 0, searchCriteria is missing, no searchIn* flag is set, no non-empty searchTerm, or workflow not found)

Notes:

The workflow must belong to the authenticated (or managed) account
The search is asynchronous. The returned ID only identifies the task; matching runs become available through SearchRunViewTask as the batches are processed
lockVersionNumber and status filters are not applied when creating a task. Apply them in SearchRunViewTask
If no runs fall into the specified date range, the task is completed immediately with no results

SearchRunViewTask

Endpoint: POST /api/SearchRunViewTask/{workflowId}

Description: Returns workflow run history with pagination and filtering. When searchRunTaskIds is provided, returns only the runs found by the specified advanced search tasks created with SearchRunNewTask. When searchRunTaskIds is empty or omitted, behaves like GetRunHistory and returns runs without content search. Response also includes aggregated statistics for all matching runs.

Parameters:

workflowId (path, required): Workflow GUID

Request Body:

{
  "searchRunTaskIds": ["b2f6c1a4-8d3e-4f0a-9c57-1e2d3a4b5c6d"],
  "page": 0,
  "size": 50,
  "lockVersionNumber": 42,
  "status": "Ready",
  "searchFrom": "2026-09-01T00:00:00Z",
  "searchTo": "2026-09-30T23:59:59Z",
  "orderByAsc": false,
  "orderField": "startDateTimeUTC"
}

Request Parameters:

page (required): Page number (zero-based)
size (required): Number of results per page
searchRunTaskIds (optional): Array of search task GUIDs returned by SearchRunNewTask. If omitted or empty, no content search is applied
lockVersionNumber (optional): Filter by specific run number
status (optional): Filter by workflow status. Valid values:
- Ready - Completed successfully
- Error - Failed with error
searchFrom (optional): Filter runs starting from this date (ISO 8601 format). Default: one month before the request time
searchTo (optional): Filter runs ending before this date (ISO 8601 format). Default: request time (UTC)
orderByAsc (optional): Sort order - true for ascending, false for descending (default: false)
orderField (optional): Field to sort by (default: lockVersionNumber). Not case-sensitive. Valid values:
- lockVersionNumber - Run number
- status - Execution status
- startDateTimeUTC - Run start time
- endDateTimeUTC - Run end time
- durationInMilliSec - Execution duration
- pauseInMilliSec - Time spent in pause/wait states
- processorType - Execution environment
- Any other value falls back to lockVersionNumber

Request Example:

curl -X POST "https://<base-url>/api/SearchRunViewTask/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "searchRunTaskIds": ["b2f6c1a4-8d3e-4f0a-9c57-1e2d3a4b5c6d"],
    "page": 0,
    "size": 50,
    "orderByAsc": false
  }'

Response 200 OK:

{
  "items": [
    {
      "lockVersionNumber": 42,
      "status": "Ready",
      "startDateTimeUTC": "2026-09-05T10:30:00Z",
      "endDateTimeUTC": "2026-09-05T10:32:15Z",
      "durationInMilliSec": 135000,
      "pauseInMilliSec": 0,
      "runBy": "API",
      "processorType": "Standard-4GB",
      "isExpiredByTime": false,
      "errorMessage": null,
      "lastExecutedBlockId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "lastExecutedBlockTitle": "Send Email"
    }
  ],
  "total": {
    "totalNumber": 127,
    "totalDurationMilliSec": 17145000,
    "avgDurationMilliSec": 135000,
    "totalPauseMilliSec": 0,
    "avgPauseMilliSec": 0
  }
}

Response Fields:

items: Page of matching workflow runs
- lockVersionNumber: Unique run number (increments with each execution)
- status: Execution status (Ready, Error, Stopped, etc.)
- startDateTimeUTC: When the workflow run started
- endDateTimeUTC: When the workflow run completed (null if still running)
- durationInMilliSec: Total execution time in milliseconds
- pauseInMilliSec: Time spent in pause/wait states
- runBy: Trigger source (API, Scheduler, Webhook, Manual, etc.)
- processorType: Execution environment (Standart or Dedicated processors, Debug, etc.)
- isExpiredByTime: Whether execution results exceeded timeout limit
- errorMessage: Error description if status is Error
- lastExecutedBlockId: GUID of the last executed block
- lastExecutedBlockTitle: Name of the last executed block
total: Aggregated statistics for all runs matching the filters (not only the current page); null when nothing matches
- totalNumber: Total number of matching runs
- totalDurationMilliSec: Sum of run durations in milliseconds
- avgDurationMilliSec: Average run duration in milliseconds
- totalPauseMilliSec: Sum of pause times in milliseconds
- avgPauseMilliSec: Average pause time in milliseconds

Response 400 Bad Request: Invalid workflow ID or request parameters

Response 404 Not Found: Workflow not found or access denied

Notes:

The workflow must belong to the authenticated (or managed) account

Use Case: Create a search task with SearchRunNewTask, then call SearchRunViewTask with the returned task ID to page through the runs that contain the searched text.

SearchRunTasks

Endpoint: POST /api/SearchRunTasks/{workflowId}

Description: Returns the advanced search tasks created for a workflow with SearchRunNewTask, newest first. Each task includes its state, progress and the number of matches grouped by search place and block.

Parameters:

workflowId (path, required): Workflow GUID

Request Body:

{
  "page": 0,
  "size": 20,
  "lockVersionNumber": 42
}

Request Parameters:

page (optional): Page number (zero-based)
size (optional): Number of tasks per page. Pagination is applied only when page is 0 or greater and size is greater than 0; otherwise all tasks of the workflow are returned
lockVersionNumber (optional): Return only tasks that found matches in this run, and count only the matches in this run

Request Example:

curl -X POST "https://<base-url>/api/SearchRunTasks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 0,
    "size": 20
  }'

Response 200 OK:

[
  {
    "id": "b2f6c1a4-8d3e-4f0a-9c57-1e2d3a4b5c6d",
    "prettyId": 3,
    "searchCriteria": "[{\"searchBy\":\"order-12345\",\"isCaseSensitive\":false}]",
    "criteriaDateFrom": "2026-09-01T00:00:00+00:00",
    "criteriaDateTo": "2026-09-30T23:59:59+00:00",
    "startDateTime": "2026-10-01T09:15:00+00:00",
    "endDateTime": "2026-10-01T09:15:42+00:00",
    "state": 1,
    "uniqueBlockIds": null,
    "searchInResponse": true,
    "searchInUserLog": true,
    "searchInError": false,
    "searchInWebhook": false,
    "searchInSession": false,
    "progressNo": 12,
    "progressTotal": 40,
    "searchRunTaskResults": [
      {
        "searchPlace": 0,
        "uniqueBlockId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "webhookId": null,
        "count": 9
      }
    ]
  }
]

Response Fields: A JSON array of search tasks sorted by startDateTime descending. Each item has the same fields as the response of GetSearchRunTask (state and searchPlace are returned as numbers).

Response 400 Bad Request: Invalid workflow ID, workflow not found, or the workflow does not belong to the account

Notes:

The workflow must belong to the authenticated (or managed) account
The response is a plain array and does not contain the total number of tasks
With lockVersionNumber, tasks without matches in that run are removed after the page is selected, so a page can contain fewer than size items
Returns an empty array if the workflow has no search tasks

GetSearchRunTask

Endpoint: GET /api/GetSearchRunTask/{taskId}

Description: Returns the details and current progress of an advanced search task created with SearchRunNewTask, including the number of matches grouped by search place and block.

Parameters:

taskId (path, required): Search task GUID returned by SearchRunNewTask

Request Example:

curl -X GET "https://<base-url>/api/GetSearchRunTask/b2f6c1a4-8d3e-4f0a-9c57-1e2d3a4b5c6d" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK:

{
  "id": "b2f6c1a4-8d3e-4f0a-9c57-1e2d3a4b5c6d",
  "prettyId": 3,
  "searchCriteria": "[{\"searchBy\":\"order-12345\",\"isCaseSensitive\":false}]",
  "criteriaDateFrom": "2026-09-01T00:00:00+00:00",
  "criteriaDateTo": "2026-09-30T23:59:59+00:00",
  "startDateTime": "2026-10-01T09:15:00+00:00",
  "endDateTime": "2026-10-01T09:15:42+00:00",
  "state": 1,
  "uniqueBlockIds": null,
  "searchInResponse": true,
  "searchInUserLog": true,
  "searchInError": false,
  "searchInWebhook": false,
  "searchInSession": false,
  "progressNo": 12,
  "progressTotal": 40,
  "searchRunTaskResults": [
    {
      "searchPlace": 0,
      "uniqueBlockId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "webhookId": null,
      "count": 9
    },
    {
      "searchPlace": 1,
      "uniqueBlockId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "webhookId": null,
      "count": 3
    }
  ]
}

Response Fields:

id: Search task GUID
prettyId: Sequential task number within the workflow
searchCriteria: Search terms, as a JSON-encoded string (array of { searchBy, isCaseSensitive })
criteriaDateFrom / criteriaDateTo: Date range the task searched in
startDateTime: When the task was created
endDateTime: When the task finished (null while it is running)
state: Task state (numeric value):
- 0 - In progress
- 1 - Completed
- 2 - Cancellation in progress
- 3 - Canceled
- 4 - Error
uniqueBlockIds: Blocks the search was restricted to (null if all blocks were searched)
searchInResponse, searchInUserLog, searchInError, searchInWebhook, searchInSession: Places the search was performed in
progressNo, progressTotal: Progress counters. Their meaning depends on state:
- While in progress: progressNo is the number of processed batches, progressTotal is the total number of batches
- Otherwise: progressNo is the number of matches found, progressTotal is the number of checked results
searchRunTaskResults: Matches grouped by place and block
- searchPlace: Where the match was found (numeric value): 0 - block response, 1 - user log, 2 - error, 3 - webhook, 4 - session
- uniqueBlockId: GUID of the block that contains the match (if applicable)
- webhookId: GUID of the webhook that contains the match (if applicable)
- count: Number of runs with a match in this place

Response 400 Bad Request: Invalid task ID, task not found, or the task's workflow does not belong to the account

Notes:

The task must belong to a workflow of the authenticated (or managed) account
Poll this endpoint after SearchRunNewTask until state is no longer 0, then call SearchRunViewTask to retrieve the runs
Enum values (state, searchPlace) are returned as numbers

CancelSearchRunTask

Endpoint: GET /api/CancelSearchRunTask/{taskId}

Description: Cancels a search task created with SearchRunNewTask. The task state is set to Canceled.

Parameters:

taskId (path, required): Search task GUID

Request Example:

curl -X GET "https://<base-url>/api/CancelSearchRunTask/b2f6c1a4-8d3e-4f0a-9c57-1e2d3a4b5c6d" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Empty body. The task was marked as canceled

Response 400 Bad Request: Invalid task ID, task not found, or the task's workflow does not belong to the account

Notes:

The task must belong to a workflow of the authenticated (or managed) account
Check the result with GetSearchRunTask (state = 3)
The task and any matches already found are kept. Use DeleteSearchRunTask to remove them

DeleteSearchRunTask

Endpoint: GET /api/DeleteSearchRunTask/{taskId}

Description: Deletes a search task together with its batches and results.

Parameters:

taskId (path, required): Search task GUID

Request Example:

curl -X GET "https://<base-url>/api/DeleteSearchRunTask/b2f6c1a4-8d3e-4f0a-9c57-1e2d3a4b5c6d" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Empty body. The task was deleted

Response 400 Bad Request: Invalid task ID, task not found, or the task's workflow does not belong to the account

Notes:

The task must belong to a workflow of the authenticated (or managed) account
This operation cannot be undone
A deleted task ID can no longer be used in searchRunTaskIds of SearchRunViewTask
Although it deletes data, the endpoint uses the GET method

ClearAllSearchRunTasks

Endpoint: GET /api/ClearAllSearchRunTasks/{workflowId}

Description: Deletes all search tasks (with their batches and results) created for a workflow.

Parameters:

workflowId (path, required): Workflow GUID

Request Example:

curl -X GET "https://<base-url>/api/ClearAllSearchRunTasks/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key"

Response 200 OK: Empty body. All search tasks of the workflow were deleted

Response 400 Bad Request: Invalid workflow ID, workflow not found, or the workflow does not belong to the account

Notes:

The workflow must belong to the authenticated (or managed) account
This operation cannot be undone
Returns 200 even if the workflow has no search tasks
Although it deletes data, the endpoint uses the GET method

GetBlockResult

Endpoint: GET /api/GetBlockResult/{workflowId}?uniqueBlockId={guid}&runNumber={int}

Description: Retrieves execution result for a specific block.

Parameters:

workflowId (path): Workflow GUID
uniqueBlockId (query): Block GUID
runNumber (query, optional): Specific run number (default: latest)

Response:

{
  "success": true,
  "runNumber": 42,
  "uniqueBlockId": "guid",
  "result": {"output": "data"}
}

Error Response:

{
  "success": false,
  "runNumber": 42,
  "uniqueBlockId": "guid",
  "result": "Error message"
}

GetBlockUserLog

Endpoint: GET /api/GetBlockUserLog/{workflowId}?uniqueBlockId={guid}&runNumber={int}

Description: Retrieves user-generated logs from a block execution.

Response:

{
  "runNumber": 42,
  "uniqueBlockId": "guid",
  "result": ["log message 1", "log message 2"]
}

Use Case: Debugging custom scripts with console.log() statements

GetBlockSession

Endpoint: GET /api/GetBlockSession/{workflowId}?uniqueBlockId={guid}&runNumber={int}

Description: Retrieves session data (state) for a block execution.

Response:

{
  "runNumber": 42,
  "uniqueBlockId": "guid",
  "result": {"sessionKey": "sessionValue"}
}

Use Case: Accessing intermediate state/variables during block execution

Tag Management

Tags are labels that can be attached to various entities (accounts, workflows, registered applications, etc.) for organization, filtering, and categorization purposes.

AttributeTagAdd

Endpoint: POST /api/AttributeTagAdd/{entityType}/{entityId}

Description: Adds a tag to an entity (account, workflow, registered application, etc.).

Parameters:

entityType (path, required): Type of entity to tag. Valid values:
- account (0)
- registeredApp (1)
- workflow (2)
- application (3)
- blockTemplate (4)
- workflowTemplate (5)
- organization (6)
- role (7)
entityId (path, required): GUID of the entity to tag

Request Body:

{
  "value": "production"
}

Request Example:

curl -X POST "https://<base-url>/api/AttributeTagAdd/workflow/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "production"
  }'

Response 200 OK: Empty response on success

Response 400 Bad Request: Invalid entity type or missing tag value

AttributeTagDelete

Endpoint: POST /api/AttributeTagDelete/{entityType}/{entityId}

Description: Removes a specific tag from an entity.

Parameters:

entityType (path, required): Type of entity (same values as AttributeTagAdd)
entityId (path, required): GUID of the entity

Request Body:

{
  "value": "production"
}

Request Example:

curl -X POST "https://<base-url>/api/AttributeTagDelete/workflow/3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "SecretKey: your-secret-key" \
  -H "Consumer: your-public-key" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "production"
  }'

Response 200 OK: Empty response on success

Response 400 Bad Request:

Missing or empty tag value
Invalid entity type
Entity not found

Notes:

The tag value must exactly match the existing tag (case-sensitive)
No error is returned if the tag doesn't exist on the entity

Tag Filtering:

Tags can be used to filter results in search endpoints:

POST /api/Accounts - Filter by tags parameter
POST /api/RegApplications - Filter by tags parameter
POST /api/Workflows - Filter by tags parameter

Error Handling

Standard Error Responses

All endpoints follow consistent error response patterns:

400 Bad Request

{
  "code": 400,
  "errorMessage": "Specific error description",
  "response": null
}

Best Practices

1. Workflow Creation Flow

GET /api/Applications → List available apps
POST /api/RegApplication → Register needed apps
GET /api/WorkflowTemplates → Find template
GET /api/WorkflowTemplate/{id} → Get template details
POST /api/Workflow → Create workflow from template
POST /api/Workflow/{id} → Configure workflow
GET /api/DeployWorkflow/{id} → Deploy workflow
POST /api/RunWorkflow → Execute workflow

2. Pagination Pattern

Always use pagination for list endpoints:

{
  "page": 0,
  "size": 50,
  "searchTerm": "optional"
}

3. Workflow Variable Formats

Both formats are supported:

// Explicit format (recommended)
{"variableName": {"value": "actualValue"}}

// Shorthand format
{"variableName": "actualValue"}

4. Error Recovery

Check response status codes
Parse error messages for details
Use validation endpoints before creation
Handle OAuth redirects appropriately

5. Webhook Security

Always use secret for HMAC validation
Implement ipRestriction for known sources
Use skipScript for payload validation
Enable strictOrderProcessing for order-sensitive workflows

6. Vault Usage

Use workflow vault for workflow-specific secrets
Use account vault for shared credentials
Always check if key exists before retrieving
Clean up unused keys

7. Performance Optimization

Use search endpoints with filters instead of listing all
Set includeLogo: false when logos not needed
Paginate large result sets
Cache template and application lists

Common Scenarios

Scenario 1: Automated Workflow Provisioning

POST /api/Account → Create user account
Authenticate as new account
POST /api/RegApplication → Register required apps
POST /api/Workflow → Create workflow from template
POST /api/WorkflowScheduler → Schedule execution
GET /api/DeployWorkflow/{id} → Deploy

Scenario 2: Webhook-Triggered Workflow

POST /api/Workflow → Create workflow
POST /api/WebhookSettingsEnable/{id} → Enable webhook
External system POSTs to webhook URL
POST /api/GetWebhookQueue/{id} → Monitor queue
GET /api/GetBlockResult → Check execution results

Scenario 3: Custom Block Execution

GET /api/GetFunctions → Get available functions
POST /api/Workflow → Create with custom blocks
POST /api/RunWorkflow → Execute
GET /api/GetBlockResult → Retrieve block output
GET /api/GetBlockUserLog → Check console logs

Scenario 4: Multi-Account Management (Partner)

POST /api/Account (activated: false) → Create account
User activates via email
Switch context to managed account
POST /api/RegApplication → Register apps for user
POST /api/Workflow → Provision workflow
Configure scheduler/webhooks

Appendix

DTO Naming Convention

ApiDto suffix: API-specific DTOs
ListApiDto: Summary objects for list endpoints
WithDetailsApiDto: Full detail objects

Key DTOs

ApplicationListApiDto: Application summary
WorkflowTemplateListApiDto: Template summary
WorkflowTemplateWithDetailsApiDto: Full template
WorkflowListApiDto: Workflow summary
WorkflowApiDto: Full workflow configuration
RegApplicationListApiDto: Registered app summary
ClientListApiDto: Account summary
BlockTemplateApiDto: Block template data
ChainApiDto: Block chain element
WebhookSettingApiDto: Webhook configuration

Enums

AccountStateEnum:

inActive
active
locked
archived

WorkflowStateEnum:

inDevelopment
deployed
archived

WorkflowRunStatusEnum:

pending
processing
completed
failed
skipped

EntityTypeEnum:

account
registeredApp
workflow
application
blockTemplate
workflowTemplate
organization
role

Last Updated: 2026-10-30

Overview​

Table of Contents​

Getting Started​

Generate API Keys​

Authentication Headers​

Quick Start Example​

Authentication​

Authenticate​

API Metadata​

GetMetaData​

Describe​

GetSchema​

Application Management​

Applications (List)​

Applications (Search)​

Workflow Templates​

WorkflowTemplates (List)​

WorkflowTemplate (Get Details)​

Block Templates​

BlockTemplates (List)​

BlockTemplate (Get Details)​

Account Management​

Accounts (List)​

Accounts (Search)​

Account (Create)​

Registered Applications​

RegApplications (List)​

RegApplications (Search)​

RegApplication (Create)​

RegApplication (Update)​

DeleteRegApplication​

Workflow Management​

Workflows (List)​

Workflows (Search)​

Workflow (Get Details)​

Workflow (Create from Template)​

Workflow (Update)​

DeployWorkflow​

ArchiveWorkflow​

DeleteWorkflow​

Workflow Execution​

RunWorkflow​

Scheduler Management​

WorkflowScheduler​

Webhook Management​

WebhookSettings (Get)​

WebhookSettingsEnable​

WebhookSettingsDisable​

GetWebhookQueue​

GetWebhookHistory​

GetWebhook​

GetSandboxWebhookValue​

Vault Operations​

MyVaultSet (Workflow-Level)​

MyVaultGet (Workflow-Level)​

MyVaultSetGlobal (Account-Level)​

MyVaultGetGlobal (Account-Level)​

MyVaultRemove (Workflow-Level)​

MyVaultRemoveGlobal (Account-Level)​

MyVaultContains (Workflow-Level)​

MyVaultContainsGlobal (Account-Level)​

JavaScript Functions​

GetFunctions​

Remote API Calls​

ApiAuth​

ApiAppVault​

ApiGet​

ApiPost​

ApiSend​

ApiProxyEmail​

ProxySecureShare​

Results & Logs​

GetRunHistory​

SearchRunNewTask​

SearchRunViewTask​

SearchRunTasks​

GetSearchRunTask​

CancelSearchRunTask​

DeleteSearchRunTask​

ClearAllSearchRunTasks​

Overview

Table of Contents

Getting Started

Generate API Keys

Authentication Headers

Quick Start Example

Authentication

Authenticate

API Metadata

GetMetaData

Describe

GetSchema

Application Management

Applications (List)

Applications (Search)

Workflow Templates

WorkflowTemplates (List)

WorkflowTemplate (Get Details)

Block Templates

BlockTemplates (List)

BlockTemplate (Get Details)

Account Management

Accounts (List)

Accounts (Search)

Account (Create)

Registered Applications

RegApplications (List)

RegApplications (Search)

RegApplication (Create)

RegApplication (Update)

DeleteRegApplication

Workflow Management

Workflows (List)

Workflows (Search)

Workflow (Get Details)

Workflow (Create from Template)

Workflow (Update)

DeployWorkflow

ArchiveWorkflow

DeleteWorkflow

Workflow Execution

RunWorkflow

Scheduler Management

WorkflowScheduler

Webhook Management

WebhookSettings (Get)

WebhookSettingsEnable

WebhookSettingsDisable

GetWebhookQueue

GetWebhookHistory

GetWebhook

GetSandboxWebhookValue

Vault Operations

MyVaultSet (Workflow-Level)

MyVaultGet (Workflow-Level)

MyVaultSetGlobal (Account-Level)

MyVaultGetGlobal (Account-Level)

MyVaultRemove (Workflow-Level)

MyVaultRemoveGlobal (Account-Level)

MyVaultContains (Workflow-Level)

MyVaultContainsGlobal (Account-Level)

JavaScript Functions

GetFunctions

Remote API Calls

ApiAuth

ApiAppVault

ApiGet

ApiPost

ApiSend

ApiProxyEmail

ProxySecureShare

Results & Logs

GetRunHistory

SearchRunNewTask

SearchRunViewTask

SearchRunTasks

GetSearchRunTask

CancelSearchRunTask

DeleteSearchRunTask

ClearAllSearchRunTasks