## 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](https://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](https://docs.flows.super.ai/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](https://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.