Super.AI

Getting Started

Build reliable, scalable workflows that orchestrate AI models, data processing, and business logic—all through a simple API.

---

## What You Can Build

SuperAI Flows is a workflow orchestration platform that enables you to:

*   📄 **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 guide](../api-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
# 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. You can add a task usi

```json
{
  "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
*   **Customize 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 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?

Start with our [5-minute quickstart guide](../getting-started/api-quickstart) or dive into the [full API reference](https://developers.flows.super.ai).

**Questions?** Email [support@super.ai](mailto:support@super.ai) — we're here to help.

Sections

Ask an AI

Code with AI