> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flows.super.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction
> Build reliable, scalable workflows that orchestrate AI models, data processing, and business logic — all through a simple API.
SuperAI Flows is a workflow orchestration platform for building durable, AI-powered automations through a simple API.
## What you can build
Extract data from invoices, contracts, and forms with AI-powered workflows.
Connect multiple services, handle retries, and manage complex business logic.
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](/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:
```bash theme={null}
# 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:
```json theme={null}
{
"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.
## Ready to build?
Authenticate and run your first workflow in under 5 minutes.
Explore every endpoint, with request and response schemas.
**Questions?** Email [support@super.ai](mailto:support@super.ai) — we're here to help.