List all available task executors

curl --request GET \
  --url https://flows.super.ai/api/task-executors \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://flows.super.ai/api/task-executors"

headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', Authorization: 'Bearer <token>'}
};

fetch('https://flows.super.ai/api/task-executors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://flows.super.ai/api/task-executors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://flows.super.ai/api/task-executors"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://flows.super.ai/api/task-executors")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://flows.super.ai/api/task-executors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "is_input_task_executor": false,
    "is_schedulable_executor": false,
    "parameters_schema": {
      "properties": {
        "model": {
          "default": "gpt-4-vision",
          "description": "AI model to use for extraction",
          "enum": [
            "gpt-4-vision",
            "claude-3-opus"
          ],
          "type": "string"
        },
        "schema": {
          "description": "Field definitions to extract from documents",
          "type": "object"
        }
      },
      "required": [
        "schema"
      ],
      "type": "object"
    },
    "task_executor_agent_prompt": "Use this executor to extract specific fields from documents. Define a schema with field names, types, and descriptions. The executor will use AI to locate and extract those fields from uploaded documents.",
    "task_executor_description": "Extracts structured data from documents using vision-language models and OCR",
    "task_executor_name": "doc_to_structured"
  }
]

task-executors

List all available task executors

List all available task executors for workflow composition.

Overview Task executors are reusable building blocks for workflows. Each executor performs a specific operation (send email, extract data, classify documents, etc.). This endpoint provides discovery of all registered executors with their schemas, enabling programmatic flow builder UIs and validation.

What are Task Executors? Task executors are typed workflow components that:

Accept configuration parameters (e.g., API keys, endpoints, templates)
Optionally receive runtime input data (for input executors)
Perform an operation (API call, data transformation, ML inference)
Return structured output for downstream tasks
Support scheduling (for compatible executors)

Executor Categories

Input Executors (is_input_task_executor=true):
- Trigger flows from external sources
- Examples: receive_email, webhook_receive, receive_file
- Have flow_input_schema defining incoming data
Processing Executors (is_input_task_executor=false):
- Transform data within flows
- Examples: doc_to_structured, classify_text, format_data
- No flow_input_schema (work on task outputs)
Output Executors:
- Send data to external systems
- Examples: send_email, webhook_notification, external_db
- Can be terminal tasks in flows
Schedulable Executors (is_schedulable_executor=true):
- Support time-based triggers
- Examples: scheduled_db_query
- Can run on cron schedules

Response Format Returns array of TaskExecutorResponse objects containing:

Executor metadata (name, description, agent prompt)
Configuration schema (parameters_schema) - JSON Schema for static config
Runtime input schema (flow_input_schema) - JSON Schema for dynamic data
Capability flags (is_input_task_executor, is_schedulable_executor)

Schema Usage

parameters_schema: Generate configuration UI, validate flow definitions
flow_input_schema: Validate incoming webhook/email/file data
Both schemas follow JSON Schema Draft 2020-12 specification

Use Cases

Flow Builder UI: Display available task types with autocomplete
AI Agents: Use agent_prompt to intelligently select executors
Validation: Check flow definitions against executor schemas
Documentation: Generate API reference from executor metadata
Client SDKs: Generate type-safe executor configuration classes

Executor Registration Task executors are registered via TaskExecutorsManager (flow-sdk). To add custom executors, see flow-sdk/src/flow_sdk/task_executors/README.md

Performance Notes

Response cached for 5 minutes (executors rarely change)
Typical response size: ~50-100 executors, 200-500KB
Schemas can be large (1-10KB per executor)
Consider client-side caching for production use

Related Endpoints

POST /flows - Create flow using discovered executors
GET /flows/ - View flow definition with executor references
POST /task-data - Get task output schemas for flow validation

GET

api

task-executors

List all available task executors

curl --request GET \
  --url https://flows.super.ai/api/task-executors \
  --header 'Authorization: Bearer <token>' \
  --header 'X-API-Key: <api-key>'

import requests

url = "https://flows.super.ai/api/task-executors"

headers = {
    "X-API-Key": "<api-key>",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', Authorization: 'Bearer <token>'}
};

fetch('https://flows.super.ai/api/task-executors', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://flows.super.ai/api/task-executors",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://flows.super.ai/api/task-executors"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://flows.super.ai/api/task-executors")
  .header("X-API-Key", "<api-key>")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://flows.super.ai/api/task-executors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

[
  {
    "is_input_task_executor": false,
    "is_schedulable_executor": false,
    "parameters_schema": {
      "properties": {
        "model": {
          "default": "gpt-4-vision",
          "description": "AI model to use for extraction",
          "enum": [
            "gpt-4-vision",
            "claude-3-opus"
          ],
          "type": "string"
        },
        "schema": {
          "description": "Field definitions to extract from documents",
          "type": "object"
        }
      },
      "required": [
        "schema"
      ],
      "type": "object"
    },
    "task_executor_agent_prompt": "Use this executor to extract specific fields from documents. Define a schema with field names, types, and descriptions. The executor will use AI to locate and extract those fields from uploaded documents.",
    "task_executor_description": "Extracts structured data from documents using vision-language models and OCR",
    "task_executor_name": "doc_to_structured"
  }
]

Authorizations

X-API-Key

string

header

required

API key authentication. Include your API key in the X-API-Key header as: X-API-Key YOUR_API_KEY

Example:

X-API-Key: saf_1234567890

Authorization

string

header

required

JWT Bearer token authentication. Include your access token in the Authorization header as: Bearer YOUR_ACCESS_TOKEN

Example:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Response

List of task executors successfully retrieved

is_input_task_executor

boolean

required

Whether this executor can trigger flow execution from external sources.

Input executors (true):

Receive data from external systems (webhooks, emails, files, schedules)
Can be first task in a flow
Have flow_input_schema defining received data structure
Examples: receive_email, receive_file, webhook_receive

Non-input executors (false):

Process data within flow execution
Cannot trigger flows (must be downstream of input executor)
No flow_input_schema
Examples: send_email, doc_to_structured, classify_text, external_db

Used by flow validators to ensure flows have at least one input executor.

Examples:

true

false

is_schedulable_executor

boolean

required

Whether this executor supports scheduled/recurring execution.

Schedulable executors (true):

Can run on cron schedules (hourly, daily, weekly, custom)
Support time-based triggers
Often paired with input executors
Examples: scheduled_db_query

Non-schedulable executors (false):

Event-driven only (triggered by upstream tasks or external events)
Cannot run on schedule
Examples: send_email, classify_document, receive_email (event-driven)

Note: Scheduling is configured at the flow execution level, not per task. This flag indicates executor compatibility with scheduling.

Examples:

true

false

parameters_schema

Parameters Schema · object

required

JSON Schema defining configuration parameters for this task executor. Describes required and optional parameters, their types, and validation rules. Clients use this schema to generate configuration UIs and validate inputs.

Schema Format: JSON Schema Draft 2020-12 specification

Common properties: type, required, properties, additionalProperties, description, examples, enum, default, minimum, maximum, pattern

Used for: UI form generation, parameter validation, API documentation

Note: This is the CONFIGURATION schema (static parameters), not the runtime input schema (see flow_input_schema).

Example:

{
  "properties": {
    "body": {
      "description": "Email body content (supports templates)",
      "type": "string"
    },
    "recipient": {
      "description": "Email recipient address",
      "format": "email",
      "type": "string"
    },
    "subject": {
      "description": "Email subject line",
      "maxLength": 200,
      "type": "string"
    }
  },
  "required": ["recipient", "subject"],
  "type": "object"
}

task_executor_agent_prompt

string

required

Prompt template used by AI agents when configuring this task executor. Provides context to LLM agents about executor capabilities and parameters. Guides automated flow generation and task configuration.

Format: Natural language instructions for AI agents describing when and how to use this executor.

Used by: Flow Builder AI Assistant, Auto-configuration agents

Examples:

"Use this executor to send email notifications. Configure recipient, subject, and body. Supports templates and attachments."

"Use this executor to extract structured fields from documents. Specify field names and types in the schema parameter."

task_executor_description

string

required

Human-readable description of what this task executor does. Explains the executor's purpose, behavior, and typical use cases. Displayed in UI flow builders and documentation.

Should be 1-3 sentences focusing on capabilities and outcomes. Written in present tense, active voice.

Minimum string length: 10

Examples:

"Sends email notifications via SMTP or email service provider"

"Extracts structured data from documents using vision-language models"

"Receives incoming emails and triggers workflow execution"

task_executor_name

string

required

Unique identifier for this task executor type. Used in flow definition YAML to reference this executor. Case-sensitive and immutable.

Naming convention: snake_case with descriptive action verbs.

Examples: 'send_email', 'doc_to_structured', 'classify_document', 'receive_file', 'webhook_notification', 'external_db'

Minimum string length: 1

Examples:

"send_email"

"doc_to_structured"

"receive_email"

"notify_webhook"

flow_input_schema

Flow Input Schema · object | null

JSON Schema defining runtime input data for input task executors. Only present for executors that can trigger/receive flow executions (is_input_task_executor=true).

Defines the shape of data received from external sources: webhooks, email attachments, file uploads, scheduled triggers, etc.

Difference from parameters_schema:

parameters_schema: Static configuration set during flow design
flow_input_schema: Dynamic data received at runtime

Example: An 'receive_email' executor has:

parameters_schema: {email_address, filters, ...} (configuration)
flow_input_schema: {from, subject, body, attachments, ...} (runtime data)

Null for non-input executors (standard task executors).

Example:

{
  "properties": {
    "attachments": {
      "description": "File URLs for attachments",
      "items": { "type": "string" },
      "type": "array"
    },
    "body": {
      "description": "Email body content",
      "type": "string"
    },
    "from": {
      "description": "Sender email address",
      "format": "email",
      "type": "string"
    },
    "subject": {
      "description": "Email subject line",
      "type": "string"
    }
  },
  "type": "object"
}

Retrieve a specific task execution List all task outputs