Introduction - SuperAI Flows

SuperAI Flows is a workflow orchestration platform for building durable, AI-powered automations through a simple API.

What you can build

Process documents at scale

Extract data from invoices, contracts, and forms with AI-powered workflows.

Chain API operations

Connect multiple services, handle retries, and manage complex business logic.

Automate business processes

Build durable workflows that handle failures gracefully and resume automatically.

Why developers choose SuperAI Flows

Built for reliability

Automatic retries — Configure retry policies per task with exponential backoff
Durable execution — Workflows survive service restarts and infrastructure failures
Version control — Roll back to previous workflow versions without breaking running executions
Real-time monitoring — Track execution progress with WebSocket notifications and comprehensive logging

Enterprise-ready

Multi-tenant architecture — Organization-scoped resources with role-based access control
Audit logging — Complete execution history for compliance and debugging
Scalable infrastructure — Distributed architecture designed for high-throughput workloads
Secure by default — JWT authentication, API key management, and webhook signature verification

Core concepts

Flows

A Flow is a workflow definition — a declarative YAML file that specifies tasks, dependencies, and execution logic. Flows are versioned, allowing you to iterate safely. Why developers love our YAML definitions:

Readable and maintainable — Define complex workflows in plain YAML without writing orchestration code
Type-safe — Every task includes a complete JSON schema for inputs and outputs, ensuring data integrity
Visual representation — YAML maps directly to the visual flow editor at flows.super.ai
Reusable components — Leverage pre-built task executors or create custom ones in Python

Reference task outputs using simple syntax like {{task_name.output.field}}, and the platform handles dependencies, retries, and data flow automatically. See the quickstart for a complete YAML workflow example.

Flow executions

A Flow Execution is a single run of a flow with specific input data. Each execution has a unique ID and tracks status through its lifecycle: queued → running → completed or failed.

Tasks

Tasks are the building blocks of flows. Each task performs a single operation (API call, data transformation, AI inference) and can depend on outputs from previous tasks.

Task executors

Task Executors are pre-built or custom Python functions that define how tasks run. SuperAI provides executors for common operations like HTTP requests, LLM calls, and data processing.

Integration patterns

Synchronous (polling)

Create an execution, poll for completion, retrieve results:

# 1. Create execution
EXEC_ID=$(curl -X POST https://flows.super.ai/api/flow-executions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"flow_id":"$FLOW_ID","input":{}}' | jq -r .id)

# 2. Check status
curl https://flows.super.ai/api/flow-executions/$EXEC_ID \
  -H "Authorization: Bearer $TOKEN" | jq .status

# 3. Get results
curl "https://flows.super.ai/api/task-executions?flow_execution_id=$EXEC_ID" \
  -H "Authorization: Bearer $TOKEN"

Best for: Testing, prototyping, low-volume workloads.

Asynchronous (webhooks)

Add a Webhook Notification task to receive real-time updates when referenced tasks produce output:

{
  "event_type": "flow_execution.completed",
  "flow_execution_id": "df77dc65-909b-430e-bff1-9e9ecf315a80",
  "status": "completed",
  "timestamp": "2025-01-15T10:32:45Z",
  "data": {
    "task_outputs": {
      "extract_invoice_data": {
        "invoice_number": "INV-0052465571",
        "total_amount": 2435.00
      }
    }
  }
}

Key benefits:

Automatic dependency resolution — Webhooks trigger after referenced tasks produce output
Customizable payload — Reference outputs from any previous task using {{task_name.output.field}}
Multiple webhooks per flow — Send different data to different endpoints at different stages

Best for: Production workloads, high-volume processing, event-driven architectures. Configure webhook tasks in the Flow Editor at flows.super.ai.

API design philosophy

Predictable and consistent

RESTful endpoints with intuitive resource naming
Consistent response formats across all endpoints
Standard HTTP status codes for error handling
Comprehensive field descriptions in all responses

Built for forward compatibility

Your integrations won’t break. We follow strict versioning rules. Non-breaking changes (safe, no action required):

Adding new API endpoints
Adding optional query parameters
Adding new fields to responses
Adding new enum values

Breaking changes (requires migration):

Removing endpoints or fields
Changing field types or validation
Removing enum values

All breaking changes are announced at least 15 days in advance with migration guides.

Client requirements

Your API clients must gracefully handle additional fields in responses. We may add new fields to any response object without advance notice — design your parsers to ignore unknown fields.

Ready to build?

API Quickstart

Authenticate and run your first workflow in under 5 minutes.

API Reference

Explore every endpoint, with request and response schemas.

Questions? Email support@super.ai — we’re here to help.

​What you can build

Process documents at scale

Chain API operations

Automate business processes

​Why developers choose SuperAI Flows

​Built for reliability

​Enterprise-ready

​Core concepts

​Flows

​Flow executions

​Tasks

​Task executors

​Integration patterns

​Synchronous (polling)

​Asynchronous (webhooks)

​API design philosophy

​Predictable and consistent

​Built for forward compatibility

​Client requirements

​Ready to build?

API Quickstart

API Reference

What you can build

Why developers choose SuperAI Flows

Built for reliability

Enterprise-ready

Core concepts

Flows

Flow executions

Tasks

Task executors

Integration patterns

Synchronous (polling)

Asynchronous (webhooks)

API design philosophy

Predictable and consistent

Built for forward compatibility

Client requirements

Ready to build?