API ReferenceApp
API Reference
App

Theme switcher

API Quickstart

Super.AI Flows API Quickstart

Start processing documents with Super.AI Flows in under 5 minutes. This guide shows you how to authenticate, run your first workflow, and retrieve results.

🚀 Quick Start

Want to process a document in 60 seconds? Run this single command to create a flow and process your first invoice:

# Replace with your credentials
EMAIL="your-email@example.com"
PASSWORD="your-password"

# Get anonymous key and authenticate
ANON_KEY=$(curl -s https://flows.super.ai/api/auth/anon-key | jq -r .anon_key)
TOKEN=$(curl -s -X POST "https://core.flows.super.ai/auth/v1/token?grant_type=password" \
  -H "Content-Type: application/json" \
  -H "apikey: $ANON_KEY" \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}" | jq -r .access_token)

# Create flow with full definition
FLOW_RESPONSE=$(curl -s -X POST https://flows.super.ai/api/flows \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "Quick Start: Invoice Processing",
  "description": "Extract and validate invoice data",
  "version": 1,
  "definition": {
    "flow": {
      "created_at": "",
      "author_uuid": ""
    },
    "flow_configs": [
      {
        "config": {
          "tasks": [
            {
              "visual_properties": {"position": {"x": 0, "y": 359}},
              "name": "8a0883ff-e0b9-4c27-8dfe-8af18c7d3ea4",
              "task_executor_name": "receive_file",
              "task_title": "Receive File",
              "parameters": {}
            },
            {
              "visual_properties": {"position": {"x": 530, "y": 232}},
              "name": "d61f3643-52d9-4ff3-bee7-7a3e26ca013f",
              "task_executor_name": "doc_to_text",
              "task_title": "Convert Document to Text",
              "parameters": {
                "worker": "gpt-4.1",
                "mime_type": "{{8a0883ff-e0b9-4c27-8dfe-8af18c7d3ea4.mime_type}}",
                "document_url": "{{8a0883ff-e0b9-4c27-8dfe-8af18c7d3ea4.document_url}}",
                "doc_representation": "whitespace"
              }
            },
            {
              "visual_properties": {"position": {"x": 1060, "y": 0}},
              "name": "ce65d796-fabe-4b05-be0e-e58182fdae98",
              "task_executor_name": "text_to_structured",
              "task_title": "Extract Invoice Data",
              "parameters": {
                "fields": [
                  {"id": "invoice_no", "title": "Invoice Number", "columns": [], "data_type": "string", "instructions": ""},
                  {"id": "total", "title": "total", "columns": [], "data_type": "float", "instructions": "identify the total amount"},
                  {"id": "account_owner", "title": "Account Owner", "columns": [], "data_type": "string", "instructions": "Identify the account owner"}
                ],
                "worker": "gpt-4.1",
                "mime_type": "{{d61f3643-52d9-4ff3-bee7-7a3e26ca013f.mime_type}}",
                "input_data": "{{d61f3643-52d9-4ff3-bee7-7a3e26ca013f.page_contents}}",
                "document_url": "{{d61f3643-52d9-4ff3-bee7-7a3e26ca013f.document_url}}",
                "general_prompt": "",
                "extract_bounding_boxes": true,
                "use_logprobs_confidence": true
              }
            },
            {
              "visual_properties": {"position": {"x": 1590, "y": 285}},
              "name": "2dad3105-b031-4681-9588-0709b487034c",
              "task_executor_name": "collection_validation",
              "task_title": "Validate Invoice Total",
              "parameters": {
                "validators": [{"name": "Not Empty Validation"}],
                "input_collection": "{{ce65d796-fabe-4b05-be0e-e58182fdae98.total}}"
              }
            },
            {
              "visual_properties": {"position": {"x": 2120, "y": 232}},
              "name": "f2e977e3-138a-41f5-a3c7-7cdbeb150c2a",
              "task_executor_name": "notify",
              "task_title": "Send Notification",
              "parameters": {
                "tag": "check_amount",
                "task_name": "text_to_structured_00nl",
                "notification_type": "sync_tag",
                "validation_result": "{{2dad3105-b031-4681-9588-0709b487034c.validation_passed}}"
              }
            }
          ]
        }
      }
    ]
  }
}')

FLOW_ID=$(echo "$FLOW_RESPONSE" | jq -r .id)
echo "✅ Flow created: $FLOW_ID"

# Execute the flow with a sample invoice
EXEC_RESPONSE=$(curl -s -X POST https://flows.super.ai/api/flow-executions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"flow_id\":\"$FLOW_ID\",\"input\":{\"filename\":\"invoice-example.pdf\",\"mime_type\":\"application/pdf\",\"document_url\":\"https://cdn.super.ai/invoice-example.pdf\"}}")

EXEC_ID=$(echo "$EXEC_RESPONSE" | jq -r .id)
echo "✅ Execution started: $EXEC_ID"
echo ""
echo "📊 View results: https://flows.super.ai/flows/$FLOW_ID?view=data"

What just happened?

  1. Authenticated with your Super.AI account
  2. Created a 5-task invoice processing flow:
    • Receive File: Entry point that accepts file uploads
    • Convert to Text: Extracts text from the document using OCR
    • Extract Invoice Data: Pulls structured data (invoice number, total, account owner)
    • Validate: Ensures the total amount field is not empty
    • Send Notification: Notifies when processing completes
  3. Started processing a sample invoice PDF
  4. Got back a flow ID and execution ID to track progress

It worked? Check the dashboard link to see your flow processing the document. Continue reading to understand each component in detail. Got an error? Jump to Troubleshooting.

What are Super.AI Flows?

Super.AI Flows automate multi-step document processing pipelines. A typical flow:

  1. Classifies documents (invoice, receipt, contract)
  2. Extracts structured data based on document type
  3. Validates extracted values
  4. Delivers results via webhook or API

Example: Document Classification & Extraction Flow

Flow Definition Example

Flows are defined in declarative YAML that's both human-readable and type-safe. Here's a complete document processing workflow:

tasks:
  - name: classify_document
    task_executor_name: document_classifier
    parameters:
      document_url: "{{input.document_url}}"
      document_types:
        - invoice
        - bank_statement
        - contract

  - name: extract_data
    task_executor_name: text_to_structured
    parameters:
      document_url: "{{classify_document.splits[0].document_url}}"
      fields:
        - id: invoice_number
          data_type: string
        - id: total_amount
          data_type: float
          instructions: "identify the total amount"

  - name: validate_results
    task_executor_name: collection_validation
    parameters:
      input_collection: "{{extract_data.total_amount}}"
      validators:
        - name: Not Empty Validation

Key features:

  • Task chaining: extract_data references output from classify_document using {{classify_document.splits[0].document_url}}
  • Type safety: Each field specifies data_type (string, float, etc.)
  • Built-in executors: Use pre-built task executors like document_classifier and text_to_structured
  • Validation: Chain validation tasks to ensure data quality

The platform automatically resolves dependencies, handles retries, and manages data flow between tasks.

Prerequisites

Before you begin, ensure you have:

  • ✅ A Super.AI account (sign up free)
  • ✅ Your login email and password
  • ✅ curl and jq installed (for testing examples)

Note: This guide will walk you through creating a flow via API, so you don't need an existing flow to get started.

Authentication

Super.AI uses JWT-based authentication. All API requests require a valid access token.

How Authentication Works

1. Get anon key          2. Login with credentials       3. Use access token
   (public)                  (get JWT tokens)                (in API calls)
      ↓                            ↓                              ↓
flows.super.ai/           core.flows.super.ai/          Authorization: Bearer
api/auth/anon-key         auth/v1/token                 YOUR_ACCESS_TOKEN

Step-by-Step Authentication

Step 1: Get the anonymous key (public, no auth required)

curl https://flows.super.ai/api/auth/anon-key

Response:

{
  "anon_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 2: Exchange your credentials for JWT tokens

curl -X POST 'https://core.flows.super.ai/auth/v1/token?grant_type=password' \
  -H 'Content-Type: application/json' \
  -H 'apikey: YOUR_ANON_KEY' \
  -d '{
    "email": "your-email@example.com",
    "password": "your-password"
  }'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600,
  "token_type": "bearer"
}

Step 3: Use the access token in all API requests

curl https://flows.super.ai/api/flows \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Token Management

Token Type Lifetime When to Use
Access Token 1 hour Include in every API request
Refresh Token 30 days Get new access tokens when expired

Security Best Practices:

  • Store tokens in environment variables or secret managers (never in code)
  • Implement token refresh logic before expiration
  • Use HTTPS for all requests
  • Tokens grant full account access—treat them like passwords

Refresh Tokens (Optional)

When your access token expires, use the refresh token to get a new one without re-authenticating:

curl -X POST 'https://core.flows.super.ai/auth/v1/token?grant_type=refresh_token' \
  -H 'Content-Type: application/json' \
  -H 'apikey: YOUR_ANON_KEY' \
  -d '{
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'

Run Your First Flow

Already completed the Quick Start? You've already created and executed a flow! This section provides additional details about flow executions and monitoring.

Create a Flow Execution

Start a flow by creating a flow execution with your input data. If you created a flow in the Quick Start, use that FLOW_ID. Otherwise, create a flow first using the Quick Start guide above.

# Use the flow you created in the Quick Start
curl -X POST https://flows.super.ai/api/flow-executions \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "flow_id": "YOUR_FLOW_ID",
    "input": {
      "filename": "invoice-example.pdf",
      "mime_type": "application/pdf",
      "document_url": "https://cdn.super.ai/invoice-example.pdf"
    }
  }'

Response:

{
  "id": "df77dc65-909b-430e-bff1-9e9ecf315a80",
  "flow_id": "550e8400-e29b-41d4-a716-446655440000",
  "flow_version": 1,
  "status": "running",
  "input": {
    "filename": "invoice-example.pdf",
    "mime_type": "application/pdf",
    "document_url": "https://cdn.super.ai/invoice-example.pdf"
  },
  "organization_id": "660e8400-e29b-41d4-a716-446655440001",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z",
  "modified_by": "user@example.com"
}

Key Fields:

  • id: The flow execution ID (use this to check status and retrieve results)
  • status: Current execution state (running, completed, failed)
  • flow_version: Version of the flow used (remains constant even if flow is updated)

About the Input Structure:

The input object structure depends on your flow's configuration:

  • Flows that accept file input: Provide filename, mime_type, and document_url
  • Other flows: May have different input schemas—check your flow's input_schema to see what's required

Input fields for file-based flows:

  • filename: Name of the document (e.g., "invoice-example.pdf")
  • mime_type: MIME type of the document (e.g., "application/pdf", "image/jpeg", "image/png")
  • document_url: A publicly accessible URL where Super.AI can download the document

Check Execution Status

Query the flow execution to see if it's complete:

curl "https://flows.super.ai/api/flow-executions/df77dc65-909b-430e-bff1-9e9ecf315a80" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "id": "df77dc65-909b-430e-bff1-9e9ecf315a80",
  "flow_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:32:45Z"
}

Retrieve Results

Get task execution results for your flow:

curl "https://flows.super.ai/api/task-executions?flow_execution_id=df77dc65-909b-430e-bff1-9e9ecf315a80" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "task_executions": [
    {
      "id": "e47f2923-1205-4bf2-bee2-2974ddb64aad",
      "task_name": "extract_invoice_data",
      "status": "completed",
      "output": {
        "invoice_number": "INV-0052465571",
        "total_amount": 2435.00,
        "currency": "USD",
        "vendor": "Acme Corp",
        "date": "2024-01-15"
      },
      "created_at": "2024-01-15T10:30:05Z",
      "updated_at": "2024-01-15T10:32:40Z"
    }
  ]
}

Common Query Parameters:

  • flow_execution_id: Filter by flow execution (required for most queries)
  • task_name: Filter by specific task name
  • task_execution_idx: Filter by execution attempt (0 = first attempt, 1 = first retry)

Webhooks (Recommended)

Instead of polling for results, configure webhooks to receive real-time notifications when flows complete. The Webhook Notification task sends POST requests to your specified URL.

Configuring Webhook Notifications

Add a Webhook Notification task to your flow with these parameters:

  • Url (required): Your webhook endpoint URL
  • Authorization Header Value (optional): Auth token or API key for securing your webhook
  • Payload (required): The data to send (can reference task outputs using {{task_name.field}} syntax)

Example Webhook Task Configuration

{
  "event_type": "flow_execution.completed",
  "flow_id": "550e8400-e29b-41d4-a716-446655440000",
  "flow_execution_id": "df77dc65-909b-430e-bff1-9e9ecf315a80",
  "status": "completed",
  "timestamp": "2024-01-15T10:32:45Z",
  "data": {
    "task_outputs": {
      "extract_invoice_data": {
        "invoice_number": "INV-0052465571",
        "total_amount": 2435.00
      }
    }
  }
}

Receiving Webhooks

Your webhook endpoint should:

  1. Validate the authorization header if you provided one:

    authorization = request.headers.get('x-webhook-token')
if authorization != f"{YOUR_EXPECTED_TOKEN}":
    return 401

  2. Process the payload:

    data = request.json()
invoice_number = data.get('invoice_number')
total_amount = data.get('total_amount')
# Process the results...

  3. Return a 2xx status code to acknowledge receipt:

    return {"status": "received", "processed": True}

Webhook Task Outputs

The Webhook Notification task captures both the request and response for tracing and debugging:

Output fields:

  • request: The complete request sent to your webhook (URL, headers, payload)
  • response: The response received from your webhook (status code, headers, body)
  • status_code: HTTP status code of the response

View in Data View: Navigate to the Data view in the flow execution to see the complete webhook request/response for tracing purposes.

Use outputs in subsequent tasks: You can reference webhook outputs in later tasks using template syntax:

{
  "name": "process_webhook_response",
  "task_executor_name": "some_task",
  "parameters": {
    "webhook_status": "{{notify_webhook.status_code}}",
    "response_data": "{{notify_webhook.response.body}}"
  }
}

This enables conditional flows based on webhook responses or logging webhook interactions.

Note: Webhook tasks are configured as part of your flow definition. They execute when reached in the flow, sending data to your specified URL with the x-webhook-token header if provided.

Complete Example

Here's a production-ready bash script that creates a flow and processes a document with full error handling:

#!/bin/bash
set -e  # Exit on error

# Configuration
EMAIL="your-email@example.com"
PASSWORD="your-password"
INPUT_DATA='{"filename":"invoice-example.pdf","mime_type":"application/pdf","document_url":"https://cdn.super.ai/invoice-example.pdf"}'

echo "🔐 Step 1: Getting anonymous key..."
ANON_KEY=$(curl -sf https://flows.super.ai/api/auth/anon-key | jq -r .anon_key)
if [ -z "$ANON_KEY" ] || [ "$ANON_KEY" = "null" ]; then
  echo "❌ Failed to get anonymous key"
  exit 1
fi
echo "✅ Got anonymous key"

echo "🔑 Step 2: Authenticating..."
AUTH_RESPONSE=$(curl -sf -X POST "https://core.flows.super.ai/auth/v1/token?grant_type=password" \
  -H "Content-Type: application/json" \
  -H "apikey: $ANON_KEY" \
  -d "{\"email\":\"$EMAIL\",\"password\":\"$PASSWORD\"}")

ACCESS_TOKEN=$(echo "$AUTH_RESPONSE" | jq -r .access_token)
if [ -z "$ACCESS_TOKEN" ] || [ "$ACCESS_TOKEN" = "null" ]; then
  echo "❌ Authentication failed"
  echo "Response: $AUTH_RESPONSE"
  exit 1
fi
echo "✅ Authenticated successfully"

echo "📋 Step 3: Creating flow with full definition..."
FLOW_RESPONSE=$(curl -sf -X POST https://flows.super.ai/api/flows \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "display_name": "API Quickstart Flow",
  "description": "Simple invoice processing with classification and extraction",
  "version": 1,
  "definition": {
    "flow": {"created_at": "", "author_uuid": ""},
    "flow_configs": [{
      "config": {
        "tasks": [
          {
            "visual_properties": {"position": {"x": 0, "y": 0}},
            "name": "classify_document",
            "task_executor_name": "document_classifier",
            "task_title": "Classify Document Type",
            "parameters": {
              "worker": "gpt-4.1",
              "mime_type": "{{input.mime_type}}",
              "document_url": "{{input.document_url}}",
              "document_types": [
                {"title": "invoice", "document_id": "invoice", "instructions": ""},
                {"title": "receipt", "document_id": "receipt", "instructions": ""}
              ]
            }
          },
          {
            "visual_properties": {"position": {"x": 500, "y": 0}},
            "name": "extract_invoice_data",
            "task_executor_name": "text_to_structured",
            "task_title": "Extract Invoice Data",
            "parameters": {
              "worker": "gpt-4.1",
              "mime_type": "{{classify_document.splits[0].mime_type}}",
              "document_url": "{{classify_document.splits[0].document_url}}",
              "fields": [
                {"id": "invoice_number", "title": "invoice_number", "data_type": "string", "instructions": ""},
                {"id": "total_amount", "title": "total_amount", "data_type": "float", "instructions": "identify the total amount"},
                {"id": "vendor_name", "title": "vendor_name", "data_type": "string", "instructions": ""}
              ]
            }
          },
          {
            "visual_properties": {"position": {"x": 1000, "y": 0}},
            "name": "validate_total",
            "task_executor_name": "collection_validation",
            "task_title": "Validate Total Amount",
            "parameters": {
              "input_collection": "{{extract_invoice_data.total_amount}}",
              "validators": [{"name": "Not Empty Validation"}]
            }
          }
        ]
      }
    }]
  }
}')

FLOW_ID=$(echo "$FLOW_RESPONSE" | jq -r .id)
if [ -z "$FLOW_ID" ] || [ "$FLOW_ID" = "null" ]; then
  echo "❌ Failed to create flow"
  echo "Response: $FLOW_RESPONSE"
  exit 1
fi
echo "✅ Flow created: $FLOW_ID"
echo "   View flow: https://flows.super.ai/flows/$FLOW_ID"

echo "🚀 Step 4: Creating flow execution..."
EXEC_RESPONSE=$(curl -sf -X POST https://flows.super.ai/api/flow-executions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"flow_id\":\"$FLOW_ID\",\"input\":$INPUT_DATA}")

EXEC_ID=$(echo "$EXEC_RESPONSE" | jq -r .id)
if [ -z "$EXEC_ID" ] || [ "$EXEC_ID" = "null" ]; then
  echo "❌ Failed to create execution"
  echo "Response: $EXEC_RESPONSE"
  exit 1
fi
echo "✅ Flow execution created: $EXEC_ID"
echo "   View in dashboard: https://flows.super.ai/flows/$FLOW_ID?view=data"

echo "⏳ Step 5: Waiting for execution to complete..."
for i in {1..30}; do
  sleep 2
  STATUS=$(curl -sf "https://flows.super.ai/api/flow-executions/$EXEC_ID" \
    -H "Authorization: Bearer $ACCESS_TOKEN" | jq -r .status)

  echo "   Status: $STATUS (attempt $i/30)"

  if [ "$STATUS" = "completed" ]; then
    echo "✅ Execution completed!"
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "❌ Execution failed"
    exit 1
  fi

  if [ $i -eq 30 ]; then
    echo "⚠️  Timeout waiting for completion (use webhooks in production)"
  fi
done

echo "📊 Step 6: Fetching results..."
RESULTS=$(curl -sf "https://flows.super.ai/api/task-executions?flow_execution_id=$EXEC_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN")

echo "$RESULTS" | jq .
echo ""
echo "✅ All done! Check results above."

Save this as run_flow.sh, make it executable (chmod +x run_flow.sh), and run it!

This script demonstrates the complete workflow:

  1. Getting anonymous key
  2. Authentication with credentials
  3. Creating a new flow with full task definitions in a single API call
  4. Running the flow on a sample invoice
  5. Polling for completion
  6. Fetching results (use webhooks in production!)

Troubleshooting

Common Issues and Solutions

"Authentication failed" or "Invalid credentials"

Problem: Cannot get access token

Solutions:

# 1. Verify your credentials work in the web UI first
#    Visit https://flows.super.ai and log in

# 2. Check for special characters in password
#    Escape special characters or use environment variables:
export EMAIL="your@email.com"
export PASSWORD='your-password'  # Single quotes preserve special chars

# 3. Verify anonymous key is valid
ANON_KEY=$(curl -s https://flows.super.ai/api/auth/anon-key | jq -r .anon_key)
echo "Anon key: $ANON_KEY"  # Should be a long JWT string

"Flow not found" (404)

Problem: Cannot execute flow with given ID

Solutions:

# 1. Verify the flow was created successfully
#    Check the response from the flow creation step
echo "Created flow ID: $FLOW_ID"

# 2. List all flows you have access to
curl https://flows.super.ai/api/flows \
  -H "Authorization: Bearer $TOKEN" | jq '.flows[] | {id, name}'

# 3. Verify you're using the correct UUID format
#    Flow IDs look like: 550e8400-e29b-41d4-a716-446655440000

# 4. Check you're logged into the correct organization
#    Flows are organization-specific

"Unauthorized" (401) mid-session

Problem: Token expired after 1 hour

Solution:

# Implement token refresh
curl -X POST 'https://core.flows.super.ai/auth/v1/token?grant_type=refresh_token' \
  -H 'Content-Type: application/json' \
  -H "apikey: $ANON_KEY" \
  -d "{\"refresh_token\":\"$REFRESH_TOKEN\"}" | jq -r .access_token

"Bad Request" (400) when creating execution

Problem: Invalid input data

Solutions:

# 1. For flows created in this guide, use the standard file input format
INPUT='{"filename":"invoice.pdf","mime_type":"application/pdf","document_url":"https://cdn.super.ai/invoice-example.pdf"}'

# 2. Validate your JSON is well-formed
echo '{"filename":"invoice.pdf","mime_type":"application/pdf","document_url":"https://cdn.super.ai/invoice-example.pdf"}' | jq .

# 3. Check the flow's required input schema (for custom flows)
curl "https://flows.super.ai/api/flows/$FLOW_ID" \
  -H "Authorization: Bearer $TOKEN" | jq .input_schema

# 4. Common input patterns:
#    - File input: {"filename":"doc.pdf","mime_type":"application/pdf","document_url":"https://..."}
#    - Custom fields: Check your flow's input schema with the command above

Execution stuck in "running" status

Problem: Flow execution doesn't complete

Solutions:

  1. Check execution status: Some flows take minutes for complex documents
  2. Use webhooks: Don't poll—get notified when complete
  3. Check task executions: See which task is blocking
    curl "https://flows.super.ai/api/task-executions?flow_execution_id=$EXEC_ID" \
  -H "Authorization: Bearer $TOKEN" | jq '.task_executions[] | {task_name, status}'

"SSL/TLS handshake failure"

Problem: Network/certificate issues

Solutions:

# 1. Update curl and certificates
brew upgrade curl  # macOS
apt-get update && apt-get install curl ca-certificates  # Linux

# 2. Test connectivity
curl -v https://flows.super.ai/api/auth/anon-key

# 3. Check for corporate proxy/firewall
#    Contact your IT team if you're behind a corporate network

Rate Limiting

Problem: Too many requests

Solution:

  • The API implements fair-use rate limiting
  • If you receive 429 (Too Many Requests), wait before retrying
  • Implement exponential backoff:
    # Wait 1s, then 2s, then 4s, etc.
for i in 1 2 4 8 16; do
  response=$(curl -s -w "%{http_code}" ...)
  if [ "$response" != "429" ]; then break; fi
  sleep $i
done

Still Having Issues?

  1. Check API Status: status.super.ai
  2. Review Logs: Include the request_id from error responses
  3. Contact Support: support@super.ai with:
    • Your flow execution ID
    • The request_id from error responses
    • Steps to reproduce the issue

Error Handling

The API uses standard HTTP status codes:

Code Meaning Example
200 Success Request completed successfully
201 Created Flow execution created
400 Bad Request Invalid input data or missing required fields
401 Unauthorized Missing or invalid access token
403 Forbidden Insufficient permissions for this resource
404 Not Found Flow or execution ID doesn't exist
422 Validation Error Request body failed schema validation
500 Server Error Internal error (retry with exponential backoff)

Error Response Format

{
  "error": {
    "code": "not_found",
    "message": "Flow not found"
  },
  "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
}

Tip: Include the request_id when contacting support for faster resolution.

Best Practices

Security

  • Store access tokens in environment variables or secure secret management systems
  • Use HTTPS for all webhook endpoints
  • Verify webhook signatures before processing

Performance

  • Use webhooks instead of polling for better performance and lower latency
  • Implement exponential backoff for retry logic
  • Cache access tokens (valid for 1 hour)

Error Handling

  • Handle all error status codes gracefully
  • Implement retry logic for 5xx errors
  • Log request_id for troubleshooting

Next Steps

Explore the Platform

API Documentation

Build with SDKs (coming soon)

Get Help

Was this section helpful?

What made this section unhelpful for you?

On this page
  • API Quickstart
View as Markdown

Ask an AI

Open in ChatGPTOpen in ClaudeOpen in Perplexity

Code with AI

Open in Copilot