Introduction - SuperAI Flows

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.