# Human-verification challenge configuration for the sign-in and signup forms Source: https://docs.flows.super.ai/api-reference/auth/human-verification-challenge-configuration-for-the-sign-in-and-signup-forms /openapi/superai-flows-openapi.json get /api/auth/captcha-config Tell the sign-in and signup forms whether to render a human-verification challenge. Public and unauthenticated: the forms read it before any session exists. The response carries only the public site key and the challenge state, never a secret — GoTrue holds the provider secret and does the verification. The state — on/off and provider both — comes from Supabase (FLO-2927), so changing either is a dashboard change with no application config change and no redeploy. Enterprise SAML SSO ignores this entirely; it is initiated server-side with service-role credentials, which GoTrue exempts from captcha. # Pre-flight signup email policy check for magic link Source: https://docs.flows.super.ai/api-reference/auth/pre-flight-signup-email-policy-check-for-magic-link /openapi/superai-flows-openapi.json get /api/auth/signup-email-policy Pre-flight UX check used by the signup form before sending a magic link. Unauthenticated and purely domain-list based — it performs no account lookup, so it cannot be used to enumerate accounts. Hard enforcement stays in POST /auth/self-service/complete; clients bypassing this check are still rejected there. Mirrors the GET /auth/login-method pre-flight pattern. # Public compliance configuration for the signup and sign-in surfaces Source: https://docs.flows.super.ai/api-reference/auth/public-compliance-configuration-for-the-signup-and-sign-in-surfaces /openapi/superai-flows-openapi.json get /api/auth/public-config Serve the compliance URLs and flags the pre-auth surfaces need (FLO-2652). Unauthenticated, unparameterised and side-effect free — modelled on ``GET /auth/anon-key`` rather than on an email-parameterised pre-flight. This is read by every visitor who lands on the sign-in page, so per-email limiting would be meaningless and a per-IP limiter would fire on shared egress addresses. Everything returned is already public: two URLs to published pages, two published effective dates, and one boolean about whether we ask for a date of birth. The client MUST read its compliance links from here rather than hardcoding them. Hardcoding is what left the signin form pointing at ``super.ai/terms_of_service.pdf`` — a document naming a contracting party we no longer use — across a change of entity, with nothing to catch it. # Resend user invitation email Source: https://docs.flows.super.ai/api-reference/auth/resend-user-invitation-email /openapi/superai-flows-openapi.json post /api/auth/resend-invite Re-send an invitation using the token from the original invite. Unauthenticated by construction: it backs the expired- and invalid-invitation screens, where the caller holds the invitation link but cannot hold a session. The response is constant. Whether the token resolved, and whether mail was sent, are both invisible to the caller — that is what stops this endpoint being used to test whether an address has an account. No log line here may carry the token or the resolved address. # Reset Password Source: https://docs.flows.super.ai/api-reference/auth/reset-password /openapi/superai-flows-openapi.json post /api/auth/reset-password # Resolve login method for an email Source: https://docs.flows.super.ai/api-reference/auth/resolve-login-method-for-an-email /openapi/superai-flows-openapi.json get /api/auth/login-method Pre-flight check used by the login form before invoking Supabase sign-in. This endpoint is unauthenticated; it only reveals whether a given email's domain is configured for strict SSO. Hard enforcement lives in the auth middleware — clients bypassing this check still get rejected on the first authenticated request. # Retrieve authentication API key Source: https://docs.flows.super.ai/api-reference/auth/retrieve-authentication-api-key /openapi/superai-flows-openapi.json get /api/auth/anon-key Retrieve the anonymous authentication key required for client authentication. Returns the authentication key that client applications need to authenticate with the authentication API at core.flows.super.ai. This key enables clients to perform password-based authentication and obtain JWT access tokens. Context: - This key is required to make authentication requests to core.flows.super.ai - The key is safe for use in client-side applications (browsers, mobile apps) - Does not grant admin privileges or direct API access - Only enables authentication operations (login, token refresh) - Same key is used across all clients and organizations - Key is long-lived and rarely rotated Authentication Flow: 1. Client retrieves anonymous key from this endpoint 2. Client sends authentication request to core.flows.super.ai 3. Include anonymous key in 'apikey' header 4. Authentication service validates credentials and returns JWT tokens 5. Client uses JWT access token for subsequent API requests Use Cases: - Web application initialization requiring user authentication - Mobile app setup for authentication integration - Testing authentication flow in development - Building custom authentication UI - Integrating third-party applications with authentication service Security Considerations: - This key is public and safe for client-side applications - Does not provide access to user data or administrative functions - Only enables authentication API operations - Users must still provide valid credentials (email/password) - Rate limiting applied at authentication service level - Key rotation handled by platform administrators Integration Example: After retrieving this key, use it to authenticate users: Step 1: Get the anonymous key (this endpoint) Step 2: Use the key to authenticate users at core.flows.super.ai Step 3: Receive JWT tokens for API access Related Endpoints: - POST /auth/resend-invite - Re-send an invitation using the token from the original invite - GET /profile/me - Retrieve authenticated user profile - See authentication tag description for complete authentication guide Error Handling: - Returns 500 if key is not configured on server - Indicates server misconfiguration requiring administrator attention - Contact platform support if persistent errors occur # Submit a self-service access request Source: https://docs.flows.super.ai/api-reference/auth/submit-a-self-service-access-request /openapi/superai-flows-openapi.json post /api/auth/access-request Record an access request from a visitor whose email failed the signup policy. Unauthenticated and whitelisted — the caller has no account. The submission is persisted (source of truth, one row per email — a resubmit upserts) and a Slack notification to the self-service channel is fired as a background task so a slow or failing webhook never blocks or fails the response. Only a genuinely new request notifies, so a resubmit (or a double-click) won't re-ping the channel. The response is a constant acknowledgement regardless of whether the request was new or already existed, so it can't be used to enumerate which emails have requested access. The optional attribution/referrer/timezone/distinct id the client sends, plus the User-Agent, are stored on the row and summarised into a source line on the Slack message. A resubmit replaces them on the row but does not re-announce. Sanitising, summarising and redacting all happen in the service; the handler only reads the header and schedules the notification. # The authenticated caller's terms-acceptance state Source: https://docs.flows.super.ai/api-reference/auth/the-authenticated-callers-terms-acceptance-state /openapi/superai-flows-openapi.json get /api/auth/terms-status Report whether this user still has a document to accept (FLO-2652). Read by the app shell on load; the blocking re-acceptance dialog is driven entirely by ``reacceptance_required``. ``with_session_bypass_rls`` because ``terms_acceptance`` grants only the backend connection user and carries no per-role policy. The scoping is explicit instead: the service reads rows for ``user_info.id``, and no other user id can enter this call path. # Authentication Source: https://docs.flows.super.ai/api-reference/authentication How to authenticate with the SuperAI Flows API using JWT bearer tokens or service-account API keys. SuperAI Flows uses **JWT-based authentication**, managed through `core.flows.super.ai`. All API endpoints except a small set of public paths require a valid bearer token. Some endpoints (and the MCP server) additionally accept a **service-account API key**. ## Authentication methods | Method | Header | Best for | | - | - | - | | **Bearer token** (JWT) | `Authorization: Bearer ` | User-driven API access | | **API key** | `X-API-Key: saf_org_...` | Programmatic / service-to-service access | ## Bearer token flow A public endpoint — no authentication required. The anon key is a long-lived key used only to authenticate against the auth service. ```bash theme={null} curl https://flows.super.ai/api/auth/anon-key ``` ```bash theme={null} 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": "you@example.com", "password": "your-password"}' ``` Returns a JWT `access_token` and a `refresh_token`. ```bash theme={null} curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ https://flows.super.ai/api/flows ``` ## Token lifetimes | Token | Lifetime | Use | | - | - | - | | **Access token** | 1 hour | Include in every API request | | **Refresh token** | 30 days | Obtain new access tokens without re-authenticating | Refresh an expired access token: ```bash theme={null} 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"}' ``` ## API keys Service-account API keys (prefix `saf_`) provide programmatic access without a login flow. An organization admin creates one under **Organization settings → Service accounts** in the profile menu. Pass the key in the `X-API-Key` header: ```bash theme={null} curl -H "X-API-Key: saf_org_..." \ https://flows.super.ai/api/flows ``` API keys are the only supported method for the [MCP server](/api-reference/mcp-server). Tokens and API keys grant access to your organization's resources — treat them like passwords. Store them in environment variables or a secret manager, use HTTPS for all requests, and never commit them to version control. ## Common authentication errors | Status | Code | Meaning | | - | - | - | | 401 | `user_info_not_found` | Token invalid, expired, or user not found — re-authenticate | | 401 | — | Missing or malformed `Authorization` / `X-API-Key` header | | 403 | `forbidden` | Authenticated, but no access to the requested resource | See the full [Error Codes reference](/api-reference/errors) for details. # Error Codes Source: https://docs.flows.super.ai/api-reference/errors Error response format, HTTP status codes, and the full catalog of machine-readable error codes. All API errors follow a consistent JSON structure with a machine-readable `code` and a `request_id` for support. ```json theme={null} { "error": { "message": "Human-readable error description", "code": "machine_readable_error_code", "details": {} }, "request_id": "uuid-v4-request-identifier" } ``` **Response headers:** `X-Request-ID` carries the same value as `request_id` for server-side log correlation. **Fields:** * `error.message` (string, required) — Human-readable error description * `error.code` (string, optional) — Machine-readable error code for programmatic handling * `error.details` (any, optional) — Additional context (e.g., validation errors) * `request_id` (string, optional) — Unique request identifier for debugging ## HTTP status codes | Status | Description | Usage | | - | - | - | | `200 OK` | Successful request | Most `GET`, `PATCH`, `DELETE` operations | | `201 Created` | Resource created | `POST` operations that create new resources | | `400 Bad Request` | Invalid request parameters | Malformed DSL, invalid query parameters, bad execution references | | `401 Unauthorized` | Authentication required or failed | Missing/invalid bearer token, expired token, user not found | | `404 Not Found` | Resource does not exist | Flow or execution ID not found, entity not in database | | `409 Conflict` | Resource already exists | Duplicate flow name, duplicate execution ID, constraint violation | | `422 Unprocessable Entity` | Validation error | Request body fails validation, type errors, constraint violations | | `500 Internal Server Error` | Unexpected server error | Database errors, repository errors, unhandled exceptions | ## Error code catalog ### `validation_error` **HTTP 422.** Request body or parameters failed validation. Review the `details` array, which lists each invalid field: ```json theme={null} { "error": { "message": "Request validation failed", "code": "validation_error", "details": [ { "type": "missing", "loc": ["body", "display_name"], "msg": "Field required", "input": {} } ] }, "request_id": "550e8400-e29b-41d4-a716-446655440000" } ``` Each `details` item contains: `type` (error type), `loc` (JSON path to the field), `msg` (message), `input` (the invalid value), and optional `ctx` (constraints) and `url`. ### `invalid_dsl_input` **HTTP 400.** The flow DSL definition is malformed or invalid — missing required fields, invalid task executor names, circular dependencies, or configurations that don't match executor schemas. ```json theme={null} { "error": { "message": "Flow definition validation failed: tasks must be an array", "code": "invalid_dsl_input", "details": [ "definition.tasks: Expected array but got object", "definition.version: Must be a positive integer" ] }, "request_id": "550e8400-e29b-41d4-a716-446655440000" } ``` Ensure all tasks reference valid executors and that dependencies form a valid directed acyclic graph (DAG). ### `not_found` **HTTP 404.** The requested resource does not exist — wrong ID, deleted resource, or a resource owned by a different organization (and therefore not visible). ```json theme={null} { "error": { "message": "Flow not found with id: 550e8400-e29b-41d4-a716-446655440000", "code": "not_found" }, "request_id": "660e8400-e29b-41d4-a716-446655440000" } ``` ### `conflict` **HTTP 409.** The request conflicts with existing state or a database constraint — for example, a duplicate flow name within an organization. Use a different identifier, or retry with backoff for concurrent-modification conflicts. ### `bad_request` **HTTP 400.** The request is syntactically correct but semantically invalid — invalid query parameter values, references to non-existent resources, or invalid state transitions. ```json theme={null} { "error": { "message": "Can't find execution referenced in query parameter 'start_from_execution_id'", "code": "bad_request" }, "request_id": "550e8400-e29b-41d4-a716-446655440000" } ``` ### `user_info_not_found` **HTTP 401.** User information could not be retrieved from the authentication token — invalid/expired token or a deactivated account. Re-authenticate to obtain a fresh token. ### `repository_error` **HTTP 500.** A database or repository-layer error occurred (connection failure, query timeout, deadlock). Retry with exponential backoff; contact support with the `request_id` if it persists. ### `service_error` **HTTP 500** (or a custom status). An application service-layer error — business-logic failure, external integration failure, or unexpected state. Check the `message` for specifics. ### `internal_error` **HTTP 500.** An unexpected internal error. These are automatically logged with full stack traces. Retry (it may be transient) and report the `request_id`. ### HTTP errors without a code Some errors return a status code without an `error.code` field — for example `405 Method Not Allowed`, `415 Unsupported Media Type`, `413 Request Entity Too Large`, or `429 Too Many Requests`. Handle these by HTTP status. ## Handling errors ```python theme={null} if response.status_code >= 400: error = response.json().get("error", {}) code, message = error.get("code"), error.get("message") ``` ```python theme={null} if code == "not_found": return None elif code == "validation_error": display_validation_errors(response.json()["error"]["details"]) elif code == "user_info_not_found": redirect_to_login() ``` ```python theme={null} RETRYABLE = {"repository_error", "service_error", "internal_error"} if code in RETRYABLE: retry_with_backoff(request) ``` ```python theme={null} request_id = response.json().get("request_id") or response.headers.get("X-Request-ID") logger.error(f"API error: {message} (request_id: {request_id})") ``` ## Summary | Error code | HTTP status | Category | Retryable | | - | - | - | - | | `validation_error` | 422 | Client | No — fix request | | `invalid_dsl_input` | 400 | Client | No — fix DSL | | `not_found` | 404 | Client | No — resource doesn't exist | | `conflict` | 409 | Client | No — resource conflict | | `bad_request` | 400 | Client | No — fix request | | `user_info_not_found` | 401 | Auth | No — re-authenticate | | `repository_error` | 500 | Server | Yes — retry | | `service_error` | 500 | Server | Yes — retry | | `internal_error` | 500 | Server | Yes — retry and report | | *(no code)* | 4xx/5xx | HTTP | Depends on status | # Download file by URI (with redirect) Source: https://docs.flows.super.ai/api-reference/files/download-file-by-uri-with-redirect /openapi/superai-flows-openapi.json get /api/files/download Download a file by resolving its gs:// storage URI. This endpoint provides a convenient way to download files directly using curl or wget. By default, it returns a 302 redirect to a pre-signed download URL. **Quick download with curl:** ``` curl -L -H "X-API-Key: $KEY" "https://flows.super.ai/api/files/download?uri=gs://..." -o file.pdf ``` The `-L` flag tells curl to follow the redirect automatically. **Note:** The URI will appear in server access logs. For sensitive files, use the POST `/api/files/resolve` endpoint instead. # Resolve storage URI to download URL Source: https://docs.flows.super.ai/api-reference/files/resolve-storage-uri-to-download-url /openapi/superai-flows-openapi.json post /api/files/resolve Resolve a gs:// storage URI to a temporary pre-signed download URL. This is the **recommended endpoint** for downloading files from task outputs. Simply pass the `gs://` URI exactly as you received it—no parsing required. The returned `download_url` is a pre-signed URL valid for **1 hour** that can be used to download the file directly without additional authentication. **Why use POST instead of GET?** Using POST keeps the URI out of server access logs and browser history, which is better for security when dealing with sensitive files. # Add task status updates (Internal API) Source: https://docs.flows.super.ai/api-reference/flow-executions/add-task-status-updates-internal-api /openapi/superai-flows-openapi.json post /api/flow-executions/{flow_execution_id}/task-status Add task status updates to a flow execution (Internal API). This endpoint is used by system workers to report task execution status changes. Multiple task statuses can be added in a single request for batch efficiency. Status updates trigger state transitions and WebSocket notifications. ⚠️ Internal API: This endpoint is designed for internal system communication. Direct customer usage is not recommended. Use GET /task-executions instead. Context: - Called by system workers during task execution - Updates task status records in bulk for performance - Triggers task output state calculations - Sends WebSocket notifications asynchronously - Worker receives immediate response without blocking on notifications Behavior: 1. Validates flow execution exists and is accessible 2. Creates status records for each task in batch 3. Updates related task output states in parallel 4. Sends WebSocket notifications in background task 5. Returns immediately to worker for low latency Performance Optimizations: - Batch inserts for multiple status updates (~50ms for 10 tasks) - WebSocket notifications processed asynchronously - Task output state updates use batch operations - Response returns before notification delivery completes Use Cases: - System workers reporting task start/completion - Bulk status updates during execution - Real-time execution monitoring via WebSocket Important Notes: - This endpoint does NOT retrieve task status (use GET /task-executions) - Requires service-level authentication token - Not intended for direct customer API integration - WebSocket notifications may arrive after HTTP response Business Logic: - Task output states recalculated based on new statuses - Multiple status updates for same task create history - Execution-level status synced to awaiting_input when any task is HITL-suspended - Status transitions not validated (allows any status value) Related Internal Endpoints: - POST /flow-executions - Creates parent execution - GET /task-executions - Retrieves task execution details - WebSocket /ws/flows/{flow_id} - Receives status notifications # Cancel a flow execution Source: https://docs.flows.super.ai/api-reference/flow-executions/cancel-a-flow-execution /openapi/superai-flows-openapi.json post /api/flow-executions/{flow_execution_id}/cancel Cancel a running flow execution. # Create and start a flow execution Source: https://docs.flows.super.ai/api-reference/flow-executions/create-and-start-a-flow-execution /openapi/superai-flows-openapi.json post /api/flow-executions Create a new flow execution and start workflow processing. This endpoint creates a flow execution record and attempts to start the associated workflow processing. The execution is created with status 'queued' and atomically promoted to 'running' if the organization's concurrency limit allows. When the organization's credits are exhausted, the execution is still created (201) but held with status 'pending_payment' instead of being processed: no workflow starts, and the execution is released back to 'queued' automatically once credits are restored. Check the response's `status` field to detect this. Context: - Flow executions represent runtime instances of flow definitions - Each execution is isolated and maintains its own state - Input data must conform to the flow's input schema - Executions are scoped to the user's organization - WebSocket notifications are sent on creation for real-time updates Input Validation: - Input data is validated against the flow's input task schema - Validation occurs before database record creation or workflow start - Invalid input returns 400 Bad Request with detailed error messages - Validation errors include field location, type, and specific issue - No flow execution record is created if validation fails Execution Flow: 1. Validates flow exists and user has access 2. Validates input data against flow's input schema 3. Creates execution record in database 4. Starts workflow processing asynchronously 5. Sends WebSocket notification to connected clients 6. Returns immediately (does not wait for completion) Performance Notes: - Response time: < 200ms (workflow starts asynchronously) - Does not block on workflow completion - WebSocket notifications sent in background task Use Cases: - Trigger flow execution from UI dashboard - Automated flow execution via API integration - Batch processing of multiple documents - Event-driven workflow automation Related Endpoints: - GET /flow-executions/{id} - Check execution status - GET /flow-executions - List all executions for a flow - POST /flow-executions/{id}/execute - Re-execute failed execution # List flow executions with filtering and pagination Source: https://docs.flows.super.ai/api-reference/flow-executions/list-flow-executions-with-filtering-and-pagination /openapi/superai-flows-openapi.json get /api/flow-executions List flow executions with filtering, sorting, and pagination. Retrieve a paginated list of flow executions for a specific flow with support for filtering by status, tags, and date ranges. Results can be sorted by creation or update time. Context: - Returns executions for a single flow (specified by flow_id) - Excludes soft-deleted executions from results - Supports multiple filtering dimensions for flexible queries - Pagination uses offset-based approach (page/page_size) Filtering Logic: - Status filter: Returns executions containing tasks with ANY of specified statuses - Tag filter: Returns executions containing tasks with ANY of the specified tags, or with ALL of them (anywhere in the run) when tags_mode=all - Date range: created_after/created_before bound created_at; updated_after/updated_before bound updated_at (all inclusive, ISO 8601) - Multiple filters combined with AND logic - Empty filters return all executions Pagination: - Offset-based: page=1, page_size=10 returns first 10 results - Default: page=1, page_size=10 - Maximum page_size: 1000 results - Maximum page: 10,000 (to prevent excessive database load) - Use start_from_execution_id for cursor-like pagination Sorting: - sort_field: 'created_at' (when execution was created) or 'updated_at' (when execution was last modified) - sort_direction: 'asc' (oldest first) or 'desc' (newest first) - Default: sort by created_at desc (most recently created first) Performance Considerations: - ~50ms for 100 results - Consider caching for frequently accessed pages - Large page_size values increase response time linearly Use Cases: - Display execution history in UI dashboard - Monitor recent execution failures (filter by status='failed') - Find executions by business context (filter by tags) - Export execution audit trail - Identify oldest pending executions (sort by created_at asc) Example Queries: - Recent failures: ?flow_id=xxx&status=failed&sort_field=created_at&sort_direction=desc&page_size=20 - Tagged executions: ?flow_id=xxx&tags=priority:high&tags=customer:acme - Paginated view: ?flow_id=xxx&page=2&page_size=50 - Completed in window: ?flow_id=xxx&status=completed&created_after=2026-06-18T08:00:00Z&created_before=2026-06-18T10:00:00Z Related Endpoints: - GET /flow-executions/{id} - Get single execution details - POST /flow-executions - Create new execution - GET /flows/{id} - Get flow definition details # List the execution IDs of one filtered, sorted runs-table page Source: https://docs.flows.super.ai/api-reference/flow-executions/list-the-execution-ids-of-one-filtered-sorted-runs-table-page /openapi/superai-flows-openapi.json post /api/flow-executions/page-ids IDs of the executions on the requested page, in the page's order. Accepts the same `filters`/`sort` the runs table sends over the WebSocket `set_page_view` frame and applies the identical mapping, so the IDs are exactly the rows the table shows. POST because the `metadata` filter is nested and does not fit query parameters. # Patch Flow Execution Status Source: https://docs.flows.super.ai/api-reference/flow-executions/patch-flow-execution-status /openapi/superai-flows-openapi.json patch /api/flow-executions/{flow_execution_id}/status Patch the status of a flow execution. # Re-execute a flow execution Source: https://docs.flows.super.ai/api-reference/flow-executions/re-execute-a-flow-execution /openapi/superai-flows-openapi.json post /api/flow-executions/{flow_execution_id}/execute Re-execute a flow execution, optionally skipping cached results. This endpoint triggers re-execution of an existing flow execution. It can selectively re-run failed tasks or re-run the entire flow from scratch. Useful for retrying failed executions or refreshing stale data. **Asynchronous.** A 202 means the re-run has been accepted and durably recorded, not that it has happened. Resetting the task state and starting the new run take a few seconds, and both survive a restart on our side. Do not assume the execution's tasks have been reset when this returns — watch the flow execution (the `Location` header) or subscribe to its WebSocket events, and act when its status reaches `queued`/`running`. Context: - Re-executes workflows that have completed or failed - Can reuse successful task results (cached execution) - Useful for handling transient failures - Updates flow to latest version if changed since original execution - Creates new workflow instance with same execution ID - A repeat request while one is still in progress is folded into it rather than starting a competing re-run Execution Modes: 1. Full Re-execution (only_stale=false, default): - Starts workflow from beginning - All tasks execute regardless of previous state - Previous results are discarded - Use for: Complete retry after fixing flow definition 2. Stale-Only Re-execution (only_stale=true): - Only re-runs tasks marked as 'stale' - Reuses results from successful tasks - Faster for partial failures - Use for: Refreshing outdated data without full re-run Behavior: - Terminates existing workflow if still running - Updates flow_version to latest version - Maintains same execution ID for traceability - Status transitions: any → queued → running (or → failed if the re-run could not be completed, which is distinct from the flow itself failing) - Does not create new execution record Performance Notes: - Response time: < 200ms (the request only validates and schedules) - The reset and the new run land within seconds of the response - Stale-only mode significantly faster for large flows - Full re-execution recalculates all task outputs Use Cases: - Retry failed execution after fixing flow definition - Refresh data after external system updates - Resume execution after transient service outage - Update execution to use latest flow version Related Endpoints: - GET /flow-executions/{id} - Check re-execution status - POST /flow-executions - Create new execution instead of re-running # Retrieve a specific flow execution Source: https://docs.flows.super.ai/api-reference/flow-executions/retrieve-a-specific-flow-execution /openapi/superai-flows-openapi.json get /api/flow-executions/{flow_execution_id} Retrieve detailed information for a specific flow execution. Fetch a single flow execution by its unique identifier. Returns execution metadata including status, input data, and timestamps. Context: - Retrieves single execution regardless of status (except deleted) - Soft-deleted executions return 404 Not Found - Includes full input data as provided at creation - Useful for monitoring execution progress Use Cases: - Check status of long-running execution - Retrieve input data for debugging - Display execution details in UI - Poll for execution completion Performance Notes: - ~10ms average response time - Highly cacheable (status changes infrequently) Related Endpoints: - GET /flow-executions - List all executions for a flow - POST /flow-executions/{id}/execute - Re-execute this execution - GET /task-executions?flow_execution_id={id} - Get task details - DELETE /flow-executions/{id} - Delete this execution # Soft delete a flow execution Source: https://docs.flows.super.ai/api-reference/flow-executions/soft-delete-a-flow-execution /openapi/superai-flows-openapi.json delete /api/flow-executions/{flow_execution_id} Soft delete a flow execution by marking it as deleted. This endpoint performs a soft delete by setting the execution status to 'deleted'. The execution record remains in the database but is excluded from list operations and cannot be retrieved through standard endpoints. Context: - Soft delete preserves audit trail and historical data - Does NOT stop running workflows (use cancel endpoint for that) - Deleted executions do not appear in GET /flow-executions list - Operation is idempotent - deleting already deleted execution succeeds - Deletion is permanent - no undelete functionality exists Behavior: - Updates execution status to 'deleted' in database - Maintains all execution data for audit purposes - Removes from user-facing list queries - Does not affect related task executions or outputs - Triggers WebSocket notification for status change Use Cases: - Remove test executions from production environment - Clean up failed executions no longer needed - Archive old executions while preserving data Important Notes: - To stop a RUNNING workflow, use cancel endpoint (not yet implemented) - Soft delete does not free up workflow resources - Consider hard delete for GDPR compliance (requires database migration) Related Endpoints: - GET /flow-executions - List excludes deleted executions - POST /flow-executions - Create new execution # Create a new flow Source: https://docs.flows.super.ai/api-reference/flows/create-a-new-flow /openapi/superai-flows-openapi.json post /api/flows Create a new flow in draft status. Creates a flow definition that can be executed via the flow executions API. New flows are assigned version 1 and status 'draft', allowing iterative development before marking as 'published' for production use. ## Flow Lifecycle 1. **Draft**: Newly created flows start here. Editable and testable. 2. **Published**: Ready for production. Can be executed by end users. ## DSL Validation The flow definition is validated against the DSL schema during creation. If validation fails, a 400 error is returned with detailed error messages in the `details` array. ## Common Validation Errors - Missing required fields (tasks, edges) - Invalid task executor names - Circular dependencies in task graph - Invalid parameter types for task executors # Delete a flow Source: https://docs.flows.super.ai/api-reference/flows/delete-a-flow /openapi/superai-flows-openapi.json delete /api/flows/{flow_id} Soft delete a flow. Marks a flow as deleted without permanently removing it from the database. Deleted flows are hidden from listings but can be recovered if needed. ## Behavior - Flow is marked with `deleted=true` flag - Flow no longer appears in list/get operations - All versions of the flow are marked as deleted - Can be recovered by support team if needed - In-flight executions (queued, running, awaiting input, pending payment) are cancelled, and their open human review tasks are cancelled and removed from reviewers' inboxes ## Important Notes - This is a soft delete, not a permanent deletion - Associated executions and files are NOT deleted - Cancelled executions stay cancelled if the flow is recovered - Deleted flows cannot be undeleted via API (contact support) # Generate file download URL Source: https://docs.flows.super.ai/api-reference/flows/generate-file-download-url /openapi/superai-flows-openapi.json post /api/flows/download-url Generate pre-signed URL for downloading a file. Creates a temporary download URL (valid 1 hour) for a previously uploaded file. The requested `file_key` is authorized against the caller's org before signing — a key belonging to another organization returns 404. ## Download Process 1. Get file_key from file listing or upload response 2. Call this endpoint with the file_key 3. Use returned URL in browser or GET request to download file # Generate file upload URL Source: https://docs.flows.super.ai/api-reference/flows/generate-file-upload-url /openapi/superai-flows-openapi.json post /api/flows/{flow_id}/upload-url Generate pre-signed URL for uploading files to a flow. Creates a temporary upload URL that allows direct file upload to cloud storage without exposing storage credentials. Each URL is valid for 1 hour. The target flow must belong to the caller's organization — a flow owned by another org returns 404 without signing anything. ## Upload Process 1. Call this endpoint to receive an upload URL 2. Use PUT request to upload your file to the returned `upload_url` 3. Save the returned `file_key` to reference the file later 4. File becomes accessible via the flow immediately after upload ## Notes - The declared `content_type` is passed through to storage; the set of file types a flow accepts depends on the tasks that consume them. - Maximum file size: 100MB # Get available flow tags for autocomplete Source: https://docs.flows.super.ai/api-reference/flows/get-available-flow-tags-for-autocomplete /openapi/superai-flows-openapi.json get /api/flows/available-tags # Get clone info for a flow Source: https://docs.flows.super.ai/api-reference/flows/get-clone-info-for-a-flow /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/clone-info # Get distinct metadata keys for a flow Source: https://docs.flows.super.ai/api-reference/flows/get-distinct-metadata-keys-for-a-flow /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/metadata/keys Get all distinct metadata keys used in runs for this flow. Retrieve distinct metadata keys with optional search-as-you-type autocomplete. Returns up to `limit` keys ordered by the specified field and direction. Example responses: - No search: [{"key": "project", "count": 42}, {"key": "department", "count": 15}] - Search "pro": [{"key": "project", "count": 42}, {"key": "product", "count": 10}] # Get distinct values for a metadata key Source: https://docs.flows.super.ai/api-reference/flows/get-distinct-values-for-a-metadata-key /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/metadata/values Get all distinct values for a specific metadata key across all runs. Retrieve distinct values with optional search-as-you-type autocomplete. Returns up to `limit` values ordered by the specified field and direction. Example: GET /flows/{id}/metadata/values?key=project Response: [{"value": "Alpha", "count": 30}, {"value": "Beta", "count": 12}] Example with search: GET /flows/{id}/metadata/values?key=project&value_like=alp Response: [{"value": "Alpha", "count": 30}, {"value": "Alpine", "count": 5}] # Get specific flow version Source: https://docs.flows.super.ai/api-reference/flows/get-specific-flow-version /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/versions/{version} Retrieve a specific version of a flow. Access historical versions of a flow to view previous definitions, compare changes, or rollback to a previous state. ## Use Cases - View flow definition at a specific point in time - Compare versions to understand what changed - Reference the exact version used in a flow execution # Get tag usage for a flow Source: https://docs.flows.super.ai/api-reference/flows/get-tag-usage-for-a-flow /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/tag-usage List every tag applied to at least one non-deleted execution of this flow. Powers the Tags management tab: one entry per distinct tag with its distinct-execution count, the number of distinct tasks carrying it, the date it was first applied, and a per-task breakdown. Counts are `COUNT(DISTINCT flow_execution_id)`, the same universe the data-tab tag filter counts, so a drill-down row count matches the count shown here. An execution tagged on two tasks counts once in `execution_count` and once per task in `task_breakdown`, so the breakdown may sum higher than the total. Tag matching is case-sensitive: `Reviewed` and `reviewed` are separate entries. Search, sort, and paging are deliberately absent — the response is the full tag set for one flow (a small, human-curated list), and near-duplicate comparison needs the whole set at once. A flow with no tags returns `200 []`. # Get tags for flow executions Source: https://docs.flows.super.ai/api-reference/flows/get-tags-for-flow-executions /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/tags Get all unique tag values from task outputs for a specific flow. Returns distinct tag strings from TaskOutput.tags across all active flow executions. Used to populate tag filter dropdowns dynamically. When task_name is provided, only returns tags from that specific task. # List all flows Source: https://docs.flows.super.ai/api-reference/flows/list-all-flows /openapi/superai-flows-openapi.json get /api/flows List all flows accessible to the authenticated user. Returns flows within the user's organization with pagination, sorting, and search support. Each flow includes its latest version by default. ## Pagination Results are paginated with a default page size of 20. Use `page` and `page_size` parameters to navigate through results. ## Sorting Sort by `created_at` or `updated_at` in `asc` or `desc` direction. Default: `created_at` descending (newest first). ## Search Use `search` parameter for case-insensitive search on flow display names. ## Expansion Parameters Use query parameters to include additional computed fields. See FlowResponse model documentation for details on available expansion parameters and their performance impact. # List all versions of a flow Source: https://docs.flows.super.ai/api-reference/flows/list-all-versions-of-a-flow /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/versions List all versions of a specific flow. Returns complete version history for a flow, ordered by version number (newest first). Each version represents a snapshot of the flow definition at the time it was saved. ## Versioning Behavior - Version numbers start at 1 and increment sequentially - Versions are immutable once created - Latest version is marked with `is_latest: true` ## Use Cases - View flow evolution and change history - Compare different versions - Rollback to previous versions # List flow files Source: https://docs.flows.super.ai/api-reference/flows/list-flow-files /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/files List all files associated with a flow. Returns metadata for all files that have been uploaded to this flow, including original filenames, sizes, and custom metadata. The flow must belong to the caller's organization — a flow owned by another org returns 404. ## Use Cases - Display uploaded files in UI - Verify file uploads completed successfully - Retrieve file keys for download URL generation # List flow invitations Source: https://docs.flows.super.ai/api-reference/flows/list-flow-invitations /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/invitations List all invitations for a specific flow. Returns all users who have been invited to access this flow. ## Permissions - Only org_admin role can view invitations - User must belong to the same organization as the flow # List task summaries for flow version Source: https://docs.flows.super.ai/api-reference/flows/list-task-summaries-for-flow-version /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/versions/{version}/summary List task execution summaries for a specific flow version. Returns lightweight task summaries without full output data, reducing network overhead when you only need execution metadata. ## Performance Benefits - Excludes potentially large task output fields - Significantly faster response times for flows with large outputs - Ideal for listing/summary views ## Use Cases - Display execution history in a table/list - Check task statuses without downloading full outputs - Build dashboards showing execution statistics # List team invitations for a flow Source: https://docs.flows.super.ai/api-reference/flows/list-team-invitations-for-a-flow /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/team-invitations List every team invited to the flow, with current member counts. # List version summaries for a flow Source: https://docs.flows.super.ai/api-reference/flows/list-version-summaries-for-a-flow /openapi/superai-flows-openapi.json get /api/flows/{flow_id}/versions/summary Get lightweight version metadata for the version history sidebar. Returns only metadata (version, timestamps, author, is_latest) without full definitions. Ordered by version descending (newest first). Supports pagination, search by name, and favourite filtering. # Partially update a flow Source: https://docs.flows.super.ai/api-reference/flows/partially-update-a-flow /openapi/superai-flows-openapi.json patch /api/flows/{flow_id} Partially update flow properties. Update specific fields of a flow without replacing the entire object. Only provided fields will be modified; others remain unchanged. ## Updateable Fields - `display_name`: Human-readable flow name - `description`: Flow description - `visibility`: Access control setting - `settings`: Flow-level configuration - `status`: Lifecycle status (draft or published) ## Status Transitions Currently the API allows any status transition. The valid status values are: - `draft`: Flow is in development and can be edited - `published`: Flow is ready for production use # Permanently delete tags from a flow Source: https://docs.flows.super.ai/api-reference/flows/permanently-delete-tags-from-a-flow /openapi/superai-flows-openapi.json delete /api/flows/{flow_id}/tags Permanently delete tags from every execution of this flow. Handles both single and bulk deletion — a single delete sends a one-element `tags` array. All-or-nothing: the whole operation runs in one transaction, so a failure anywhere leaves every tag in place. Tags travel in the request body rather than the path because tag names are free-form user text that can contain `/`, `#`, `%`, spaces, and emoji; a path parameter would be corrupted by proxy and ASGI `%2F` normalization. ## Behavior - Matching is case-sensitive: deleting `reviewed` leaves `Reviewed` untouched. - `flow_task_tag` rows move to `status='deleted'` with `modified_by` stamped — the soft-deleted rows are the audit trail. - The denormalized `task_output.tags` array is recomputed from the surviving active rows, which is what removes the tag from the tag dropdown and the data-tab tag filter. `total_task_outputs_resynced` reports how many rows were rewritten. - Tags on soft-deleted executions are neither counted nor modified. - Deleting a tag with no active rows (already deleted, or a case mismatch) is an idempotent no-op returning `200` with zero counts, not a 404. - One `refresh_all_data` WebSocket event is published after commit so open data tabs re-fetch. ## Permissions Authentication plus RLS, with no role decorator — the same policies that let a caller add a tag let them delete it. ## RLS blast radius The `UPDATE` only reaches rows the caller can see. For `org_admin` / `app_user` that is the whole organization, so the delete is genuinely flow-wide. For `worker` / `publisher` the policies are invitation- and team-scoped, so the tag is stripped only from executions inside the caller's scope and survives elsewhere — an org admin will still see it in the Tags tab. The response counts report what actually changed, which makes the scoping observable. # Remove team invitations from a flow Source: https://docs.flows.super.ai/api-reference/flows/remove-team-invitations-from-a-flow /openapi/superai-flows-openapi.json delete /api/flows/{flow_id}/team-invitations Remove team invitations; members lose access unless they're invited individually or via another team still on the flow. # Remove user invitations from a flow Source: https://docs.flows.super.ai/api-reference/flows/remove-user-invitations-from-a-flow /openapi/superai-flows-openapi.json delete /api/flows/{flow_id}/invitations Remove invitations for specific users from a flow. This endpoint allows admins to revoke access for worker users to specific flows. Once removed, users will no longer be able to access the flow and its executions through the RLS policies enforced at the database level. ## Permissions - Only org_admin role can remove invitations - Users must belong to the same organization as the flow ## Behavior - Removes invitations for all specified user IDs - Non-existent invitations are silently ignored - All deletions are performed in a single transaction ## Use Cases - Revoke worker access from specific flows - Manage flow-level permissions for review workflows - Remove team members who no longer need access # Restore a past version Source: https://docs.flows.super.ai/api-reference/flows/restore-a-past-version /openapi/superai-flows-openapi.json post /api/flows/{flow_id}/versions/{version}/restore Restore a past version as the new latest version. Creates a new version with the same definition as the specified historical version. The restored version becomes the new latest version with an incremented version number. # Retrieve a flow by ID Source: https://docs.flows.super.ai/api-reference/flows/retrieve-a-flow-by-id /openapi/superai-flows-openapi.json get /api/flows/{flow_id} Retrieve a specific flow by ID. Returns the latest version of a flow with its complete definition, metadata, and optional computed fields. This endpoint is typically used when displaying flow details or preparing to execute a flow. ## Behavior - Always returns the latest version unless a specific version is requested via `/flows/{flow_id}/versions/{version}` - Use expansion parameters to include computed fields (see FlowResponse model docs) ## Use Cases - Display flow details in your application UI - Retrieve flow definition before execution - Check flow validation status and errors # Update a single task in flow Source: https://docs.flows.super.ai/api-reference/flows/update-a-single-task-in-flow /openapi/superai-flows-openapi.json put /api/flows/{flow_id}/task Update a single task within a flow definition. Updates one task while preserving the rest of the flow definition. More efficient than replacing the entire definition when modifying a single task. ## Behavior - Task is identified by the `name` field in the task definition - If task doesn't exist, it will be added - If task exists, it will be replaced - Only available for flows in 'draft' status # Update flow definition Source: https://docs.flows.super.ai/api-reference/flows/update-flow-definition /openapi/superai-flows-openapi.json put /api/flows/{flow_id}/definition Update the complete definition of a flow. Replaces the entire flow definition with a new one. This operation is only allowed for flows in 'draft' status. Creates a new version of the flow. ## Restrictions - Only flows with status 'draft' can be updated - Published flows cannot be modified - A new version is created with each update ## Validation - New definition is validated before applying - If validation fails, the original definition remains unchanged - Use `include_validation_errors=true` to see validation details # Update version metadata Source: https://docs.flows.super.ai/api-reference/flows/update-version-metadata /openapi/superai-flows-openapi.json patch /api/flows/{flow_id}/versions/{version} # Upsert team (worker group) invitations to a flow Source: https://docs.flows.super.ai/api-reference/flows/upsert-team-worker-group-invitations-to-a-flow /openapi/superai-flows-openapi.json put /api/flows/{flow_id}/team-invitations Invite one or more worker groups (teams) to a flow. Every current member of the referenced team gains flow visibility via the RLS join on `worker_group_members` — no per-member rows are written, so membership changes propagate automatically. # Upsert user invitations to a flow Source: https://docs.flows.super.ai/api-reference/flows/upsert-user-invitations-to-a-flow /openapi/superai-flows-openapi.json put /api/flows/{flow_id}/invitations Upsert invitations for multiple users to access a flow. This endpoint allows admins to invite worker users to specific flows. Only users with the **worker role** will be invited - other users are automatically filtered out. Invited users will be able to access the flow and its executions through the RLS policies enforced at the database level. ## Permissions - Only org_admin role can create/update invitations - Users must belong to the same organization as the flow ## Behavior - **Upsert semantics**: Creates new invitations or updates existing ones - **Role filtering**: Only users with worker role are invited (others are skipped) - If a user_id doesn't have worker role, it's silently skipped - Returns both invited user IDs and skipped user IDs - All operations are performed in a single transaction ## Use Cases - Grant worker access to specific flows - Update existing invitations (refresh updated_at timestamp) - Manage flow-level permissions for review workflows - Enable selective flow visibility for team members ## Example If you send user_ids: [user1, user2, user3, user4] and only user1, user2, user3 have worker role: - Response will show invited_user_ids: [user1, user2, user3] - Response will show skipped_user_ids: [user4] # Validate a flow definition without persisting Source: https://docs.flows.super.ai/api-reference/flows/validate-a-flow-definition-without-persisting /openapi/superai-flows-openapi.json post /api/flows/{flow_id}/validate Validate a flow definition without persisting anything. Runs DSL validation and returns validation errors and ordered task names. Used for real-time validation feedback during editing. # Complete a human review task Source: https://docs.flows.super.ai/api-reference/human-review-tasks/complete-a-human-review-task /openapi/superai-flows-openapi.json post /api/human-review-tasks/{task_id}/complete Complete a human review task with validated output. Marks the task as completed and records the review results. This endpoint: - Validates reviewed_output against target task's output model - Updates task status to 'completed' - Records the review result (correct/incorrect) and reviewed output - Sets completed_by and completed_at fields - Removes the in-progress record for the user - Returns 404 if task not found - Returns 400 if the task is not in progress (already completed, or the claim was lost to an unstart or the review timeout), or validation fails - Returns 409 `review_task_reexecuted` if a re-run cancelled the review (the answer belongs to a run that no longer exists and must be given again on the new run) Context: - Only authenticated users can complete tasks - Task must be in 'in_progress' status - Records who completed the task and when - Automatically removes in-progress tracking - Output is validated against the target task's schema Use Cases: - User finishes reviewing a task and submits their results - Record validation outcomes for data quality tracking - Complete workflow steps requiring human judgment Related Endpoints: - POST /human-review-tasks/{task_id}/start - Start working on a task - GET /human-review-tasks - List all assigned tasks # Create a new human review task Source: https://docs.flows.super.ai/api-reference/human-review-tasks/create-a-new-human-review-task /openapi/superai-flows-openapi.json post /api/human-review-tasks Create a new human review task with assigned users. Creates a new human review task and assigns it to the specified users. Both the task and assignments are created in a single transaction. Context: - The task is created with the provided flow and execution information - All assigned users are linked to the task via assignments - Organization ID is automatically set from the current user's context Use Cases: - Create a review task for a flow execution - Assign multiple reviewers to a task - Track human review workflow state Related Endpoints: - GET /human-review-tasks - List all tasks - GET /human-review-tasks/{id} - Get task details # Get a human review task by ID Source: https://docs.flows.super.ai/api-reference/human-review-tasks/get-a-human-review-task-by-id /openapi/superai-flows-openapi.json get /api/human-review-tasks/{task_id} Get a human review task by its ID. Returns the details of a specific human review task, including its status, instructions, review results, and completion information. Context: - Returns the full task details for the specified task ID - Excludes soft-deleted tasks - Authorization is handled by RLS policies (user must have access to the organization) - Returns 404 if the task does not exist Use Cases: - View detailed information about a specific review task - Display task details in a task management UI - Check task status and review results - Access task instructions and completion information Related Endpoints: - GET /human-review-tasks - List all tasks assigned to current user - GET /human-review-tasks/{task_id}/assignments - List all assignments for a task - POST /human-review-tasks/{task_id}/start - Start working on a task - POST /human-review-tasks/{task_id}/complete - Complete a task # List all assignments for a human review task Source: https://docs.flows.super.ai/api-reference/human-review-tasks/list-all-assignments-for-a-human-review-task /openapi/superai-flows-openapi.json get /api/human-review-tasks/{task_id}/assignments List all assignments for a human review task. Returns a list of all assignments (user assignments) for the specified human review task. This includes all users who have been assigned to review the task, along with their assignment status and when they started working on it. Context: - Returns all assignments for the specified task - Includes assignment status (pending, in_progress, completed, cancelled) - Includes started_at timestamp for assignments that have been started - Only accessible if the task exists and user has access to the organization Use Cases: - View all reviewers assigned to a task - Track which reviewers have started or completed their review - Monitor assignment status across all reviewers - Display assignment information in task management UI Related Endpoints: - GET /human-review-tasks - List all tasks assigned to current user - POST /human-review-tasks/{task_id}/start - Start working on a task - POST /human-review-tasks/{task_id}/complete - Complete a task # List human review tasks assigned to the current user Source: https://docs.flows.super.ai/api-reference/human-review-tasks/list-human-review-tasks-assigned-to-the-current-user /openapi/superai-flows-openapi.json get /api/human-review-tasks List all human review tasks assigned to the current user. Returns a paginated list of human review tasks that have been assigned to the currently authenticated user. Tasks are joined with assignments to filter by user. Context: - Returns only tasks assigned to the current user - Excludes soft-deleted tasks - Results are paginated using offset and limit - Tasks can be filtered by one or more statuses (optional, comma-separated) - Tasks can be filtered by source task name (optional) - Tasks can be filtered by flow execution ID (optional) - Tasks can be filtered by flow ID stored in task_metadata (optional) - Tasks can be filtered by tags, connected by `tags_mode` — ANY of them (default) or ALL of them, matched at run level so the tags may sit on different tasks (optional) - Tasks can be excluded by tags via `tags_exclude`, which drops a run when any of its tasks carries one of those tags (optional) - Tasks can be filtered by metadata key-value pairs (optional, AND between groups, OR within) - Tasks can be sorted by created_at, updated_at, source_task_title or run_created_at (optional). `source_task_title` groups items sharing a Source Task Name; within each group items are ordered oldest-first by created_at regardless of sort_direction. `run_created_at` orders by the run's creation date, which a re-run leaves untouched. Use Cases: - Display user's assigned review tasks in a dashboard - Show pending reviews for the current user - Filter tasks by status (e.g., only show pending tasks) - Filter tasks by multiple statuses (e.g., 'pending,in_progress') - Filter tasks by source task name or flow execution - Filter tasks by tags or metadata for targeted task discovery - Narrow to runs carrying every one of several tags (`tags_mode=all`), or drop runs carrying an unwanted tag (`tags_exclude`) - Sort tasks by creation or update time - Track review task assignments Related Endpoints: - POST /human-review-tasks - Create a new review task - GET /human-review-tasks/{id} - Get specific task details # List human review tasks for a flow execution (org-level access) Source: https://docs.flows.super.ai/api-reference/human-review-tasks/list-human-review-tasks-for-a-flow-execution-org-level-access /openapi/superai-flows-openapi.json get /api/human-review-tasks/by-execution List human review tasks for a flow execution without user-assignment filtering. Returns all non-deleted HITL tasks for the given flow execution, regardless of which user they are assigned to. Requires org membership (get_user_info). Intended for admin/observer use-cases such as viewing a completed HITL task. Supplying both source filters narrows the result to the single task identified by (flow_execution_id, source_task_name, source_task_execution_idx) — the natural key of a HITL task. This is what lets an external system deep-link a reviewer straight to a review task using only data it already holds (FLO-2696); the task's own id is never exposed outside the platform. Context: - Both source filters must be given together, or neither (400 otherwise) - Excludes soft-deleted tasks - Authorization is handled by RLS policies (user must have access to the organization) Related Endpoints: - GET /human-review-tasks/{task_id} - Get a single task once its id is known - GET /human-review-tasks - List tasks assigned to the current user # Start a human review task Source: https://docs.flows.super.ai/api-reference/human-review-tasks/start-a-human-review-task /openapi/superai-flows-openapi.json post /api/human-review-tasks/{task_id}/start Start a human review task. Marks the task as in progress for the current user. This endpoint: - Creates an in-progress record linking the user to the task - Changes task status from 'pending' to 'in_progress' (if it's pending) - Returns 409 if the task is already completed - Can be called multiple times for the same user (idempotent) - Creates a timeout schedule to automatically unstart the task if it remains IN_PROGRESS beyond the configured timeout Context: - Only authenticated users can start tasks - Updates assignment status to 'in_progress' and sets started_at timestamp - Updates task status if currently pending - Organization ID is automatically set from the current user's context Use Cases: - User begins working on an assigned review task - Track which users are currently working on which tasks - Prevent starting already completed tasks Related Endpoints: - GET /human-review-tasks - List all assigned tasks - POST /human-review-tasks - Create a new review task # Unstart a human review task assignment Source: https://docs.flows.super.ai/api-reference/human-review-tasks/unstart-a-human-review-task-assignment /openapi/superai-flows-openapi.json post /api/human-review-tasks/{task_id}/unstart Unstart a human review task assignment. Resets an in_progress assignment back to pending status. This allows users to temporarily leave the review page and potentially return later to continue their review. Only valid for assignments with status 'in_progress'. Attempting to unstart an assignment with any other status will result in a 409 Conflict error. Context: - Only authenticated users can unstart their assignments - Only affects assignments with status 'in_progress' - Resets assignment status back to 'pending' (opposite of /start) - Task status remains unchanged - Organization ID is automatically set from the current user's context Use Cases: - User needs to temporarily leave the review page - User wants to pause their review and continue later - Browser/page navigation that should save progress but not complete Related Endpoints: - POST /human-review-tasks/{task_id}/start - Start working on a task - POST /human-review-tasks/{task_id}/complete - Complete a task - GET /human-review-tasks - List all assigned tasks # Compare Csv For Replace Source: https://docs.flows.super.ai/api-reference/integrations/compare-csv-for-replace /openapi/superai-flows-openapi.json post /api/integrations/database/{db_id}/upload/compare Compare existing CSV with new CSV for replace operation. # Complete File Upload Source: https://docs.flows.super.ai/api-reference/integrations/complete-file-upload /openapi/superai-flows-openapi.json post /api/integrations/database/{db_id}/upload/complete Complete file upload and process the file. # Create Database Source: https://docs.flows.super.ai/api-reference/integrations/create-database /openapi/superai-flows-openapi.json post /api/integrations/database Create a new CSV database instance. # Create Email Task Source: https://docs.flows.super.ai/api-reference/integrations/create-email-task /openapi/superai-flows-openapi.json post /api/integrations/email/tasks Create a new email task with a unique email address. # Create integration credentials Source: https://docs.flows.super.ai/api-reference/integrations/create-integration-credentials /openapi/superai-flows-openapi.json post /api/integrations/credentials Create new integration credentials for connecting to external services. Stores encrypted credentials for connecting to third-party services like Google Drive, SharePoint, SFTP servers, or PostgreSQL databases. Credentials are encrypted at rest using AES-256-GCM and scoped to the user's organization for security isolation. Context: This endpoint is the primary mechanism for establishing connections to external integrations. After credentials are created, they can be used in: - Flow tasks that require external data sources (file inputs, database queries) - Webhook subscriptions for real-time data synchronization - Batch data imports from cloud storage providers - Database query operations within workflow executions - OAuth-based integrations (after completing OAuth flow first) Credentials are never stored in plaintext and cannot be retrieved after creation. For OAuth providers (Google, SharePoint), complete the authorization flow first, then the callback handler automatically creates credentials. Use Cases: Create SFTP credentials for connecting to a file server to download CSV files in a workflow. Store PostgreSQL database credentials to enable SQL query tasks in flows. After testing connection with POST /integrations/sftp/test-connection, create permanent credentials. Related Endpoints: - POST /integrations/sftp/test-connection - Test SFTP credentials before saving - POST /integrations/postgres/test-connection - Test PostgreSQL credentials before saving - GET /integrations/google/authorize - Initiate Google OAuth flow - GET /integrations/sharepoint/authorize - Initiate SharePoint OAuth flow - GET /integrations/credentials - List all user credentials - GET /integrations/credentials/{credential_id} - Get specific credential metadata - DELETE /integrations/credentials/{credential_id} - Delete credential - PATCH /integrations/credentials/{credential_id} - Update credential Security: - Credentials are encrypted using Fernet (AES-256-GCM) before database storage - Encryption keys are managed via environment variables and never exposed via API - Passwords, private keys, and tokens are never logged or included in API responses - Credentials are scoped to organization with strict isolation enforced at query level - OAuth tokens are automatically refreshed when expired (no user action required) - Audit trail: Created timestamps and user associations tracked for compliance Notes: - Always test credentials before creating them (use test-connection endpoints) - OAuth credentials require completing the OAuth authorization flow first - Maximum 50 credentials per provider per organization (contact support for higher limits) - Credentials cannot be retrieved in plaintext after creation (security by design) - For SFTP key_file authentication, ensure private key is in valid PEM format - PostgreSQL connection_string takes precedence over individual connection fields # Create managed database Source: https://docs.flows.super.ai/api-reference/integrations/create-managed-database /openapi/superai-flows-openapi.json post /api/integrations/database/managed Create a managed PostgreSQL database for the organization. Creates a dedicated database on the customer Cloud SQL instance with: - Database name: tenant_{org_id} - Role: tenant_{org_id}_rw with ALL PRIVILEGES - app_admin user can CONNECT and SET ROLE to access the database Only one managed database per organization is allowed. Use Cases: - Create isolated database for organization data - Store structured data with SQL queries - Enable multi-tenant data isolation # Create table in managed database Source: https://docs.flows.super.ai/api-reference/integrations/create-table-in-managed-database /openapi/superai-flows-openapi.json post /api/integrations/database/managed/tables Create a new table in a managed database. Creates a table with specified columns using tenant_admin credentials. Uses organization_id from user context to identify the database. Use Cases: - Add new tables to managed database - Define custom schema for organization data # Deactivate Email Task Source: https://docs.flows.super.ai/api-reference/integrations/deactivate-email-task /openapi/superai-flows-openapi.json delete /api/integrations/email/tasks Deactivate the email integration for a removed task. Called when a receive_email task is removed from a flow definition. # Delete credential Source: https://docs.flows.super.ai/api-reference/integrations/delete-credential /openapi/superai-flows-openapi.json delete /api/integrations/credentials/{credential_id} Soft-delete an integration credential. Marks the credential as deleted without physically removing it from the database. Deleted credentials are excluded from list queries and cannot be used in workflows. Context: This endpoint safely removes credentials while preserving audit trail. Common scenarios: - User disconnects an integration from settings UI - Credential compromise detected (delete and recreate) - Integration no longer needed for workflows - OAuth token revoked by provider Soft deletion allows recovery if needed and maintains historical records for compliance. Use Cases: User clicks "Disconnect" button for SharePoint integration in settings UI. Remove compromised SFTP credentials before creating new ones with rotated password. Clean up unused credentials to reduce organization's attack surface. Related Endpoints: - GET /integrations/credentials - List active credentials (excludes deleted) - GET /integrations/credentials/{credential_id} - Verify credential before deletion - POST /integrations/credentials - Create new credential to replace deleted one Security: - Soft deletion preserves audit trail for compliance - Encrypted credential data remains in database but inaccessible - Consider automatic credential rotation policies for sensitive environments - Deleted credentials cannot be restored via API (database admin required) Notes: - Deletion is immediate and cannot be undone via API - Workflows using this credential will fail after deletion - Check for dependent workflows before deleting credentials - OAuth tokens are not revoked at provider (user must revoke separately) # Delete database Source: https://docs.flows.super.ai/api-reference/integrations/delete-database /openapi/superai-flows-openapi.json delete /api/integrations/database/{db_id} Delete a database integration. Removes the database integration and its associated CSV file from storage. This operation may affect workflows that reference this database. Permissions enforced at RLS level: - Admins can delete any database within their organization. - Non-admin users can only delete databases they uploaded themselves. # Execute Postgres Plugin Task Source: https://docs.flows.super.ai/api-reference/integrations/execute-postgres-plugin-task /openapi/superai-flows-openapi.json post /api/integrations/plugins/postgres/execute Execute PostgreSQL task using the new plugin system. # Generate database upload URL Source: https://docs.flows.super.ai/api-reference/integrations/generate-database-upload-url /openapi/superai-flows-openapi.json post /api/integrations/database/{db_id}/upload-url Generate a pre-signed URL for uploading files to a database. Creates a temporary upload URL that allows direct file uploads to cloud storage without routing data through the API server. The URL expires after 1 hour. The target database must belong to the caller's organization — a database owned by another org returns 404 without signing anything. This is the first step in the multi-step upload workflow: 1. Generate upload URL (this endpoint) 2. Upload file directly to cloud storage using the URL 3. Preview uploaded file (optional) 4. Complete upload and process file Use Cases: - Upload CSV files for data import - Upload large datasets efficiently - Batch data ingestion Security: - URL expires after 1 hour - File is uploaded to user-specific path - Metadata includes database ID for tracking # Get credential by ID Source: https://docs.flows.super.ai/api-reference/integrations/get-credential-by-id /openapi/superai-flows-openapi.json get /api/integrations/credentials/{credential_id} Retrieve metadata for a specific integration credential. Returns credential metadata without sensitive data. Use this endpoint to check credential status, provider type, and creation date without exposing passwords or tokens. Context: This endpoint provides safe access to credential information for UI display and validation purposes. Common use cases include: - Displaying credential details in integration settings pages - Verifying credential ownership before performing operations - Checking credential type before initiating provider-specific workflows - Validating credential exists before attempting to use it in tasks Use Cases: Verify credential exists and belongs to current user before displaying integration UI. Check credential type to determine which configuration UI to show (password vs OAuth). Display credential creation date in integration settings for audit purposes. Related Endpoints: - GET /integrations/credentials - List all user credentials - GET /integrations/credentials/{credential_id}/credentials - Get credential secrets (service accounts only) - PATCH /integrations/credentials/{credential_id} - Update credential - DELETE /integrations/credentials/{credential_id} - Delete credential Notes: - This endpoint is safe for UI use (no sensitive data exposure) - Soft-deleted credentials return 404 - OAuth credentials include token expiration metadata # Get credential secrets Source: https://docs.flows.super.ai/api-reference/integrations/get-credential-secrets /openapi/superai-flows-openapi.json get /api/integrations/credentials/{credential_id}/credentials Retrieve decrypted credential secrets for integration use. Returns the actual credential data (passwords, tokens, keys) in decrypted form. This endpoint is restricted to service accounts only for security. Regular users cannot retrieve plaintext credentials after creation. Context: This endpoint provides access to sensitive credential data for system-level operations. It is primarily used by: - Service accounts executing workflows that need integration credentials - Internal services performing integration health checks - System processes that need to establish external connections - Automated credential rotation and renewal workflows Regular user accounts cannot access this endpoint to prevent credential exposure. Use Cases: Service account retrieves SFTP credentials to execute file download task in workflow. Internal health check service validates PostgreSQL credential by attempting connection. Automated token refresh service retrieves OAuth refresh_token for renewal. Related Endpoints: - GET /integrations/credentials - List credentials (metadata only, no secrets) - POST /integrations/credentials - Create new credential - PATCH /integrations/credentials/{credential_id} - Update credential Security: - Service accounts only - regular users cannot retrieve plaintext credentials - Credentials are decrypted in-memory only (never logged or persisted unencrypted) - Organization isolation enforced at query level - Audit logging recommended for production use - Consider rotating credentials if this endpoint is compromised Notes: - This endpoint is intended for internal system use, not direct customer API calls - Sensitive data should be handled securely and never exposed in logs or responses - OAuth tokens are automatically refreshed if expired before returning # Get database by ID Source: https://docs.flows.super.ai/api-reference/integrations/get-database-by-id /openapi/superai-flows-openapi.json get /api/integrations/database/{db_id} Retrieve detailed information for a specific database. Returns complete database configuration including: - Database metadata (name, description, status) - File information (location, size) - Schema details (row count, column count) - Timestamps and audit information Use Cases: - Display database details in UI - Validate database exists before operations - Retrieve configuration for workflow tasks # Get database columns Source: https://docs.flows.super.ai/api-reference/integrations/get-database-columns /openapi/superai-flows-openapi.json get /api/integrations/database/{db_id}/columns Retrieve column names from a specific database. Returns the list of columns available in the database, useful for: - Building query interfaces - Configuring data mappings - Validating field references in workflows Use Cases: - Display available columns in query builder - Configure column mappings for data transformation - Validate workflow field references # Get Download Url Source: https://docs.flows.super.ai/api-reference/integrations/get-download-url /openapi/superai-flows-openapi.json get /api/integrations/database/{db_id}/download Generate pre-signed URL for downloading the database CSV file. # Get Email Task Status Source: https://docs.flows.super.ai/api-reference/integrations/get-email-task-status /openapi/superai-flows-openapi.json get /api/integrations/email/tasks/{task_id} Get status of an email task. # Get plugin capabilities Source: https://docs.flows.super.ai/api-reference/integrations/get-plugin-capabilities /openapi/superai-flows-openapi.json get /api/integrations/plugins/{plugin_name}/capabilities Retrieve detailed capabilities of a specific plugin. Returns comprehensive information about what the plugin can do, including: - Supported operations and execution models - Required authentication types - Configuration schema and metadata - Webhook support status Use Cases: - Display plugin configuration UI - Validate plugin compatibility with workflow - Generate plugin documentation # Get table columns from managed database Source: https://docs.flows.super.ai/api-reference/integrations/get-table-columns-from-managed-database /openapi/superai-flows-openapi.json get /api/integrations/database/managed/tables/{table_name}/columns Get column definitions from a table in a managed database. Returns column names and types for foreign key reference selection. Use Cases: - Display available columns for foreign key selection - Validate foreign key references # Get table data from managed database Source: https://docs.flows.super.ai/api-reference/integrations/get-table-data-from-managed-database /openapi/superai-flows-openapi.json get /api/integrations/database/managed/tables/{table_name}/data Get all data from a table in a managed database. Uses app_admin with SET ROLE to fetch data with read-only access. Uses organization_id from user context to identify the database. Use Cases: - Display table contents in schema management UI - View organization data # Insert one row into a managed-DB table Source: https://docs.flows.super.ai/api-reference/integrations/insert-one-row-into-a-managed-db-table /openapi/superai-flows-openapi.json post /api/integrations/database/managed/tables/{table_name}/rows Insert a single row into a managed-DB table and return the inserted row. Column names in `values` must match the table schema. Values are bound via parameterised SQL. # List all registered plugins Source: https://docs.flows.super.ai/api-reference/integrations/list-all-registered-plugins /openapi/superai-flows-openapi.json get /api/integrations/plugins/ List all registered plugins from the integration registry. Returns plugins available in the new plugin system only, excluding legacy integrations. Each plugin includes metadata about its capabilities, version, and status. Use Cases: - Display available integrations to users - Validate plugin availability before configuration - Integration discovery and selection # List credentials by provider Source: https://docs.flows.super.ai/api-reference/integrations/list-credentials-by-provider /openapi/superai-flows-openapi.json get /api/integrations/credentials/provider/{provider} Retrieve user credentials filtered by integration provider. Returns credentials for a specific integration provider. This is useful when you need to find credentials for a particular service without fetching all credentials. Context: This endpoint provides filtered access to credentials, commonly used when: - Checking if a user has connected to a specific provider (e.g., SharePoint) - Populating provider-specific integration configuration UI - Validating credential availability before initiating provider-specific workflows - Building provider selection dropdowns with availability indicators Use Cases: Check if user has SharePoint credentials before showing SharePoint site picker. Filter credentials for Google provider to display connected Google accounts in UI. Validate SFTP credential availability before configuring file upload task. Related Endpoints: - GET /integrations/credentials - Get all credentials (unfiltered) - POST /integrations/credentials - Create new credential for a provider - GET /integrations/catalog - List all available providers Notes: - Provider names are case-insensitive but lowercase is recommended - Multiple credentials per provider are supported (e.g., multiple SFTP servers) - Soft-deleted credentials are excluded from results # List integration catalog Source: https://docs.flows.super.ai/api-reference/integrations/list-integration-catalog /openapi/superai-flows-openapi.json get /api/integrations/catalog Retrieve the catalog of available third-party integrations. Returns a comprehensive list of all integration providers supported by SuperAI Flows. Each integration includes metadata about authentication requirements, capabilities, and categorization to help users discover and connect external services to their workflows. Context: - The integration catalog is the primary discovery mechanism for available services - Dynamically generated from the plugin registry (no database storage overhead) - All authenticated users can access the catalog - Automatically excludes credentialless integrations and integrations in migration Integration Categories: - **database**: PostgreSQL, internal PostgreSQL database connectors - **storage**: SharePoint document libraries, SFTP file servers - **messaging**: AWS SES email integration - **automation**: Various task executors and workflow automation tools Authentication Methods: - **oauth2**: OAuth 2.0 authorization flow (Google, SharePoint, Microsoft) - **user_password**: Username/password authentication (SFTP, PostgreSQL) - **api_key**: API key-based authentication - **key_file**: SSH key-based authentication (SFTP) Use Cases: - Display available integrations in UI marketplace - Show available connectors during flow task configuration - Validate provider support before connection attempts - Determine authentication requirements before OAuth flows - Populate provider selection dropdowns Related Endpoints: - GET /integrations/plugins - List detailed plugin metadata - GET /integrations/plugins/{plugin_name}/capabilities - Get plugin capabilities - POST /integrations/credentials - Create credentials for integration - GET /integrations/credentials - List user's configured credentials Notes: - OAuth integrations require additional authorize/callback flow - Integration availability ≠ user has configured credentials - Plugin system allows custom integrations without code changes - Use GET /integrations/credentials to check user's connections # List tables in managed database Source: https://docs.flows.super.ai/api-reference/integrations/list-tables-in-managed-database /openapi/superai-flows-openapi.json get /api/integrations/database/managed/tables List all tables in a managed database with row counts. Returns table names and their row counts for schema management. Uses organization_id from user context to identify the database. Use Cases: - Display available tables in schema management UI - Monitor table sizes # List user credentials Source: https://docs.flows.super.ai/api-reference/integrations/list-user-credentials /openapi/superai-flows-openapi.json get /api/integrations/credentials Retrieve all integration credentials for the authenticated user. Returns stored credentials for various integration providers including Google Drive, SharePoint, SFTP servers, PostgreSQL databases, and other external services. Each credential contains metadata about the integration but excludes sensitive authentication data (passwords, tokens, API keys) by default. Context: - Credentials are scoped to the authenticated user and their organization - Returns only active (non-deleted) credentials - Ordered by creation date (newest first) - OAuth credentials with expired tokens are still returned - Maximum 100 credentials per user - Credentials are encrypted at rest using AES-256-GCM Use Cases: - Display available integrations in the UI integration dashboard - Check which external services the user has already connected - Retrieve credential IDs for making integration-specific API calls - Audit credential creation dates and verify active connections - Support integration selection workflows in flow configuration Related Endpoints: - POST /integrations/credentials - Create new integration credential - GET /integrations/credentials/{credential_id} - Get specific credential details - GET /integrations/credentials/provider/{provider} - Filter credentials by provider - GET /integrations/credentials/{credential_id}/credentials - Get credential secrets - DELETE /integrations/credentials/{credential_id} - Delete credential Security Notes: - Sensitive data (passwords, tokens, keys) excluded from response - Use GET /integrations/credentials/{id}/credentials to retrieve sensitive data - Cross-organization access not permitted # List user databases Source: https://docs.flows.super.ai/api-reference/integrations/list-user-databases /openapi/superai-flows-openapi.json get /api/integrations/database List all databases accessible to the authenticated user. Returns all databases, including: - Database metadata and configuration - Row and column counts - Creation and update timestamps - Current status Use Cases: - Display databases in UI - Select database for workflow configuration - Monitor database integration status # Preview CSV file before import Source: https://docs.flows.super.ai/api-reference/integrations/preview-csv-file-before-import /openapi/superai-flows-openapi.json post /api/integrations/database/{db_id}/upload/preview Preview CSV file before final import. Shows the first 5 rows and file metadata to help users: - Verify correct file was uploaded - Confirm header row detection - Check delimiter parsing - Review column names - Validate data format This is step 3 in the upload workflow (optional): 1. Generate upload URL 2. Upload file to cloud storage 3. Preview file (this endpoint) 4. Complete upload and process Use Cases: - Verify file structure before import - Confirm CSV parsing settings - Preview data for validation # Process Emails Source: https://docs.flows.super.ai/api-reference/integrations/process-emails /openapi/superai-flows-openapi.json post /api/integrations/email/process Manually trigger email processing (for testing). # Query a managed-DB table with exact-match filters Source: https://docs.flows.super.ai/api-reference/integrations/query-a-managed-db-table-with-exact-match-filters /openapi/superai-flows-openapi.json post /api/integrations/database/managed/tables/{table_name}/query Run a parameterised SELECT against a managed-DB table. Supports a list of match clauses against columns. Each clause is either a 'whole' exact-match or a 'json_keys' match against keys inside a JSONB column. Clauses combine via `combinator` at the top level (AND or OR; defaults to AND). Returns rows ordered by `order_by` if provided, capped to `limit` (max 1000). The API surface is generic — ICL is the first consumer ("Write To Database" + ICL Retrieve tasks); future use cases reuse it without bespoke service methods. # Replace File Upload Source: https://docs.flows.super.ai/api-reference/integrations/replace-file-upload /openapi/superai-flows-openapi.json post /api/integrations/database/{db_id}/upload/replace Replace existing database data with new file upload. # Test Postgres Connection Source: https://docs.flows.super.ai/api-reference/integrations/test-postgres-connection /openapi/superai-flows-openapi.json post /api/integrations/postgres/test-connection Test PostgreSQL connection (proxied to legacy system). # Test Postgres Connection By Credential Id Source: https://docs.flows.super.ai/api-reference/integrations/test-postgres-connection-by-credential-id /openapi/superai-flows-openapi.json post /api/integrations/postgres/test-connection/{credential_id} Test PostgreSQL connection by credential ID (proxied to legacy system). # Test Postgres Plugin Connection Source: https://docs.flows.super.ai/api-reference/integrations/test-postgres-plugin-connection /openapi/superai-flows-openapi.json post /api/integrations/plugins/postgres/test-connection Test PostgreSQL connection using the new plugin system. # Test Sftp Connection Source: https://docs.flows.super.ai/api-reference/integrations/test-sftp-connection /openapi/superai-flows-openapi.json post /api/integrations/sftp/test-connection Test SFTP connection by attempting to connect and write a test file. # Update credential Source: https://docs.flows.super.ai/api-reference/integrations/update-credential /openapi/superai-flows-openapi.json patch /api/integrations/credentials/{credential_id} Update existing integration credentials with new values. Replaces credential data (passwords, tokens, connection details) for an existing credential. Use this endpoint to rotate passwords, update connection strings, or refresh OAuth tokens. Context: Credential updates are necessary for several operational scenarios: - Password rotation policies require periodic credential updates - SFTP server configuration changes (hostname, port) - Database connection string modifications - SSH key rotation for key-based authentication - OAuth token refresh (though typically handled automatically) Updates preserve credential_id, allowing workflows to continue using the same reference. Use Cases: Rotate SFTP password after security audit requires credential changes. Update PostgreSQL connection string after database server migration. Replace SSH private key after key compromise detected. Related Endpoints: - GET /integrations/credentials/{credential_id} - Get credential metadata before updating - POST /integrations/sftp/test-connection - Test new SFTP credentials before updating - POST /integrations/postgres/test-connection - Test new PostgreSQL credentials before updating - DELETE /integrations/credentials/{credential_id} - Delete credential instead of updating Security: - New credentials are encrypted before storage (same as creation) - Old credential data is overwritten (not preserved in database) - Audit trail tracks who performed the update via modified_by field - Test new credentials before updating to prevent workflow disruption Notes: - Always test new credentials before updating to avoid breaking workflows - Workflows using this credential will use new values immediately - OAuth credentials are typically auto-refreshed (manual update rarely needed) - Consider creating new credential instead of updating if provider changes # Overview Source: https://docs.flows.super.ai/api-reference/introduction The SuperAI Flows REST API — base URL, conventions, and how the reference is organized. The SuperAI Flows API is a unified REST API for defining, executing, and monitoring workflows. It combines the core workflow API and the AI agent API into a single coherent surface served from one domain. ## Base URL ``` https://flows.super.ai ``` | Surface | Path prefix | Purpose | | - | - | - | | Main API | `/api/*` | Flows, executions, tasks, integrations, files, auth | | Agent API | `/api/agent/*` | AI agent and conversation endpoints | ## Conventions The API follows Stripe-inspired design principles: * **RESTful endpoints** with intuitive, resource-oriented paths * **Standard HTTP methods** — `GET`, `POST`, `PATCH`, `DELETE` * **Standard HTTP status codes** for success and error handling * **Consistent JSON** request and response bodies * **`request_id` on every response** for log correlation and support ## Authentication Most endpoints require a JWT bearer token; some accept a service-account API key. See [Authentication](/api-reference/authentication) for the full flow. ```bash theme={null} curl https://flows.super.ai/api/flows \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ## Resource groups The endpoint reference in this section is generated directly from the OpenAPI specification and grouped by resource: Create, list, and manage workflow definitions. Run flows and monitor execution status. Inspect individual task runs and their results. Connect flows to external services and platforms. Download files referenced in task outputs. Manage programmatic API access credentials. ## Versioning & compatibility The API follows a strict compatibility policy. Non-breaking changes (new endpoints, optional parameters, new response fields, new enum values) ship without notice — design your clients to ignore unknown fields. Breaking changes are announced at least **15 days in advance** with migration guides. ## Errors All errors share a consistent JSON shape with a machine-readable `code` and a `request_id`. See the [Error Codes reference](/api-reference/errors). ```json theme={null} { "error": { "message": "Human-readable error description", "code": "machine_readable_error_code" }, "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8" } ``` # MCP Server Source: https://docs.flows.super.ai/api-reference/mcp-server Connect external AI agents and MCP-compatible clients to SuperAI Flows over the Model Context Protocol. The SuperAI Flows **MCP (Model Context Protocol) server** lets external AI agents and MCP-compatible clients work with SuperAI Flows programmatically — building and updating flows, starting and monitoring runs, reading task outputs, completing human reviews, and downloading files — without going through the UI. ## Overview The MCP server exposes the **public SuperAI Flows API** as MCP tools over the **Streamable HTTP** transport: every operation in the [API reference](/api-reference/introduction) is available as a tool, and nothing outside it. It's mounted at `/mcp` on the main API service and secured via the service-account API key system. | | | | - | - | | **Endpoint** | `https://flows.super.ai/mcp` (production) | | **Transport** | Streamable HTTP (POST), stateless | | **Authentication** | `X-API-Key` header with a valid service-account key | ## Authentication All MCP requests require a valid service-account API key passed via the `X-API-Key` header. 1. As an organization admin, open **Organization settings → Service accounts** from your profile menu in the SuperAI Flows UI. 2. Create a new service account or use an existing one. 3. Copy the API key (format: `saf_org_...`). Bearer token (`Authorization` header) authentication is **not supported** for MCP — use API keys only. ## Client configuration Add to `.mcp.json` in your project root: ```json theme={null} { "mcpServers": { "superai-flows": { "command": "npx", "args": [ "mcp-remote", "https://flows.super.ai/mcp", "--header", "X-API-Key:saf_org_..." ] } } } ``` Add `.mcp.json` to `.gitignore` if it contains API keys. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json theme={null} { "mcpServers": { "superai-flows": { "command": "npx", "args": [ "mcp-remote", "https://flows.super.ai/mcp", "--header", "X-API-Key:saf_org_..." ] } } } ``` Some MCP clients support the `url` + `headers` format directly: ```json theme={null} { "mcpServers": { "superai-flows": { "url": "https://flows.super.ai/mcp", "headers": { "X-API-Key": "saf_org_..." } } } } ``` To avoid hardcoding keys, use shell variable expansion — for example `"X-API-Key:${SAF_API_KEY}"`. ## Available tools Each operation of the public API is one MCP tool. A tool's name is the operation's `operationId` from the [OpenAPI specification](/api-reference/introduction), its input is the operation's path, query and body parameters, and it returns the same JSON the API returns. Your client lists the tools with `tools/list`. The tools follow the sections of the API reference: | Area | What the tools cover | Example tool | | - | - | - | | Flows | List, create, read, update and delete flows and their definitions | `get_flow_api_flows__flow_id__get` | | Task executors | Discover the task types you can build flows from | `get_task_executors_api_task_executors_get` | | Flow executions | Start, list, read, cancel, re-execute and delete runs | `create_flow_execution_api_flow_executions_post` | | Task executions and outputs | Read and update the results of each task in a run | `list_task_executions_api_task_executions_get` | | Human review tasks | List, read and complete review tasks | `complete_human_review_task_api_human_review_tasks__task_id__complete_post` | | Files | Resolve file references and download files | `download_file_api_files_download_get` | | Integrations and plugins | Manage credentials and integration instances | `get_integration_catalog_api_integrations_catalog_get` | | Organization and access | Service accounts, members, worker groups, SSO and your profile | `list_service_accounts_api_service_accounts_get` | What each tool may do follows the permissions of the service account behind the API key. ## Common workflows ```text theme={null} Build a new flow: get_task_executors_api_task_executors_get → create_flow_api_flows_post → get_flow_api_flows__flow_id__get (check validation) Run a flow and read its results: create_flow_execution_api_flow_executions_post → get_flow_execution_api_flow_executions__flow_execution_id__get → list_task_executions_api_task_executions_get Download a file: resolve_uri_api_files_resolve_post → download_file_api_files_download_get ``` ## Testing The MCP Inspector is the easiest way to debug: ```bash theme={null} npx @modelcontextprotocol/inspector ``` Connect to `https://flows.super.ai/mcp` with Streamable HTTP transport and add the `X-API-Key` header. Or check the endpoint with curl: ```bash theme={null} curl -X POST https://flows.super.ai/mcp \ -H "Content-Type: application/json" \ -H "X-API-Key: saf_org_..." \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` ## Limitations * **API key auth only** — JWT / bearer token authentication is not supported for MCP connections. * **Read/write scope** — The API key's permissions determine which flows are accessible. * **No streaming** — Tool responses are returned as complete JSON. * **Public API only** — Internal and admin-only endpoints are not exposed. If an operation isn't in the API reference, it isn't available as a tool. * **Stateless** — Each request is handled on its own, so there is no server-to-client notification stream (`GET /mcp` returns `405`). # List available models Source: https://docs.flows.super.ai/api-reference/models/list-available-models /openapi/superai-flows-openapi.json get /api/models Retrieve a list of available AI models, deduplicated by model name and optionally filtered by region. Each model entry aggregates information from all available endpoints: - **regions**: All regions where this model is deployed - **locations**: All specific locations (e.g., westeurope, eastus) - **providers**: All providers offering this model - **endpoint_count**: Total number of endpoints available Use the `region` parameter to filter models by deployment region: - `eu`: Only models with at least one EU endpoint - `global`: Only models with at least one global/US endpoint If no region is specified, all models are returned. # Add or remove members from a worker group Source: https://docs.flows.super.ai/api-reference/organizations/add-or-remove-members-from-a-worker-group /openapi/superai-flows-openapi.json post /api/organizations/worker-groups/{group_id}/members Add and/or remove members from a worker group in a single call. Users in add_user_ids that are already members are silently skipped. Users in remove_user_ids that are not members are silently ignored. # Claim an email domain for this organization Source: https://docs.flows.super.ai/api-reference/organizations/claim-an-email-domain-for-this-organization /openapi/superai-flows-openapi.json post /api/organizations/domains Claim a domain so its signups are routed to this organization (FLO-2811). Two refusals, both deliberate: - **400** for a domain nobody can own — a public mailbox provider, temp-mail service, school, or standards-reserved domain. Claiming gmail.com would divert every consumer signup on the platform. - **400** for a domain none of this organization's active admins use. Claiming a domain diverts other people's signups and discloses their email addresses to you, so it needs some proof of connection; an admin address on the domain is proof we already hold. Domains you own but have no admin on yet (a subsidiary, an acquisition) are added by support through the backoffice route. - **409** when another organization already claims it. The response never says which one — that would make this endpoint a "who is a customer of super.AI" lookup. Accepts a bare domain or a full address; both are normalised to the domain. # Create a worker group Source: https://docs.flows.super.ai/api-reference/organizations/create-a-worker-group /openapi/superai-flows-openapi.json post /api/organizations/worker-groups Create a new worker group in the current organization. # Decline a signup request Source: https://docs.flows.super.ai/api-reference/organizations/decline-a-signup-request /openapi/superai-flows-openapi.json post /api/organizations/join-requests/{request_id}/reject Decline a request without telling the requester. No email is sent. The person finds out only if they try to sign up again, which is deliberate — a decline is often "we don't know who that is", and an unsolicited rejection notice is worse than silence. Reversible in practice: adding the same person through the normal Add Member flow is not blocked by a declined request, and resolves it to approved. # Delete a worker group Source: https://docs.flows.super.ai/api-reference/organizations/delete-a-worker-group /openapi/superai-flows-openapi.json delete /api/organizations/worker-groups/{group_id} Soft-delete a worker group. Existing HITL task assignments are preserved. # Get a worker group Source: https://docs.flows.super.ai/api-reference/organizations/get-a-worker-group /openapi/superai-flows-openapi.json get /api/organizations/worker-groups/{group_id} Get details of a specific worker group including its members. # Get credit balance for current user's organization Source: https://docs.flows.super.ai/api-reference/organizations/get-credit-balance-for-current-users-organization /openapi/superai-flows-openapi.json get /api/organizations/credits Get credit balance for the current user's organization. Returns the current credit balance including grants, consumption, and remaining credits for the authenticated user's organization. Consumption is read from the credit_usage_summary materialized view, refreshed every 10 minutes. **Authorization**: - Organization admins and users can view their own organization's credits - RLS policies enforce organization-level data isolation at database level **Context**: - Credits are tracked at the organization level, not per user - Grants are permanent allocations (cannot be revoked) - Credits consumed track usage across all users in the organization **Use Cases**: - Display credit balance in user dashboard - Check remaining credits before starting workflows - Monitor organization usage **Related Endpoints**: - POST /admin/organizations/{id}/grants - Admin can grant additional credits (backoffice only) **Security**: - @require_roles decorator enforces role-based access - Uses current_user.organization_id (no path parameter to validate) - RLS policies provide database-level enforcement # Get organization by ID Source: https://docs.flows.super.ai/api-reference/organizations/get-organization-by-id /openapi/superai-flows-openapi.json get /api/organizations/{organization_id} Retrieve detailed information for a specific organization. Fetches complete metadata for a single organization using its unique identifier. Use this to verify organization existence, check active status, or retrieve organization details before performing related operations. Context: - Returns organization regardless of active/inactive status - Does not include user count or related entity counts - Organization ID must be a valid UUID Behavior: 1. Validates organization_id is valid UUID format 2. Queries database for organization by ID 3. Returns organization if found 4. Raises 404 error if organization does not exist Use Cases: - Retrieve organization details # List all worker groups Source: https://docs.flows.super.ai/api-reference/organizations/list-all-worker-groups /openapi/superai-flows-openapi.json get /api/organizations/worker-groups List all worker groups for the current organization (paginated). # List signups waiting on this organization's review Source: https://docs.flows.super.ai/api-reference/organizations/list-signups-waiting-on-this-organizations-review /openapi/superai-flows-openapi.json get /api/organizations/join-requests People whose signup was blocked because their email domain is yours (FLO-2811). Approving is not an operation here: an admin approves by adding the person through `POST /admin/organizations/{id}/users`, which resolves the matching request to `approved` as a side effect. That keeps one code path for "this person becomes a member" whether or not a request ever existed. # List the email domains this organization has claimed Source: https://docs.flows.super.ai/api-reference/organizations/list-the-email-domains-this-organization-has-claimed /openapi/superai-flows-openapi.json get /api/organizations/domains Which email domains route a self-service signup to this organization (FLO-2811). A signup whose address is on one of these domains is stopped before it can create its own free-tier organization, and shows up under `GET /organizations/join-requests` for an admin to act on instead. Two lists, but only one of them routes anything: - `claimed` — the domains this organization has claimed. These are the only domains that capture a signup, always. - `suggested` — claimable domains this organization's active admins use but has not claimed. Captures nothing; offered so an admin can claim their own domain in one click instead of retyping it. The organization is taken from the caller's token, never from a parameter. # Release a claimed email domain Source: https://docs.flows.super.ai/api-reference/organizations/release-a-claimed-email-domain /openapi/superai-flows-openapi.json delete /api/organizations/domains/{claim_id} Stop routing a domain's signups to this organization. A claim is the only thing that routes anything, so removing the last one turns capture off for this organization entirely — signups on that domain go back to getting their own free-tier organization. The admin domains this page suggests are suggestions only; they capture nothing on their own. # Update a worker group Source: https://docs.flows.super.ai/api-reference/organizations/update-a-worker-group /openapi/superai-flows-openapi.json put /api/organizations/worker-groups/{group_id} Update a worker group's name and/or description. # Update organization settings Source: https://docs.flows.super.ai/api-reference/organizations/update-organization-settings /openapi/superai-flows-openapi.json put /api/organizations/settings Update self-service organization settings. This endpoint replaces settings in the organization's settings JSONB column. Only admins can update settings. Uses JWT token to identify the organization. The request model (`SelfServiceOrganizationSettingsRequest`) exposes only the self-service fields and structurally OMITS backoffice-only ones (`max_concurrent_executions`, `payment_method`, `enabled_capabilities`, `account_state`) — those are settable exclusively via the `/admin/organizations/{id}/…` endpoints. Sending one is a 422 (extra fields forbidden), so an org admin cannot alter or clear a backoffice-imposed setting through this route. `account_state` matters most here (FLO-2652): without the omission an org admin could set their own stage to `promoted` and self-promote off the trial. FLO-2715 replaced the per-field 403 guards this endpoint used to carry with the narrow model, which covers `account_state` by construction rather than by remembering to add a guard for it. Configuration Options for worker_landing_page: - hub: Workers land on the Hub page - assigned_flow_data_tab: Workers land on their assigned flow's Data Tab - assigned_flow_work_tab: Workers land on their assigned flow's Work Tab Returns: Full organization object with updated settings Note: To retrieve settings, use the standard organization endpoint which includes settings in OrganizationResponse via RLS policies. # Why this account is restricted, if it is Source: https://docs.flows.super.ai/api-reference/organizations/why-this-account-is-restricted-if-it-is /openapi/superai-flows-openapi.json get /api/organizations/account-restriction The statement of reasons for a restricted account (FLO-2652, L9, L10). Under DSA Art. 17 a restriction notice must state the concrete facts, the exact clause relied on, whether automated means were used, and the redress route. "Your account was limited" is non-compliant. This endpoint serves that statement, and the suspension screen renders it. The same screen serves the demoted state: a demoted account sits at a negative balance and can do nothing, indefinitely, which is an account restriction whether or not a human decided it. **Scoped to the caller's own organization**, with no path parameter, for the same reason ``/credits`` is: this is a notice about you, and there is no version of it that is about somebody else. Served here rather than out of ``account_review`` because that table has no tenant read policy at all — a subject learns about the *review* from an operator answering a subject access request (L5). What comes back here is only what the person is entitled to be told, and it carries no model reasoning: no rationale, no confidence, no internal category. ``restricted: false`` for the overwhelmingly common case. A trial that has simply run out is deliberately **not** a restriction — it is a contractual default reaching its end, and putting an accusation in front of somebody who did nothing wrong would be worse than saying nothing. # Create Integration Source: https://docs.flows.super.ai/api-reference/plugins/create-integration /openapi/superai-flows-openapi.json post /api/plugins/{plugin_name}/instances # Delete Integration Source: https://docs.flows.super.ai/api-reference/plugins/delete-integration /openapi/superai-flows-openapi.json delete /api/plugins/{plugin_name}/instances/{integration_id} # Execute Integration Source: https://docs.flows.super.ai/api-reference/plugins/execute-integration /openapi/superai-flows-openapi.json post /api/plugins/{plugin_name}/instances/{integration_id}/execute # Get Ui Schema Source: https://docs.flows.super.ai/api-reference/plugins/get-ui-schema /openapi/superai-flows-openapi.json post /api/plugins/{plugin_name}/instances/{integration_id}/ui_schema # Handle Webhook Source: https://docs.flows.super.ai/api-reference/plugins/handle-webhook /openapi/superai-flows-openapi.json post /api/plugins/{plugin_name}/instances/{integration_id}/webhook/callback # List Instances Source: https://docs.flows.super.ai/api-reference/plugins/list-instances /openapi/superai-flows-openapi.json get /api/plugins/instances # List Integrations Source: https://docs.flows.super.ai/api-reference/plugins/list-integrations /openapi/superai-flows-openapi.json get /api/plugins/{plugin_name}/instances # Oauth Authorize Source: https://docs.flows.super.ai/api-reference/plugins/oauth-authorize /openapi/superai-flows-openapi.json post /api/plugins/{plugin_name}/oauth/authorize # Oauth Callback Source: https://docs.flows.super.ai/api-reference/plugins/oauth-callback /openapi/superai-flows-openapi.json get /api/plugins/{plugin_name}/{provider_name}/oauth/callback # Poll Integration Source: https://docs.flows.super.ai/api-reference/plugins/poll-integration /openapi/superai-flows-openapi.json post /api/plugins/{plugin_name}/instances/{integration_id}/poll Execute scheduled polling for polling integration plugins. This endpoint is called by the Temporal scheduled workflow to poll external systems for new data. It handles file uploads, flow execution creation, and cleanup. Runs under RLS (``@transactional``, not ``bypass_rls``): the scheduled caller's token carries the deploying user's org and an ``app_user``/``org_admin`` role, so the org-scoped policies on ``user_integrations``/``user_credentials`` resolve only this org's rows. Another org's ``integration_id`` therefore resolves to nothing and surfaces as a 404 — tenant isolation is enforced by the database, not a hand-rolled check (FLO-2449). # Update Integration Source: https://docs.flows.super.ai/api-reference/plugins/update-integration /openapi/superai-flows-openapi.json put /api/plugins/{plugin_name}/instances/{integration_id} # Change the authenticated user's password Source: https://docs.flows.super.ai/api-reference/profile/change-the-authenticated-users-password /openapi/superai-flows-openapi.json post /api/profile/password Verify the current password, then write the new one (FLO-2735 G-2). The verification is unconditional for an account that has a password, which is why this is a server endpoint and not a ``supabase.auth.updateUser`` call: GoTrue skips its own current-password check for any session whose AMR is ``otp``, ``magiclink`` or ``recovery``, and every email-link sign-in produces one. See the module docstring in ``password_service.py`` for the full reasoning, including what this does and does not protect against. The caller's bearer token is forwarded to GoTrue for the write itself so that session bookkeeping matches the direct client call this replaces: this device stays signed in, every other one is signed out. NOT used by ``/set-password`` (invited user) or ``/reset-password`` (recovery). Those hold a session minted seconds earlier by the emailed credential, have no current password to give, and keep calling Supabase directly. # Get current user profile Source: https://docs.flows.super.ai/api-reference/profile/get-current-user-profile /openapi/superai-flows-openapi.json get /api/profile/me Retrieve complete profile information for the currently authenticated user. Returns the full user profile including personal information, role, status, organization membership with organization name, AND landing page configuration for workers. Context: - Returns user regardless of active/inactive/pending status - Includes organization_id AND organization_name for multi-tenant access control - Organization name used by frontend to enable/disable features (e.g., "super-ai" org) - Landing page config included for worker roles (reviewers, publishers) - Profile data is read-only via this endpoint (use PATCH /profile/me to update) - User role determines API permissions across the platform Behavior: 1. Extracts user_id from authenticated user context 2. Calls UserService.get_profile() which handles: - User profile retrieval from database - Organization details retrieval - Landing page configuration (for workers only) 3. Returns complete user profile with landing page config 4. Raises 404 if user exists in auth system but not in database (rare edge case) Use Cases: - Display user name and email in application header - Check user role to show/hide UI features (org_admin, app_user, etc.) - Check organization name for feature gating (e.g., credits visible for "super-ai") - Verify user's organization for multi-tenant data filtering - Determine user status for account activation workflows - Fetch user details after authentication to initialize session - **NEW**: Determine landing page redirect for workers on login Related Endpoints: - PATCH /profile/me - Update current user's name - GET /admin/users/{user_id} - Admin endpoint to view any user - GET /admin/organizations/{org_id}/users - List users in organization - GET /organizations/{org_id}/credits - View organization credit balance # Grant or withdraw marketing consent Source: https://docs.flows.super.ai/api-reference/profile/grant-or-withdraw-marketing-consent /openapi/superai-flows-openapi.json post /api/profile/marketing-consent Set ``users.marketing_consent_at`` (FLO-2652). Withdrawal must be as easy as granting (Art. 7(3)), so both directions are the same one-field call from the same settings toggle — not a granting endpoint plus a support request. # Record the caller's acceptance of one or more documents Source: https://docs.flows.super.ai/api-reference/profile/record-the-callers-acceptance-of-one-or-more-documents /openapi/superai-flows-openapi.json post /api/profile/accept-terms Record an acceptance the caller performed deliberately (FLO-2652). Three surfaces share this endpoint, which is why it takes a list rather than doing one thing: * **Re-acceptance** after a material amendment (the blocking dialog). * **An invited member's first act**, on the set-password screen — the first screen where they act for themselves. The invitation endpoints are the *inviter's* admin calls; stamping acceptance there would record an admin's action as the invitee's assent and destroy the evidentiary value of the whole table. ``renewal_terms`` is deliberately NOT among them, despite being a documented use for the underlying service call. ``AcceptedDocument.document`` is a ``Literal[self_service_tos, privacy_policy]``, so a ``renewal_terms`` body is a 422 -- the same structural refusal that keeps ``immediate_performance`` off this endpoint, and for the same reason: both are written server-side by the surface that collected the act, and a client that could name them could forge a waiver against its own account. PR X records renewal terms through ``TermsComplianceService.record_acceptance`` from the checkout path, not through this endpoint. Only the version, IP and timestamp are trusted from the server side: the version the caller sends is *validated against* the published one and then discarded, never stored as given. A version we do not publish is a 400 — accepting one would put an arbitrary string in the formation record. Because the sent version is discarded either way, naming it is OPTIONAL: a caller that omits ``documents`` accepts every currently-published signup document at the server's versions. That is what the set-password screen does, and what any surface should do unless it genuinely knows what it rendered — naming a version it had to guess at is strictly worse than not naming one. ``transactional_bypass_rls`` because ``terms_acceptance`` grants only the backend connection user; the write is scoped to ``user_info.id`` in the handler, and no other user id can reach this call path. # Update current user profile Source: https://docs.flows.super.ai/api-reference/profile/update-current-user-profile /openapi/superai-flows-openapi.json patch /api/profile/me Update the currently authenticated user's profile information. Allows users to modify their personal information including first and last name. Only the fields provided in the request body will be updated. Omitted fields remain unchanged. The user is automatically identified from their authentication credentials. Context: - Only first_name and last_name can be updated via this endpoint - Password field in request body is reserved for future use (not implemented) - Email, role, status, and organization cannot be changed by users - Updates are immediate and reflected in database upon success - Full user profile returned in response with updated values Behavior: 1. Extracts user_id from authenticated user context 2. Validates request body fields (min/max length constraints) 3. Queries database to verify user exists 4. Updates only first_name and last_name if provided 5. Persists changes to database with updated_at timestamp 6. Returns complete updated user profile Use Cases: - User wants to correct misspelled name - User prefers different name display (nickname vs full name) - User changes last name after marriage or legal name change - Profile updates during onboarding or account setup - Internationalization of name display Field Update Rules: - first_name: 1-100 characters if provided, unchanged if null - last_name: 1-100 characters if provided, unchanged if null - password: Not currently implemented, reserved for future use - All other fields (email, role, status): Use admin endpoints to modify Related Endpoints: - GET /profile/me - Retrieve current user profile - PUT /admin/users/{user_id} - Admin endpoint to update any user - POST /auth/change-password - Change password (separate auth flow) # Whether this account has a password and whether it is SSO-managed Source: https://docs.flows.super.ai/api-reference/profile/whether-this-account-has-a-password-and-whether-it-is-sso-managed /openapi/superai-flows-openapi.json get /api/profile/credential-state Answer what the account-settings password form may render (FLO-2735 G-2). Strictly self-scoped: the auth id comes from the caller's own ``users`` row, never from a parameter, so this cannot be pointed at anybody else. That is what separates it from the email-keyed ``get_auth_signin_options_by_email`` sibling, whose public endpoint was retired precisely because a caller chose the address it answered for. Answers 503 when the state cannot be resolved, rather than guessing. An earlier version failed open to ``has_password=False``, which looked kinder and was worse: the form then renders "Set a Password" with no current-password field, the submit omits it, and ``POST /profile/password`` — which resolves the same fact from the same RPC — answers ``current_password_required``, whose copy asks the user to reload, straight back into the same failing lookup. The most likely trigger is the deploy window before this revision's RPC exists. An unknown state is a third outcome and the form renders a retry for it. # Create a new service account Source: https://docs.flows.super.ai/api-reference/service-accounts/create-a-new-service-account /openapi/superai-flows-openapi.json post /api/service-accounts Create a new service account. Creates a new service account and returns the full authentication token. **Important**: The full token is only shown once during creation. Store it securely. Context: - This API creates organization-scoped accounts only - Token format: saf_{type}_{org_prefix}_{account_id_prefix}_{random_part} Use Cases: - Create API integration accounts - Set up automated workflows - Enable programmatic access to platform resources Related Endpoints: - GET /service-accounts - List all accounts - GET /service-accounts/{id} - Get account details - PATCH /service-accounts/{id} - Update account # Create an API key for a service account Source: https://docs.flows.super.ai/api-reference/service-accounts/create-an-api-key-for-a-service-account /openapi/superai-flows-openapi.json post /api/service-accounts/{service_account_id}/api-keys Create a new API key for a specific service account. Creates a new API key associated with the specified service account and returns the full authentication token. **Important**: The full token is only shown once during creation. Store it securely. Context: - The user must have access to the service account - System accounts are not visible to API users due to RLS restrictions - All accessible service accounts are organization accounts - Uses 'organization_service_account' identity type Related Endpoints: - GET /service-accounts/{id}/api-keys - List API keys for a service account - GET /service-accounts/{id} - Get service account details # Delete a service account Source: https://docs.flows.super.ai/api-reference/service-accounts/delete-a-service-account /openapi/superai-flows-openapi.json delete /api/service-accounts/{service_account_id} Delete a service account. Permanently deletes a service account. This action cannot be undone. Context: - Hard delete (permanent removal) - Cannot be undone - Use deactivate if you want to temporarily disable access Related Endpoints: - POST /service-accounts/{id}/deactivate - Temporarily disable account # Delete an API key Source: https://docs.flows.super.ai/api-reference/service-accounts/delete-an-api-key /openapi/superai-flows-openapi.json delete /api/service-accounts/{service_account_id}/api-keys/{api_key_id} Soft delete an API key (sets deleted = True). Permanently deletes an API key. Any applications using this key will immediately lose access. Context: - Soft delete (sets deleted = True) - Applications using this key will lose access immediately - Cannot be undone Related Endpoints: - PATCH /service-accounts/{id}/api-keys/{key_id} - Update API key - GET /service-accounts/{id}/api-keys - List API keys for service account # Get a specific service account Source: https://docs.flows.super.ai/api-reference/service-accounts/get-a-specific-service-account /openapi/superai-flows-openapi.json get /api/service-accounts/{service_account_id} Get details for a specific service account. Returns service account information including status and token prefix. Note: Full token is never returned after creation. Context: - Users can only access accounts from their organization - System accounts are accessible to all users - Token prefix is shown for identification purposes Related Endpoints: - GET /service-accounts - List all accounts - PATCH /service-accounts/{id} - Update account # List all service accounts Source: https://docs.flows.super.ai/api-reference/service-accounts/list-all-service-accounts /openapi/superai-flows-openapi.json get /api/service-accounts List all service accounts accessible to the current user. Returns organization accounts for your organization plus all system accounts. Context: - Returns accounts from your organization - Includes all system accounts - Does not include accounts from other organizations Related Endpoints: - GET /service-accounts/{id} - Get specific account details - POST /service-accounts - Create new account # List API keys for a service account Source: https://docs.flows.super.ai/api-reference/service-accounts/list-api-keys-for-a-service-account /openapi/superai-flows-openapi.json get /api/service-accounts/{service_account_id}/api-keys List all API keys associated with a specific service account. Returns all API keys that belong to the specified service account. The user must have access to the service account to view its API keys. Context: - Only returns API keys for the specified service account - User must have access to the service account - Returns empty list if no API keys exist for the account Related Endpoints: - GET /service-accounts/{id} - Get service account details - POST /api-keys - Create a new API key # Update a service account Source: https://docs.flows.super.ai/api-reference/service-accounts/update-a-service-account /openapi/superai-flows-openapi.json patch /api/service-accounts/{service_account_id} Update a service account. Updates name and/or description of a service account. Status updates should use activate/deactivate endpoints. Context: - Can update name and description - Cannot update token (use delete + create for new token) - Cannot update status (use activate/deactivate endpoints) Related Endpoints: - POST /service-accounts/{id}/activate - Activate account - POST /service-accounts/{id}/deactivate - Deactivate account # Update an API key Source: https://docs.flows.super.ai/api-reference/service-accounts/update-an-api-key /openapi/superai-flows-openapi.json patch /api/service-accounts/{service_account_id}/api-keys/{api_key_id} Update an API key name and/or description. Updates the name and/or description of an API key. Note: Cannot update the token itself - delete and create a new key for that. Context: - Can update name and description only - Cannot update token (use delete + create for new token) - User must have access to the API key Related Endpoints: - DELETE /service-accounts/{id}/api-keys/{key_id} - Delete API key - GET /service-accounts/{id}/api-keys - List API keys for service account # Create SSO configuration for organization Source: https://docs.flows.super.ai/api-reference/sso/create-sso-configuration-for-organization /openapi/superai-flows-openapi.json post /api/sso Create SSO configuration for the current user's organization. Creates a new SAML SSO provider in Supabase and stores the configuration locally. This is a transactional operation that ensures both Supabase and local database are updated atomically. Context: - Only organization administrators can create SSO configurations - Each organization can have only one SSO configuration SAML Configuration: - Provide either metadata_url OR metadata_xml, not both - metadata_url: URL where Supabase can fetch SAML metadata - metadata_xml: Raw SAML metadata XML content - domains: Email domains that should authenticate via this provider - attribute_mapping: Maps SAML attributes to user profile fields Related Endpoints: - GET /auth/sso - Get current SSO configuration - PATCH /auth/sso - Update SSO metadata - DELETE /auth/sso - Remove SSO configuration # Get SSO configuration for organization Source: https://docs.flows.super.ai/api-reference/sso/get-sso-configuration-for-organization /openapi/superai-flows-openapi.json get /api/sso Get SSO configuration for the current user's organization. Returns the current SAML SSO configuration including domains, metadata settings, and attribute mappings. Context: - Returns SSO configuration for the authenticated user's organization - Includes both active and inactive configurations - Shows configuration stored in local database Response Data: - sso_provider_id: Supabase SSO provider identifier - domains: Email domains using this SSO provider - metadata_url: URL for SAML metadata (if configured) - attribute_mapping: SAML attribute to user field mappings - is_active: Whether the SSO provider is currently enabled Use Cases: - Reviewing current SSO configuration - Checking SSO status before updates - Auditing SSO provider settings Related Endpoints: - POST /auth/sso - Create SSO configuration - PATCH /auth/sso - Update SSO metadata # Get Supabase SAML service-provider URLs Source: https://docs.flows.super.ai/api-reference/sso/get-supabase-saml-service-provider-urls /openapi/superai-flows-openapi.json get /api/sso/service-provider-details Get the Supabase SAML service-provider (SP) URLs for IdP configuration. These URLs depend only on the Supabase project and are the same for every organization. They are available before any SSO configuration exists, so the setup UI can pre-fill the read-only SP fields the customer must copy into their Identity Provider. Response Data: - entity_id: SAML SP EntityID (same value as metadata_url) - metadata_url: SAML SP metadata URL - acs_url: Assertion Consumer Service (ACS) URL - slo_url: Single Logout (SLO) URL Related Endpoints: - POST /auth/sso - Create SSO configuration - GET /auth/sso - Get current SSO configuration # Proxy SAML metadata to avoid CORS issues Source: https://docs.flows.super.ai/api-reference/sso/proxy-saml-metadata-to-avoid-cors-issues /openapi/superai-flows-openapi.json get /api/sso/metadata Fetches SAML metadata from external URLs to avoid browser CORS restrictions # Remove SSO configuration for organization Source: https://docs.flows.super.ai/api-reference/sso/remove-sso-configuration-for-organization /openapi/superai-flows-openapi.json delete /api/sso Remove SSO configuration for the current user's organization. Disables the SSO configuration by setting is_active=False. This is a soft delete that preserves the configuration for potential future reactivation. Context: - Soft delete (sets is_active=False, preserves data) - Users will fall back to password authentication - Configuration can be reactivated by creating a new SSO config - Does not delete the Supabase SSO provider Impact: - Immediate: Users can no longer authenticate via SSO - Existing sessions may remain active until expiration - Users must use password authentication - Organization admins can recreate SSO configuration Security Considerations: - Disabling SSO immediately affects all users in configured domains - Ensure alternative authentication methods are available - Consider communication to affected users before disabling Use Cases: - Temporary SSO maintenance or troubleshooting - Migrating to a different SSO provider - Emergency access restoration via password auth - Decommissioning SSO integration Related Endpoints: - POST /auth/sso - Create new SSO configuration - GET /auth/sso - Check current configuration status # Update SSO metadata configuration Source: https://docs.flows.super.ai/api-reference/sso/update-sso-metadata-configuration /openapi/superai-flows-openapi.json patch /api/sso Update SSO metadata configuration for the current user's organization. Updates metadata-related fields only. This endpoint is restricted to updating: - metadata_url: URL for fetching SAML metadata - metadata_xml: Raw SAML metadata XML content - domains: Email domains that should use this SSO provider - attribute_mapping: SAML attribute to user profile field mappings Context: - Only metadata-related fields can be updated via this endpoint - Updates both Supabase SSO provider and local database - Changes are applied immediately - Cannot update provider ID or organization association Metadata Update Rules: - Provide either metadata_url OR metadata_xml, not both - Setting metadata_url clears any existing metadata_xml - Setting metadata_xml clears any existing metadata_url - Domains can be added, removed, or modified - Attribute mappings are completely replaced if provided Use Cases: - Updating SAML metadata after IdP changes - Adding or removing email domains - Modifying attribute mapping for user profiles - Rotating SAML certificates or endpoints Related Endpoints: - GET /auth/sso - Get current configuration - DELETE /auth/sso - Remove SSO configuration # Analyze flow definition and extract schemas Source: https://docs.flows.super.ai/api-reference/task-data/analyze-flow-definition-and-extract-schemas /openapi/superai-flows-openapi.json post /api/task-data Analyze a flow definition to extract task output schemas, dynamic data, and validation errors. **Overview** This endpoint validates a flow definition and returns metadata needed for flow building, execution planning, and UI generation. It processes all tasks in the flow definition to extract their output schemas (for type validation), dynamic configuration data (for UI dropdowns and conditional fields), and any structural or semantic validation errors. **Use Cases** - **Flow Builder UI**: Get task output schemas for downstream task input validation - **Dynamic Configuration**: Retrieve runtime-dependent options (e.g., available spreadsheets, databases) - **Flow Validation**: Check for errors before saving or executing a flow - **Schema Discovery**: Understand what data each task will produce - **Custom Integrations**: Programmatically validate and analyze flow definitions **How It Works** 1. Parses and validates the flow definition structure (basic validation) 2. For each task in the flow: - Loads the task executor implementation - Calls the executor's `get_output_model()` to get the output schema - Calls the executor's dynamic data methods (if available) to get runtime options - Collects any errors encountered during schema/data extraction 3. If `full_validation=true`, performs additional semantic validation (checks task parameter values, validates connections between tasks, etc.) 4. Returns all schemas, dynamic data, and validation errors in a single response **Dynamic Data Explained** Dynamic data represents configuration options that depend on external state or user credentials. For example: - Google Sheets task: List of spreadsheets accessible with user's credentials - Database task: List of available tables/columns - API task: Available endpoints or data models from connected service **Validation Levels** - **Basic (default)**: Structure validation only (required fields, data types) - **Full (`full_validation=true`)**: Includes semantic validation (valid references, parameter constraints, external resource availability) **Performance Notes** - May make external API calls to fetch dynamic data (e.g., Google Sheets API) - Response time varies based on number of tasks and external service latency - Typical response time: 100ms-2s depending on task executors used **Related Endpoints** - `POST /flows` - Create flow (uses this endpoint's validation internally) - `PUT /flows/{flow_id}` - Update flow (uses this endpoint's validation internally) - `GET /task-executors` - List available task executors # Create a task execution record Source: https://docs.flows.super.ai/api-reference/task-executions/create-a-task-execution-record /openapi/superai-flows-openapi.json post /api/task-executions Create a new task execution record for a specific task within a flow execution. **Overview** Task executions represent individual task invocations within a flow execution. Each task in a flow can be executed multiple times (retries, loops), tracked by task_execution_idx. This endpoint is primarily used by system workers to report task execution state. **Resource Hierarchy** Organization → Flow → Flow Execution → Task Execution **Lifecycle** Task executions progress through states: queued → running → completed/failed - queued: Task scheduled but not yet started - running: Task currently executing - completed: Task finished successfully with output - failed: Task encountered an error **Use Cases** - Workers reporting task execution start/completion - Recording task outputs for downstream tasks - Tracking task execution history and retries - Debugging failed workflow executions **Idempotency** This endpoint is idempotent based on (flow_execution_id, task_name, task_execution_idx). If a task execution with these identifiers exists, it will be updated rather than creating a duplicate. **Performance Notes** WebSocket notifications are processed in the background to ensure fast worker responses. The endpoint returns immediately after database write; notifications are async. **Related Endpoints** - GET /task-executions - List task executions with filtering - PUT /task-executions - Update existing task execution and optionally re-execute flow - GET /flow-executions/{id} - View parent flow execution # List task executions with filtering Source: https://docs.flows.super.ai/api-reference/task-executions/list-task-executions-with-filtering /openapi/superai-flows-openapi.json get /api/task-executions List task executions with optional filtering by flow execution, task name, or execution index. **Overview** Retrieve task executions across all flows in your organization. Results can be filtered by parent flow execution, specific task name, or execution index. Returns task executions with their associated tags for categorization and filtering. **Filtering Logic** Multiple filters are combined with AND logic: - flow_execution_id AND task_name → All executions of a specific task in a flow - flow_execution_id AND task_execution_idx → All tasks at a specific execution index - All three filters → Exact task execution lookup (equivalent to GET /{id}) **Common Query Patterns** 1. All tasks in a flow execution: ?flow_execution_id={id} 2. Specific task across retries: ?flow_execution_id={id}&task_name=send_email 3. First execution of all tasks: ?flow_execution_id={id}&task_execution_idx=0 4. All task executions (no filters): Returns all executions in organization **Response Format** Returns TaskExecutionWithTagsAPI objects containing: - Full task execution details (input, output, error, status) - Associated tags (e.g., reviewed, approved, flagged) - Metadata (created_at, updated_at, modified_by) - Organization context for multi-tenant isolation **Performance Considerations** - Queries are scoped to organization_id via RLS policies (automatic filtering) - Add flow_execution_id filter for better query performance on large datasets - Unfiltered queries may return large result sets; pagination planned for future **Tags** Task tags provide categorization and workflow state: - Tag types: 'review_status', 'approval', 'quality', 'custom' - Tags are returned with each task execution for filtering and display - Soft-deleted tags are excluded from results **Related Endpoints** - GET /task-executions/{id} - Get single task execution by ID - GET /task-tags - List all tags for a flow execution - POST /task-executions - Create new task execution # Retrieve a specific task execution Source: https://docs.flows.super.ai/api-reference/task-executions/retrieve-a-specific-task-execution /openapi/superai-flows-openapi.json get /api/task-executions/{task_execution_id} Retrieve a specific task execution by its unique identifier. **Overview** Fetches a single task execution record with all details including input parameters, output data, error information, and execution metadata. Used for detailed inspection of task execution results and debugging. **Resource Identification** Task executions are uniquely identified by UUID (id field). This is distinct from the composite key (flow_execution_id, task_name, task_execution_idx) used for creation and filtering. **Use Cases** - Debugging failed task executions (inspect error field and stack trace) - Retrieving task output for display or downstream processing - Auditing task execution history and modifications - Viewing detailed execution metadata (timestamps, modified_by) **Related Endpoints** - GET /task-executions - List task executions with filtering - PUT /task-executions - Update task execution - GET /flow-executions/{id} - View parent flow execution with all tasks # Update task execution and optionally re-execute flow Source: https://docs.flows.super.ai/api-reference/task-executions/update-task-execution-and-optionally-re-execute-flow /openapi/superai-flows-openapi.json put /api/task-executions Update an existing task execution and optionally trigger flow re-execution. **Overview** This endpoint updates a task execution's output, status, or other fields, and can automatically propagate changes to downstream tasks by re-executing the flow. Commonly used for human-in-the-loop workflows or manual corrections. **Update Behavior** When updating a task execution, the system: 1. Validates task output against the task's output model 2. Updates the task execution record in the database 3. Recalculates task output summaries for the parent flow execution 4. Identifies downstream tasks that depend on the updated task (stale tasks) 5. Optionally re-executes those stale tasks if execute_flow=true **Stale Task Detection** Tasks become "stale" when an upstream task they depend on changes. The system analyzes task dependencies from the flow definition to determine affected tasks. Only stale tasks are re-executed, not the entire flow. **Use Cases** - Correcting task outputs after manual review (human-in-the-loop) - Updating task results based on external feedback - Fixing data quality issues in completed tasks - Triggering partial flow re-execution after corrections **Concurrency** Updates use optimistic locking via updated_at timestamp. Concurrent updates to the same task execution may result in last-write-wins behavior. **Related Endpoints** - POST /task-executions - Create new task execution - POST /flow-executions/{id}/execute - Re-execute entire flow - GET /task-executions - List task executions with filtering # List all available task executors Source: https://docs.flows.super.ai/api-reference/task-executors/list-all-available-task-executors /openapi/superai-flows-openapi.json get /api/task-executors List all available task executors for workflow composition. **Overview** Task executors are reusable building blocks for workflows. Each executor performs a specific operation (send email, extract data, classify documents, etc.). This endpoint provides discovery of all registered executors with their schemas, enabling programmatic flow builder UIs and validation. **What are Task Executors?** Task executors are typed workflow components that: - Accept configuration parameters (e.g., API keys, endpoints, templates) - Optionally receive runtime input data (for input executors) - Perform an operation (API call, data transformation, ML inference) - Return structured output for downstream tasks - Support scheduling (for compatible executors) **Executor Categories** 1. Input Executors (is_input_task_executor=true): - Trigger flows from external sources - Examples: receive_email, webhook_receive, receive_file - Have flow_input_schema defining incoming data 2. Processing Executors (is_input_task_executor=false): - Transform data within flows - Examples: doc_to_structured, classify_text, format_data - No flow_input_schema (work on task outputs) 3. Output Executors: - Send data to external systems - Examples: send_email, webhook_notification, external_db - Can be terminal tasks in flows 4. Schedulable Executors (is_schedulable_executor=true): - Support time-based triggers - Examples: scheduled_db_query - Can run on cron schedules **Response Format** Returns array of TaskExecutorResponse objects containing: - Executor metadata (name, description, agent prompt) - Configuration schema (parameters_schema) - JSON Schema for static config - Runtime input schema (flow_input_schema) - JSON Schema for dynamic data - Capability flags (is_input_task_executor, is_schedulable_executor) **Schema Usage** - parameters_schema: Generate configuration UI, validate flow definitions - flow_input_schema: Validate incoming webhook/email/file data - Both schemas follow JSON Schema Draft 2020-12 specification **Use Cases** - Flow Builder UI: Display available task types with autocomplete - AI Agents: Use agent_prompt to intelligently select executors - Validation: Check flow definitions against executor schemas - Documentation: Generate API reference from executor metadata - Client SDKs: Generate type-safe executor configuration classes **Executor Registration** Task executors are registered via TaskExecutorsManager (flow-sdk). To add custom executors, see flow-sdk/src/flow_sdk/task_executors/README.md **Performance Notes** - Response cached for 5 minutes (executors rarely change) - Typical response size: ~50-100 executors, 200-500KB - Schemas can be large (1-10KB per executor) - Consider client-side caching for production use **Related Endpoints** - POST /flows - Create flow using discovered executors - GET /flows/{id} - View flow definition with executor references - POST /task-data - Get task output schemas for flow validation # Create task output Source: https://docs.flows.super.ai/api-reference/task-outputs/create-task-output /openapi/superai-flows-openapi.json post /api/task-outputs Create a task output record for a completed task and notify connected clients. Task outputs represent the processed, summarized results of task executions. Unlike task executions which track the full execution lifecycle (input, output, error, status), task outputs focus on the final output data formatted for display, downstream consumption, and workflow decisions. ## What Are Task Outputs Task outputs serve multiple purposes: - **Structured Results**: Store task results in a queryable format via the summary field - **Full Output Data**: Provide complete output for downstream task consumption - **Metadata Tracking**: Associate tags for categorization and filtering - **Real-time Updates**: Enable WebSocket notifications for UI progress tracking - **Workflow Logic**: Support decision-making based on task outcomes ## Relationship to Task Executions - **Task Execution**: Full execution record (input, output, error, retries, timing) - **Task Output**: Summarized result optimized for querying and display - One task execution typically produces one task output upon completion - Task outputs are created by system workers after task completion ## Notification Behavior This endpoint triggers two types of WebSocket notifications asynchronously: 1. **Flow-level notification**: Updates all clients subscribed to the flow's WebSocket 2. **Enhanced notification**: Broadcasts to summary-watching clients for real-time updates Notifications are processed in the background to ensure fast response times (< 100ms). ## Common Use Cases - Workers reporting task completion with structured output - Storing task results for display in execution history UI - Providing data for downstream task inputs in workflows - Triggering real-time progress updates - Enabling workflow decisions based on task outcomes ## Related Endpoints - `GET /task-outputs` - List all task outputs - `GET /task-outputs/{id}` - Get single task output - `GET /flow-executions/{id}` - View parent flow execution - `GET /task-executions` - View full task execution details # Get task output by ID Source: https://docs.flows.super.ai/api-reference/task-outputs/get-task-output-by-id /openapi/superai-flows-openapi.json get /api/task-outputs/{task_output_id} Retrieve a specific task output by its unique identifier. Fetch a single task output record with complete output data, summary, tags, and metadata. Used for inspecting individual task results, debugging, and retrieving output for downstream processing. ## Resource Identification Task outputs are uniquely identified by UUID (id field). To find task outputs by other criteria (flow execution, task name), use `GET /flow-executions/{id}` or `GET /task-outputs` (list all). ## What You'll Get - **summary**: Structured task output summary for display - **output**: Full output data produced by task - **tags**: Associated metadata tags - **status**: Task execution state when output was created - **Timestamps**: created_at, updated_at for audit trail - **Organization context**: organization_id for multi-tenant isolation ## Common Use Cases - Inspect task output for debugging or validation - Retrieve output data for manual review or corrections - Audit task execution history - Display detailed task results in UI ## Related Endpoints - `GET /task-outputs` - List all task outputs - `GET /flow-executions/{id}` - View parent flow execution with all outputs - `GET /task-executions/{id}` - View full task execution details # List all task outputs Source: https://docs.flows.super.ai/api-reference/task-outputs/list-all-task-outputs /openapi/superai-flows-openapi.json get /api/task-outputs List all task outputs across all flow executions in your organization. Retrieve all task output records for your organization. Returns complete output data including summary, full output, tags, and status for each task that has produced output. Results are ordered by creation time (most recent first). ## Important: No Pagination This endpoint currently returns **ALL** task outputs in the organization without pagination. For organizations with many flow executions, this may return large result sets. Pagination is planned for a future release. Consider using `GET /flow-executions/{id}` to filter by specific flow execution. ## What Are Task Outputs Task outputs represent the summarized, structured results of completed tasks: - **summary**: Structured data optimized for UI display and querying - **output**: Full output data for downstream task consumption - **tags**: Categorization metadata for filtering and organization - **status**: Task execution state when output was created ## Filtering and Querying Currently no query parameters are supported. To filter by flow execution, use `GET /flow-executions/{id}` which includes task outputs in response. **Planned enhancements**: - Filter by flow_execution_id - Filter by task_name - Filter by status - Pagination (limit, starting_after) - Date range filtering ## Performance Considerations - Query returns all outputs (potentially thousands of records) - Results ordered by created_at desc (newest first) - Database query scoped to organization via RLS policies - Consider using `GET /flow-executions/{id}` for filtered results ## Common Use Cases - Export all task outputs for audit or analysis - Debug output issues across multiple executions - Build organization-wide analytics dashboards - Bulk data extraction for external systems ## Related Endpoints - `GET /task-outputs/{id}` - Get single task output by ID - `GET /flow-executions/{id}` - Get flow execution with filtered task outputs - `GET /task-executions` - Get full task execution details # Add or remove task tags in batch Source: https://docs.flows.super.ai/api-reference/task-tags/add-or-remove-task-tags-in-batch /openapi/superai-flows-openapi.json patch /api/task-tags Add or remove tags from task executions in batch operations. **Overview** Task tags provide flexible categorization and workflow state tracking for task executions. Tags enable custom workflows like review/approval processes, quality assurance, and business-specific categorization. This endpoint supports batch operations to efficiently add or remove multiple tags in a single request. **What are Task Tags?** Task tags are key-value metadata attached to task executions for: - Workflow state tracking: 'reviewed', 'approved', 'rejected' - Quality assurance: 'quality_checked', 'flagged', 'verified' - Custom categorization: 'priority_high', 'customer_vip', 'requires_attention' - Audit trails: Track who reviewed what and when (via tag_metadata) **Batch Operations** This endpoint accepts an array of tag operations in a single request: - operation='add': Creates new tag (idempotent - returns 'already_exists' if duplicate) - operation='remove': Soft-deletes tag (sets status='deleted') - Mixed operations: Can add and remove different tags in same request - Atomic processing: All operations succeed or all fail **Idempotency** Adding an existing tag returns status='already_exists' without error. Removing a non-existent tag returns status='not_found' without error. This enables safe retries and prevents duplicate tag creation. **Soft Delete Behavior** Tags are never hard-deleted. Removal sets status='deleted' and records: - updated_at: Timestamp of deletion - modified_by: User/service that performed deletion Soft-deleted tags are excluded from all list queries automatically. **Use Cases** 1. Human-in-the-loop workflows: Tag tasks as 'reviewed' after manual inspection 2. Approval chains: Track 'pending_approval', 'approved', 'rejected' states 3. Quality control: Flag suspicious outputs with 'requires_review' tag 4. Custom business logic: Apply domain-specific tags for routing/filtering **Error Scenarios** - 404 Not Found: flow_execution_id doesn't exist or belongs to different organization - 403 Forbidden: User lacks permission to modify tags in this organization - 400 Bad Request: Invalid operation value or malformed request **Performance Notes** Batch operations are optimized with a single database transaction. All tag additions/removals commit atomically. WebSocket notifications are sent after commit to notify connected clients of tag changes. **Related Endpoints** - GET /task-tags - List tags for a flow execution - GET /task-executions - View task executions with their tags - PUT /task-executions - Update task execution (separate from tagging) # List active task tags for a flow execution Source: https://docs.flows.super.ai/api-reference/task-tags/list-active-task-tags-for-a-flow-execution /openapi/superai-flows-openapi.json get /api/task-tags List all active tags for task executions within a flow execution. **Overview** Retrieve tags associated with task executions in a specific flow execution. Results can be filtered to a single task or return all tasks' tags. Only active tags are returned; soft-deleted tags (status='deleted') are excluded. **What are Task Tags?** Task tags provide flexible categorization and workflow state for task executions: - Review status: 'reviewed', 'approved', 'rejected' - Quality flags: 'quality_checked', 'flagged', 'verified' - Custom categories: 'priority_high', 'customer_acme', 'requires_attention' Each tag includes optional metadata for context (reviewer name, notes, etc.) **Filtering Logic** Query parameters combine with AND logic: - flow_execution_id (required): Return tags for this flow execution - task_name (optional): Filter to tags for a specific task Without task_name: Returns all tags across all tasks in the flow execution **Common Query Patterns** 1. All tags in flow execution: GET /task-tags?flow_execution_id={id} 2. Tags for specific task: GET /task-tags?flow_execution_id={id}&task_name=send_email 3. Check if task reviewed: GET /task-tags?flow_execution_id={id}&task_name=extract_data Filter results where tag='reviewed' **Response Format** Returns array of FlowTaskTagAPI objects with: - Tag identification: tag, tag_type, task_name - Metadata: tag_metadata (JSON object for custom data) - Lifecycle: created_at, updated_at, modified_by - Status: Always 'active' (deleted tags excluded) - Organization context: organization_id for tenant isolation **Tag Types and Usage** Common tag_type values: - 'review_status': Workflow state ('reviewed', 'approved', 'rejected') - 'quality': Quality assurance ('quality_checked', 'flagged') - 'priority': Business priority ('high', 'medium', 'low') - 'custom': Domain-specific categories **Performance Considerations** - Queries scoped by organization_id via RLS (automatic filtering) - Indexes on (flow_execution_id, task_name, status) for fast lookups - Typical response: 5-50 tags per flow execution - Soft-deleted tags excluded at query time (no filtering overhead) **Use Cases** - Display task status in UI (show 'reviewed' badge) - Filter tasks by approval state (find all 'approved' tasks) - Audit workflow progression (who reviewed what, when) - Custom business logic (trigger actions based on tag presence) **Error Scenarios** - 400 Bad Request: Invalid UUID format for flow_execution_id - 403 Forbidden: User lacks permission to access flow execution's organization - 404 Not Found: flow_execution_id doesn't exist Note: Missing task_name is NOT an error; returns empty array **Related Endpoints** - PATCH /task-tags - Add/remove tags - GET /task-executions - List task executions (includes tags via TaskExecutionWithTagsAPI) - GET /flow-executions/{id} - View parent flow execution # Submit webhook data for a waiting task Source: https://docs.flows.super.ai/api-reference/webhook-data/submit-webhook-data-for-a-waiting-task /openapi/superai-flows-openapi.json post /api/flow-executions/{flow_execution_id}/webhook-data Push data to a flow execution's waiting "Wait for Webhook" task. The flow pauses when it reaches a webhook receiver task and resumes with the submitted `data` as the task's output. Data may also be submitted before the flow reaches the task; it is stored and picked up when the task runs. Delivery contract: - A 2xx response means the data is durably stored and will not be lost. - Retrying with the identical body is safe and idempotent (returns status 'duplicate'). - Retry on 5xx. Do not retry 4xx unchanged: 422 means the data does not match the task's schema; 409 with different data means the first delivery already won. Context: - The target task is addressed by `task_name` in the request body; a flow may contain multiple webhook receiver tasks. - Authenticate with an organization API key (X-API-Key) or a user JWT. Tasks that run more than once: - A receiver whose `run_after` points at a task that processes a collection item by item runs once per upstream item, and each of those executions waits for a delivery of its own. - Address them with `task_execution_idx` (0-based, in upstream item order). Omitting it targets execution 0 — the only execution a task that does not fan out ever has. - Executions are independent: the same `data` sent to two different indices is two first deliveries rather than a duplicate, and 'first write wins' applies per execution, not per task. - The number of executions is not reported by this API. A payload is accepted before the task has run at all, so there is nothing to enumerate at delivery time; carry a correlation value (typically the index itself) in whatever outbound call notifies the external system and have it echoed back here. # Changelog Source: https://docs.flows.super.ai/changelog New features, improvements, and fixes across the SuperAI Flows platform and API. Filter by **API** or **UI** using the tags on each entry. Subscribe via RSS at `/changelog/rss.xml`. ## Chat reads long documents reliably without repeat charges Chat now handles long documents: reading them no longer fails, paging through them no longer bills the whole document again, and the assistant stops repeating an action that cannot succeed. Gemini 3.8 Flash is available as a model and is the new default for chat document processing. **New** * Gemini 3.8 Flash is available as a model in both the EU and global regions, with low, medium and high reasoning levels. It is now the default model when chat reads, extracts from or classifies documents. **Improved** * Tasks you add to a flow no longer appear automatically in your existing custom views. The default Runs view still shows them, so you choose where new columns belong. **Fixed** * Chat no longer fails when you upload a long document such as a PDF with more than a hundred pages. When a step can't succeed, the assistant now explains why instead of repeating the same attempt and charging you for each one. * Paging through a large document in chat is no longer charged as a full read of the document each time. Once a document has been read, later pages come from the text already retrieved. ## Contact support from inside the app and edit review tables in bulk You can now reach support from the sidebar or right from a chat or task that needs attention, with the details our team needs attached. Review tables let you select many cells or rows and clear or delete them at once. **New** * Contact support without leaving the app. Use Contact support in the sidebar, or the link that appears beside a chat reply, document task or error message that needs attention. Pick a category, write your message, and the details our team needs are attached automatically. An Attached for our team box shows exactly what is sent. * Select cells and rows in review tables, then right-click to clear or delete them in one step. When an extraction picks up extra line items, you can remove them together instead of one row at a time. **Improved** * The Data context in the search panel now searches the last 30 days by default, so results come back faster and stay focused on recent work. Switch to Last 7 days, Last 90 days or All time when you need a different range. * When a document can't be processed, the task now tells you exactly why, for example a password-protected PDF, a corrupt file or an image that's too large, so you know right away what to change. Doc to Structured, Classifier and Image Rotation also accept more formats, including HEIC, AVIF, WebP, TIFF, SVG and EPUB, and images keep their full resolution. * The MCP server now offers your AI agent exactly the operations in the public API reference. The tools an agent discovers match the documentation, which makes agent setups more predictable. → [MCP Server](/api-reference/mcp-server) **Fixed** * My Work now displays review tasks whose target is another review step. * Deleting a flow from the hub keeps you on the hub and removes the flow from the list. ## Review tables inline, see flagged validations, and cancel runs from My Work Human Review gets inline tables with flexible split layouts and can highlight exactly which field, row or page a validation flagged. You can also cancel and re-run work straight from My Work, reference stored credentials securely in Python tasks, and choose Claude Opus 5.5. **New** * Table extractions now appear inline in the review extraction list, in the same order as your flow's fields, with a preview of the first rows and a See all option to expand in place. Split icons on each table open it in a resizable bottom dock or a side column next to the document, so you can work on wide tables without losing your place. Your layout, dock height and column width are remembered for you. * Human Review now highlights the exact field, table row or cell, document split, document type or page that a validation flagged, with the validation's message shown right next to it. Add the validations you want surfaced to your Human Review task and the highlight appears on the reviewed data, then clears once the reviewer commits a change, so it's clear at a glance what still needs attention. * Select runs in My Work to re-run or cancel them together, and cancel a single run from the task screen next to Re-run. Cancelling asks for confirmation first, and after a cancel, work mode moves on to your next item. * Reference your organization's stored credentials directly in Python task code: type # in the code editor and pick a credential from Resources to insert it. The code only stores a reference, never the secret itself, values are masked in error messages, and an edited credential applies from the next run. * Claude Opus 5.5 is now available as a model for your tasks, with EU and global processing options and all reasoning effort levels. **Improved** * The model list adds Kimi K3, Qwen 3.8 Max, GLM 5.3 and GLM 5.3 Flash, replacing models the provider has retired; flows that used a retired model keep running on its replacement. Image tasks now offer only models that can read images, and saving a text-only model on one prompts you to choose a vision model. * The document viewer now fits its controls into a single toolbar row, and page navigation moves to a compact control at the bottom of the document with an optional thumbnail strip below the page. Your document gets noticeably more room while you review, and your strip preference is remembered. * The Data table now remembers your column widths, and default widths fit the column headers. The Input and Output divider in task details keeps the position you set on each device. * Clicking an Error, Cancelled, Skipped or pending cell in the Data table now opens the cell card, the same as cells with output. Cells for tasks that were added after a run finished now read Task not part of current flow version. * Task errors are easier to read and act on: long errors scroll within their panel and keep their line breaks, Python task errors show a short, relevant traceback, and tasks explain clearly when a file can't be downloaded or a model's response reached its output limit. * Document classification is more accurate where one document ends and the next begins in a multi-document file, so pages at those boundaries are assigned to the right document type more reliably. * Flow canvas groups now have their own floating-tab style with a task count and a menu to rename, recolour or remove the group, so they're easy to tell apart from notes. Note colours now live in each note's menu and apply instantly, and tasks stay in their groups when you save. * Users with the worker role can now delete runs from the selection bar. **Fixed** * Emails are now routed to a task when its address is in Cc, the same as To. * Each click on a download now starts exactly one file, and the confirmation says Download started or File downloaded depending on what your browser reports. ## Shape your My Work table and get alerted when reviews are waiting You can now customize the My Work table column by column for each flow, and get notified when a run is waiting on a human review. Run statuses also explain themselves, so you can see what a run is waiting for and why it stopped. **New** * Customize the My Work table for each flow. Hide and reorder columns from the new Customize columns drawer, freeze a column from its header menu, and drag a column's edge to resize it. Your layout is saved for you per flow, so each queue shows the fields you work with most. * Flow notifications have a new Human review pending trigger. Turn it on in a flow's Notifications settings to get an email or Inbox alert when a run is waiting on a human review; the email links straight to My Work. If the review has already been opened or completed, or the run has finished, the alert is skipped, so you only hear about reviews that still need you. **Improved** * Run statuses now tell you more. A waiting run shows which task it is waiting for, with consistent wording across the app, and hovering a failed or cancelled run explains what happened, with quick actions to review or re-run. Failed tasks and task columns show the same detail on hover, and finished task results in stopped runs now show while they load. * Deleting a flow now also stops its runs in progress and removes its pending reviews from your Inbox. If you restore a flow from the trash, its scheduled, email and file-drop triggers are set up again, so it picks up new work just as before. * Connecting lines on the flow canvas now stay visible above groups and sticky notes, so you can follow a flow at a glance. Sticky notes have a refreshed look that matches the rest of the app. * Every download in the app now shows a confirmation once the file is saved, so you know right away that it worked. * References in the flow editor share one consistent look. References to a whole collection carry a database icon, and hovering any reference shows which kind it is. **Fixed** * A task condition that checks a sibling task is now evaluated for each item on its own, so every item runs or skips based on its own result. * Filling an extraction field by clicking a word on the document in a review now saves as expected. ## Share filtered views by link and read every sheet of your Excel files Filters and sort on any view now live in the link, so you can bookmark or share exactly what you see, and save them to a view when you choose. Excel workbooks are now read sheet by sheet, and the canvas, review screen and document classification all get faster and smoother. **New** * Filters and sort on every view, including your saved views, are now part of the page link, so you can bookmark a filtered table or send it to a teammate. Saving filters and sort to a view is now an explicit action, and every member except publishers can create, rename, duplicate and delete custom views and set their own default view. Your runs-per-page setting also stays put when you switch views or come back from a task. **Improved** * Excel workbooks are now read sheet by sheet, so data on the second or later sheets, common in bid forms, rate cards and volume files, reaches your extractions. In review, the Excel preview lets you move between every sheet, and spreadsheets process faster. * Very long tables, such as multi-page statements, now extract reliably: when a table is too large to extract in one pass, it is automatically split by page range and the rows are merged back in page order. This works for both text-based and image-based extraction. * The flow canvas opens faster on large flows, starting on the flow's input task. Jumping to a task from search always lands at the same comfortable zoom, travels at a steady pace, and selects the task you landed on. * The review screen is cleaner: task fields are always expanded, every AI hint now tells you what it shows on hover and opens on click, and the controls to hide or move extractions now sit in the extraction panel. Field instructions open from the info icon, so clicking a table field's name opens the table, and tags and Edited or Stale badges appear as soon as you save. * When you work through a review queue, items that are already completed, cancelled or being worked on by someone else are now skipped automatically, so you go straight to the next item you can work on. A short note tells you how many items were skipped, and a new settings menu next to Exit lets you choose which kinds of items to skip. * Receive Email now accepts attachments based on their actual content rather than their file name, so a PDF, image or Excel file without the expected extension, or without a name at all, is still processed. * Document classification that splits a document into parts now checks page continuity in parallel, so long documents are classified several times faster. * The AI validation rule in Item Validation and Collection Validation now offers the same up-to-date model list as the rest of your flow, so newly available models show up there too. **Fixed** * Each item in a run now moves through the rest of the flow independently, so one item that needs attention no longer holds back the others. ## Review documents your way, with field instructions one click away The review screen gets a flexible layout, keyboard navigation and full field instructions inside Task details, and bounding boxes now work on rotated pages. Doc-to-Structured adds Mistral Document AI, extraction results trace back to the page of the original file, and Python code tasks can read the flow's own documents. **New** * Recent flows now appear in the side panel under Flows, with the flow you have open highlighted. Click one to jump straight to its data, or to the designer if it has no runs yet, without going back to the hub. The collapsed sidebar offers the same list from a menu. * Mistral Document AI is now available as a model in Doc-to-Structured tasks, billed per page. Doc-to-Text in markdown mode can now return bounding boxes and confidence scores for each block of text, and new Doc-to-Text tasks start in markdown mode with bounding boxes switched on. If a Doc-to-Structured task's model can't extract bounding boxes, the designer tells you when you save the flow. * Python code tasks can now read the flow's own documents through declared file inputs. You can handle what the built-in tasks don't cover, such as reading every sheet of a workbook or the text of a Word file, without preprocessing outside the platform. * When a document is split by a classifier, extraction results now record the page number in the original file and a link to that file. You can trace every extracted value back to the exact page of the document you uploaded. **Improved** * The review screen adapts to how you work. Move the extraction list to the left or right of the document, collapse the header to give the document more room, and use the arrow keys to move through your work queue and between tasks. Long breadcrumbs now stay on one line and fold gracefully. * Field instructions are easier to reach while labelling. Click a field's label to see its instructions, and open long instructions in full in the new Field instructions section of Task details, which scrolls straight to that field. Instructions load only when you open them, so work items with large inputs open quickly. * Abstracted values now stand out at a glance in the labelling view, and the AI badges inside a value open their explanation with a click instead of a hover, so the panel stays calm while you scan it. * Bounding boxes stay visible and line up correctly when you rotate a document in review, and you can draw new boxes at any angle, including on touch screens. Rotated pages also fit the viewer width properly. * You can set a split's document type directly from the classifier's expanded page preview, where the pages are large enough to read. The preview stays open even when a type filter is active. * My Work can now be sorted by Run created at, so items keep their place in the queue by the date the run started, even after a re-run. * The Flows hub is tidier. Select flows in the list view and Delete now sits in the list header, and with one flow selected an Actions menu offers Rename, Duplicate and Copy flow ID. Template cards now share the look of the flow cards below them. * The Data view table feels steadier. A new run's row keeps its height while results fill in, an expanded cell scrolls smoothly into view, and the running indicator and sort button are easier to read. * Searching flow data is faster, including on flows with many runs. The search panel now asks for at least 3 characters before it searches, and it tells you when a search is taking longer than usual. * Search in the flow designer now zooms to the exact parameter that matched and names list items by their label, for example Document Type > Pay Stub > Instructions. Long field labels truncate with a tooltip, and expanded list items close with a clear Done button. * The flow designer catches more setup problems before a run. A Write to SFTP task without a file is flagged at design time, and the Use Logprobs Confidence setting can be switched off when the selected model doesn't support it. * Large page images are now sized to fit each model's limits automatically, so high-resolution scans process smoothly in document and chat tasks. * Gemini 3.1 Flash Lite is now available in its generally available version, and GPT-5.4, GPT-5.4 Mini and GPT-5.4 Nano show clear names in model dropdowns. * Re-running a run now happens in the background and is retried automatically until it completes, so you can carry on working while it restarts. * You can now delete notes you've written on a run. * Chat, the chats list, My Profile and Organization settings now fill the whole screen on phones. * The SharePoint receive task now lists every site in your organization when you choose where to receive documents from. **Fixed** * Doc-to-Structured tasks now use your Additional instructions when extracting. * Tasks connected to another task's Execution Error output now run as configured, so your error notifications are always sent. **Breaking API changes** * Re-executing a flow execution now returns 202 Accepted instead of 204 and runs in the background, with a Location header pointing at the flow execution. A re-run requested while one is already in progress joins it instead of returning 409, and a 503 means nothing was changed and the request can be retried. **Migration:** Treat 202 as success and follow the flow execution's status, which moves to queued, then running. Retry on 503. → [API reference](/api-reference/introduction) ## See the AI's reasoning behind extracted values and add notes to runs Extraction review can now show why the AI chose each value and the instruction each field was given, and you can keep notes on runs and find them, along with run metadata, in search. Reviewing documents, Classify tasks and My Work queues also takes fewer clicks. **New** * Extraction tasks can now explain themselves. Turn on reasoning for a Doc to Structured or Text to Structured task and each extracted value comes with a sentence or two on where it was found and how it was derived, shown as a badge inside the field during review. Fields that have an instruction also show an info icon with that instruction, so reviewers no longer need the instruction document open in another tab. * Add notes to a task run from the new Notes tab in task details. Notes form a running log that only their author can edit. The new Metadata search context finds runs by these notes and by job metadata, and data search result counts now match the results shown. * Page through a Classify task without leaving the document preview. Arrows and the left and right keys move between pages within a split, the up and down keys move between splits, and a split selector and Actions menu sit above the page. Your zoom level stays the same as you turn pages. Splits are grouped by document class and sorted within each class, so you can work through one class at a time, and the Group Splits setting is remembered. **Improved** * Document review is easier to navigate. Drag to pan the inline document viewer, and documents now open at a readable fit-to-width zoom. Clicking a bounding box scrolls its field into view, and clicking a field scrolls the document to its box in both directions. Task execution sections in the extraction list can be collapsed, the document type dropdown opens on the current selection, and wide tables scroll inside their panel instead of pushing it off screen. * My Work keeps your place. When you leave a work item, the list comes back with the filters and sort you had set. After you complete work, the All done dialog takes you back to My Work while new items load in. The Inbox My Work tab adds Collapse all and Expand all for work groups. * Write to SFTP can now write task output values as file content. Text, JSON objects and lists become the file's contents, large values are written in full, and file names are generated for you unless you set one. Templated destination paths now resolve to the folder shown in review, and review details show the actual values and paths instead of template text. * A Wait for Webhook task that runs once per item, for example once per page, can now receive data for each item. Set the new optional task\_execution\_idx field in the webhook data request to address a specific run; each run waits for its own data and continues as soon as it arrives. * The flow detail pages and work mode now share a cleaner single-card layout. **Fixed** * Re-running only stale tasks now also re-runs tasks whose settings changed in the flow since the original run. * Doc to Structured tasks now handle long documents by processing their pages in batches, for documents of up to 150 pages. ## Mark abstracted values, fill down extractions and zoom documents in chat Reviewing extracted data gets faster: flag values that were deduced rather than copied, fill a whole column in one drag, and zoom, rotate and pan PDFs and images in chat and review previews. Review screens, sharing and the app's tabs and buttons also got a cleaner, more consistent design. **New** * You can now mark an extracted field value as abstracted, meaning it was deduced or calculated from the document (such as a total summed from line items) rather than copied word for word. Use the Abstracted option in the value's ⋯ menu during review, and a small A badge shows which values are flagged. Doc to Structured and Text to Structured tasks can also pre-fill this flag for you when you turn on their new Extract Abstracted setting. * The extraction table now supports fill-down and drag-to-fill. Copy a value into the cells below it in one action instead of editing each row, which saves time when many rows share the same answer. * Admins can now resend an invitation to a member who hasn't joined yet, straight from the members list. If an invitation link can't be verified, the member is now shown how to get a fresh one instead of a dead end. **Improved** * PDFs and images opened in chat now have full viewer controls: zoom with buttons, keyboard or pinch, rotate and tilt, and reset to fit. When you're zoomed in, you can drag to pan around the page in chat and in the review document previews, and you can type a page number to jump straight to it. * The expanded review screen is easier to work in: controls are clearly labelled, and the document preview opens in place instead of in a second window. Validation notes for reviewers now appear in a clear banner you can step through, with the full list in the task details panel, and the setting that produces them has a readable name in the flow editor. * When you filter or sort the Data table, the previous and next run buttons in task detail now follow the same filters and order. You step only through the runs you're actually reviewing. * Sharing now uses one type-ahead picker for both members and worker groups, so you find and add the right people faster. The wording says Add rather than Invite, and the option to create a new user sits right under the search box. * Tabs and buttons look and behave the same across the app. Main navigation tabs use one pill style with clear count badges and can be used from the keyboard, and buttons follow a clear primary, secondary and tertiary hierarchy, so it's easier to see which action matters most on each screen. * Notices take up less room: the upgrade prompt now sits in a card in the sidebar below your credits, and privacy and consent notices appear as compact cards in the bottom-right corner. The Current credit usage card always shows a button to your plan options. * Changing your password now asks for your current password first, which keeps your account safe on shared or unattended devices. **Fixed** * Downloading files from chat cards works smoothly on iPhone and iPad, and you'll see a message if a download can't be completed. * Bulk actions on many selected items, such as re-running, cancelling or deleting runs, now run more smoothly. If anything needs attention you'll see one clear message with a Retry option for just those items. ## Review documents faster with near-instant page loads and a focused review view Multi-page documents now open almost instantly, and reviewing several task outputs is easier with a near-fullscreen view, reachable zoom and rotation, and steadier scrolling. This entry also adds choice fields for extraction, HEIC photo support, a barcode reader task and new AI models. **New** * Extraction fields can now be single choice or multiple choice. In document-to-structured and text-to-structured tasks, you define the allowed options, the AI picks from them, and reviewers choose from the same list, so values stay consistent across documents. * HEIC and HEIF images, the default photo format on iPhones, can now be uploaded and processed like any other image. Phone photos of documents go straight into your flows without converting them first. * A new Barcode reader task decodes the barcode on the back of US driver's licenses into structured fields such as name, date of birth, address, license number and issue and expiration dates. Documents without a readable barcode simply return no result, so the task never stops your flow. * Claude Fable 5, GPT 5.6 (Sol, Terra and Luna) and Gemini 3.6 Flash are now available as AI workers in the global region. Pick them in the flow builder wherever you choose an AI worker for a task. **Improved** * Multi-page documents in review now show their first page almost instantly, however many pages they have. Zoom and rotation are always visible in the review toolbar, even in a side-by-side pane, and you can scroll a zoomed or rotated page all the way to its edges. * When a review in My Work has several task outputs, you can expand any one of them into a near-fullscreen view and step between outputs with the arrows. On the page itself, one output is shown at full height while the others collapse to headers, and you can pin more than one to view them together. * The classify screen in My Work shows document types in full, lets you zoom and rotate the page preview, and puts the best match first when you search for a document type. * Sort the My Work queue by source task name, A to Z or Z to A, to work through reviews of the same kind together. Your sort choice is kept in the link, so it survives a reload and can be shared. * On a flow's Data tab, clicking a cell opens its details right below the highlighted cell, so neighboring values stay visible for comparison. The whole cell is now one click target, and you can drag the card's edges or corner to resize it and read longer values. * Tables in Organization settings and Resources share one cleaner layout: search, sort, filters and actions sit in a single row at every screen width, and primary actions are easier to spot. Organization settings tables are now paginated, with 10, 25 or 50 rows per page. * Signing in is simpler: after you enter your email, a single continue screen shows how you can sign in, and the reset password link takes you straight to setting a new password. Enterprise single sign-on now explains why it could not start instead of showing a generic error. * The flow builder now uses the same names on every AI task: the model setting is labeled "AI worker" and prompts are labeled "Instructions" (or "Additional instructions" where a task also has per-field instructions), whether you configure OCR, extraction, classification, an agent or validation. * The web app and the API respond faster and more consistently. Search and database integration checks no longer slow down other requests, and fewer requests wait on new database connections. **Fixed** * Completed reviews keep their status when a flow is re-run. If a run is re-run while you have its review open, My Work tells you and lets you check again or move on to the next item. * MCP clients now stay connected across requests, and the MCP endpoint follows the MCP transport specification for streaming requests. → [MCP Server](/api-reference/mcp-server) ## Find files and tasks in chat, and manage tags across a whole flow Chat conversations get an Objects panel that gathers every file and task in one place, and flows gain a Tags tab for reviewing and cleaning up tags. Filtering in the Data view and My Work is more precise, and chat task review now works well on phones. Enterprise admins can also claim their email domains so new colleagues join the right organization. **New** * Open the Objects panel in a chat conversation to see every file and task in one docked side panel, split into Files and Tasks tabs with search and counts. Preview or download files one at a time or all at once, and jump straight to a related task, so you no longer have to scroll back through the conversation to find what you shared or produced. * A new Tags tab in flow settings lists every tag used in the flow, with how many runs carry it, a per-task breakdown and when it was first applied. Search and sort the list, open the matching runs in the Data tab, and delete tags you no longer need across the whole flow, one at a time or in bulk. * Document and text classification tasks now give a confidence score for each page and each split when you turn on the confidence option. Use these scores to send low-confidence classifications to review. The option is available for models that support confidence scoring. * Every trigger task now exposes the run's execution ID as an output, so you can reference it in any later task in the flow. This lets you include the run ID in custom payloads, such as a request your flow sends to another system. * Link straight to a review task in My Work using values your webhook already delivers: the flow execution ID, the task name and the task execution index. Your own systems can now send reviewers directly to the right work item. * Organization admins can now restrict AI processing to the EU from the new Data residency section in organization settings. When it is on, chat and flow model calls use EU-hosted models only. Your profile page also has a new Privacy section where you can manage product news emails, product analytics and automated analysis of your usage. * Enterprise organization admins can claim their company's email domains under Organization settings › Members › Settings › Email domains. New sign-ups from a claimed domain arrive as join requests in the new Join requests tab, and admins are notified so they can add the person to the organization. **Improved** * Chat task cards and the task review window now fit phone screens. Panels stack vertically, task actions become compact icons, and extraction review opens on the fields first with a tap to show the document and a simple zoom menu. * The Data view tag filter can now match runs that contain all of the selected tags, and you can combine it with a do not contain filter. The Metadata filter is now available in the Data view too, and expanding the input task's cell shows the run's metadata under the content, so you can see what you are filtering on. * My Work keeps your filters, sort and page in the URL, so reloading or sharing a link brings back the same view. Tag filters in My Work now support both contain all of and do not contain. * When you select rows in the runs table, My Work, Flow Hub or Worker Groups, the action bar now appears in the same place on every screen, just above the pagination, and never covers your last rows. * The task card's Actions menu is now called Export, and flow sharing and review task assignment now use the term worker groups, matching organization settings. The chat assistant uses the same names as the interface, so its directions match what you see on screen. * Signing up is smoother. If you are already signed in, starting from the website takes you straight into the app, and if a sign-in provider such as Microsoft does not share your email address, you now see a clear explanation of what to do. **Fixed** * When you draw a box around a value during review, you can always type the value yourself, and you are prompted to do so if the text in that area can't be read automatically. * Importing a flow definition from JSON now opens the updated flow as expected. ## Start with free trial credits and sign up with any email address New accounts now start with free trial credits and can sign up with personal or academic email addresses. Runs are more dependable too: error notifications now cover individual task failures, runs started while you're out of credits are saved and start automatically, and Wait for Webhook tasks can time out on your terms. **New** * New accounts now start on a free trial with one-time trial credits, and you can sign up with a personal or academic email address, not only a work address. When your trial credits run out, everything you've built stays available and the app shows you how to upgrade or move to the free tier. * Error notifications now cover individual tasks too: with the Error state notification turned on for a flow, you're alerted when any task in a run fails, even if the run itself completes. Each run alerts you once, and the alert clears when a successful re-run resolves it. * When your organization is out of credits, new runs are now saved as Pending — credit required instead of being declined. They start automatically once credits are available again, so runs triggered by SFTP, email, webhooks or SharePoint are picked up without any action from you. * Wait for Webhook tasks can now have a timeout between 60 seconds and 48 hours, and you choose what happens when it expires: fail the task or skip it and continue. Without a timeout, the task keeps waiting as before. **Improved** * When the assistant in chat changes your settings, the changes now appear inline as clear, key-by-key rows instead of in a separate dialog. Nested values, lists, additions, removals and renames are labelled and indented, and long values are shortened with the full text available on hover. * The chat composer now shows a character counter as you approach the 8,000-character message limit and disables Send once you go over, so you can shorten your message before sending. If a message can't be sent, your draft stays in the composer. * Invitation links from email now open a Continue step, so you're signed in only when you click, and links checked by email security tools stay valid for you. Expired or invalid links show a clear explanation. * Organization settings, your profile and billing now work well on a phone. Members, service accounts and worker groups appear as easy-to-read cards, Compare plans shows one plan at a time with a switcher, and the settings tabs keep the active tab in view. * GPT-5.2 is now available when you choose the EU region, so you can use it while keeping processing in the EU. * In organizations that use Chat only, invited members, not just admins, now land in Chat when they sign in, with Chat navigation available across the app. **Fixed** * When a request refers to a document you haven't attached, such as a starter template prompt, the assistant now asks you to attach it. * The document pane now displays correctly while you draw bounding boxes during review, and the drawing controls appear when you hover over or focus a table cell. ## Fine-tune task models and settings right from chat You can now fine-tune the AI model, region, reasoning effort and other advanced options for tasks in chat, and review Wait for Webhook tasks on a readable details screen. Runs are easier to find and share with copyable Run IDs, and tags now open the exact task execution. **New** * Tasks in chat now have an Advanced settings section where you can choose the AI model, region and reasoning effort, plus confidence scores and bounding boxes for tasks that support them. Options the selected model doesn't support are switched off automatically. You can also switch a task's model from a dropdown on its tile, and the tile shows your saved settings straight away. * Wait for Webhook tasks have a human-readable details screen. You see the payload you expected next to the one you received, field by field with types and missing values, in resizable panels, plus a clear waiting state while the task is still waiting for data. * When you start signing up or signing in on super.ai, you can now open the emailed link on another device, such as your phone. Check that the short code matches, confirm, and your session continues in the window where you started, with the prompt and files you added still there. **Improved** * Runs are now identified by a short Run ID that you can copy in full with one click, in flow tables, navigation and task review. This makes it easy to share an exact run with a colleague or look it up later. * Clicking a tag in the Runs view now opens the exact task execution the tag belongs to, so you land right on the result you tagged. * In review, locating a table row on the document now uses a map-pin icon that tells you which page the row is on, and rows are tinted to show whether they're on the page you're viewing. Locating a row scrolls only vertically, so the document stays where you panned it. If a task's file type setting is invalid, the review screen explains why the preview is unavailable and still lets you download the file. * Settings changes and output edits in a chat conversation now show as clear before-and-after rows with readable model names. For long or structured values, select View changes to see a detailed diff, and click the document name to preview it in place. * When a file can't be added to chat, the message now tells you exactly why. An oversized file shows its size next to the 8 MB limit, and an unsupported file lists the formats chat accepts. * Long structured results that reach the model's output limit now continue automatically instead of starting over. Extractions from large documents complete more often and faster. * Requesting a fresh invitation from an expired invitation link is now a single click. You no longer need to type your email address. **Fixed** * Task references used in the instructions of extraction fields, table columns, classifier document types and agent outputs are now replaced with their values when the task runs. * Email-triggered flows that stay paused for more than a day, for example while waiting for human review, now resume as expected. **Breaking API changes** * The run\_number field and the include\_run\_number query parameter are removed from the list and get flow execution endpoints. Requests that still send the parameter succeed, without the field. **Migration:** Identify runs by their id, which the app now shows as a copyable Run ID. * Resending an invitation now takes the invite\_token from the invitation link instead of an email address. The endpoint always returns the same acknowledgement and can return 429 when called too often. **Migration:** Send the invite\_token from the invitation link in the request body, and retry after a pause on 429. → [API reference](/api-reference/introduction) ## See extracted fields highlighted right on the source document Check extracted data against the source document with highlights, fill repeated values in merged results in one drag, and stop a chat reply mid-turn. The chat app now also works comfortably on your phone. **New** * In chat, select View highlights on an extraction result to see the extracted fields and table rows outlined on the original document, in a full-screen view with page navigation. When you review an extracted table, choose Show in document on a row (or its locate icon) to go to its page and highlight it. You can also click a highlight in the document to select the matching row. * When you review merged results in the spreadsheet grid, right-click a cell and choose Fill down or Fill up to copy its value into the empty cells below or above. You can also drag the fill handle to copy a value across a range. Pressing Enter now confirms an edit in review table cells and fields. * Use the new Stop control in chat to end a reply that is still in progress without leaving the conversation. Whatever was already written is kept and marked as stopped, and you can send your next message right away. * Use the chat app, navigation and sign-in comfortably from your phone. A slide-out menu and a New chat button in the header make it easy to move around. Starter prompts and industry tabs scroll sideways, so the message box stays in focus on small screens. **Improved** * When you change a task's settings or correct its output in chat, the assistant now shows what changed and asks what you'd like to do next: re-run this document, re-run all documents, or keep the change. Several edits made together become a single question, and corrected outputs appear in the conversation as Output edited with the changed fields. * Searching a flow now highlights matching fields inside task builders, including nested fields. Open a builder from a search result and the matching row is brought into focus, so you find the setting you were looking for straight away. * The Data table of a flow now opens noticeably faster on flows with many runs, and filtering runs by tag, task name or status responds much more quickly. * Flow notification settings now have an explicit Save button, so changes apply only when you confirm them. The Notifications tab in Flow Settings is shown only to people who are allowed to edit it. * The redesigned billing page groups credit volumes by plan, marks your current and recommended volume, and shows the discount on annual billing. Plan cards compare Free, Growth and Enterprise side by side, with a Current plan tag and clear actions such as Upgrade, Reactivate plan or Downgrade to Free. * SFTP tasks now retry automatically when the server is briefly busy or slow to accept a connection, and give slower servers more time to respond. Sign-in errors are reported right away so you can correct the credentials. * The sidebar and chat have a cleaner look, with clearer hover and selected states and refreshed starter prompt cards. New chats get short, label-style titles of a few words. ## Chat is now available to every eligible user, with a new sign-in Chat is now generally available, with a redesigned sidebar, starter prompts, automatic conversation names and support for text, CSV, Markdown and JSON files. Signing in is simpler with one email-first screen, and a new Usage tab shows your credit consumption at a glance. **New** * Chat is now available to everyone whose role and plan include it, with no extra setup. If your account qualifies, Chat appears in the navigation and is where you land after signing in. * Sign in and sign up from a single screen. Enter your email and the app offers the right option for your account: single sign-on, password, a magic link, or creating a password. If you cancel a sign-in with an external provider, you return to the screen you started from. * Upload plain text, CSV, Markdown and JSON files in chat. They are read directly without scanning, previewed with formatted JSON and CSV tables, and recognised by their file extension even when the file type is missing. * A new Usage tab in your organization details shows your monthly and additional credit usage, and you can buy more credits or upgrade your plan right from there. The Credits link in the sidebar now opens it, and the Billing page focuses on plans and subscription details. * New conversations name themselves from your first message and any attached file names, so your chat list is easy to scan. The name appears in the header and the sidebar while the first answer is still being prepared. * Start on super.ai: describe your task and attach files on our website, and after you sign up your first chat opens with them already sent, so you pick up exactly where you left off. **Improved** * The sidebar has a cleaner layout with quick buttons to start a new chat or browse all your chats, and a collapsible Recent list that opens on hover when the sidebar is collapsed. Long chat, flow and account names now show in full in a tooltip, and the chat header stays hidden on a new chat and floats over the conversation as you scroll. * Starting a new chat is quicker: pick your industry to browse starter prompts shown as cards, and select one to fill the message box. Previous conversations open at the latest message with their history in order. * Data extraction in chat now reads a document's text once and reuses it, so you can ask for more fields without the document being processed again. Text extraction appears as a Data Extraction step, and corrections you make to extracted values stay consistent with the summary. * Classification results in chat can now be copied or downloaded as JSON or CSV, including the document type, confidence, split details and page ranges. When a document is split into parts, each part's results are grouped under the original document so you can follow them at a glance. **Fixed** * CSV files generated by the Format Data step can be downloaded, previewed and delivered to SFTP. → [Downloading Files](/guides/downloading-files) ## Pause flows for external data and see why tasks ran Flows gain a Wait for Webhook task that pauses a run until an external system sends data, and the Run Graph now explains why each task did or didn't run. Monthly Growth subscribers can switch to annual billing in-app, My Work updates live, Python code tasks can process images and PDFs, and voice input works in the agent chat. **New** * Dictate messages to the AI agent: press the microphone button in the agent chat on the Hub or in the flow designer to start and stop recording. Your speech is transcribed into the message box so you can review it before sending. * Add a Wait for Webhook task to pause a flow until an external system sends data. The flow editor shows the URL to submit to and lets you define the expected payload, and the run resumes automatically once the data arrives. * Monthly Growth subscribers can switch to an annual plan directly from the billing page. A confirmation shows what you will be charged before you upgrade, and a move to a plan with fewer credits is scheduled for the end of your current period instead of charged right away. **Improved** * The Run Graph now explains why each task did or didn't run. Edges show how many items flowed down each path, tasks that routed no data are marked 'No path taken', and a skipped task names the task that caused it, with a button to jump straight to it. A new View Task Design button opens any task in the flow editor. * My Work and review screens update live as human review assignments are created, started, completed or cancelled, so you always see the current list without refreshing. Assignments made to a worker group appear for every member right away. * Full filenames are now visible across Runs, My Work, data tables and file previews: click a truncated name to see and copy the whole name, and runs with several files list one per row. Data table cells open in a click-to-expand preview for easier reading. * Search now finds matches hidden inside collapsed fields. Collapsed list items that contain a match are highlighted and expand when you jump to them, and the Field Extractor and Output Builder dialogs open with every row expanded. Jumping to a match in the data table scrolls to and highlights the right cell. * The flow editor flags invalid human review assignees and unavailable AI models while you design, so you can fix them before running the flow. * Python code tasks can now use Pillow, OpenCV and PyMuPDF for image and PDF processing, and more of the standard library works as expected, such as parsing dates. Unsupported modules return a clear error. * The SSO setup dialog shows the service provider details your identity provider needs, including the entity ID, metadata URL, ACS URL and logout URL, as copyable fields, even before SSO is configured. * The billing page puts upgrading front and center, with a plan configurator beside the plan cards and annual pricing shown by default. Page estimates now reflect typical usage (the Free plan shows 300 pages per month), and the upgrade banner can be dismissed, leaving a compact upgrade card in the sidebar. ## Search across your flows and data, now available to everyone Search is now open to every user, with highlighted matches that take you straight to the right table cell or field. Admins can also top up credits from the Billing page, and the sign-in screen now offers social login alongside SSO. **New** * Search is now available to everyone in your organization. Find flows, runs and data from the search panel, then jump to the match: matching table cells and form fields are highlighted, and clear actions let you open details, show items in tables, or filter a table by run. * Admins can now buy more credits directly from the Billing page: pick a preset or custom amount, review what you're getting and continue to checkout. Other members see that credit purchases are handled by organization admins. The credit volume slider is easier to use too, with clickable tick labels. * The sign-in screen now offers Google, Microsoft, LinkedIn, GitHub and GitLab sign-in alongside SSO, right above the email form. Password fields on sign-in, password reset and account settings now have a show/hide toggle so you can check what you typed. * Table extraction can optionally record where each row and cell sits on the page. In review, hovering a table row highlights it on the document, switches to the right page and scrolls it into view, so you can check extracted tables against the source quickly. **Improved** * Review screens give your documents more room. Receive File shows each document larger, Receive Email reviews scroll in one place with the PDF fitted to its column, and integration tasks such as SharePoint and Azure Blob now have a details view with their fields and documents side by side. * Confidence scores can only be turned on for models that support them, and you get a clear message when a model doesn't. When confidence scores are off, results show N/A instead of 0%. * Edit saved credentials without re-entering your secrets. Secret fields show a masked value with Change and Cancel actions, and any secret you leave untouched keeps its saved value. * Flows run faster: each task now starts sooner after the previous one finishes, cutting the waiting time between steps in multi-step flows. **Fixed** * The CSV upload preview now keeps quoted values that contain commas in a single column, and database matching against CSV databases keeps leading zeros in codes such as 000. ## Choose what happens to Azure Blob files after pickup Azure Blob Storage inputs can now leave, move or delete files once they've been picked up. Reviewing executions, managing saved table views and reading credit balances also got smoother. **New** * Azure Blob Storage inputs now let you choose what happens to each file once it's picked up: leave it where it is (the default), move it to another container or prefix, or delete it. The action runs only after the file has started a flow, so files are only moved or removed for runs that began. **Improved** * Step through executions directly from the review pane. If you have unsaved changes, you are asked before switching, and task details, tags and the selected execution stay in sync and load smoothly as you move from run to run. * Saved views in the flow executions table update instantly when you create, rename, duplicate or delete them, and a newly created or duplicated view is selected for you. Showing, hiding and reordering columns also feels smoother, with your changes saved as soon as you pause. * Credit amounts read more clearly: the sidebar credit meter and the credit limit dialog now use the same compact notation as the billing page, such as 1.5M instead of 1500k. If your organization has used more credits than it has available, the Additional credits card on the billing page now shows the amount owed. **Fixed** * When you re-run an execution after removing a task from the flow, the removed task no longer appears in that execution. * Task status in the executions table now matches what task details show. **Breaking API changes** * Credit usage is now opt-in on the flow and task execution read endpoints. total\_credits on flow executions and credits on task executions are returned only when you pass include\_credits=true, which keeps standard responses lighter; previously, getting a single flow execution always included total\_credits. **Migration:** Add include\_credits=true to requests that read total\_credits or credits. → [API reference](/api-reference/introduction) ## Upgrade to the Growth plan and compare plans right in the app Admins can now upgrade to the Growth plan from inside the app, compare plans side by side and size their monthly credits before subscribing. Task references in the flow editor are also easier to read and work with. **New** * Organization admins can now upgrade to the Growth plan from inside the app, monthly or annually. The new pricing section compares the Free, Growth and Enterprise plans side by side, lets you size your monthly credits with a slider, and includes a contact form for billing questions. Your subscription summary shows your current plan separately from any scheduled change, and your monthly credits now renew on your billing date. * Python tasks can now use the exiftool library to read metadata from PDFs and images, such as capture details, camera information and embedded document properties. This lets you sort, check or enrich files based on their metadata without an extra step outside your flow. **Improved** * Task references in the flow editor are easier to work with. Collection and Single references now have their own colours, and right-clicking a reference lets you jump to the referenced task or switch its mode. The reference mode settings now pre-select and label the default mode. In Python and Calculation tasks, references behave as single blocks that the cursor skips over and that copy and paste cleanly. * If an uploaded document can't be read, for example because it is empty or isn't a valid PDF or image, the run now shows a clear message, so you know to replace the file rather than retry the flow. **Fixed** * Improved compatibility with SFTP servers that use older ssh-rsa host keys. ## Build API calls visually, add task conditions and read from Azure Blob Storage Building flows gets easier: you can construct API request bodies visually, run tasks only when a condition holds, and start flows from files dropped into Azure Blob Storage. Your inbox is now split into Notifications and My Work, and search results take you straight to the data you are looking for. **New** * Start flows automatically from Azure Blob Storage. Add the Azure Blob Storage input task, connect your storage account, choose a container and optionally a folder prefix, then point an Azure Event Grid subscription at the webhook URL shown in the task form. Only files inside the container and prefix you chose are processed. * Build the request body of an API call task visually: switch the body to Builder and add fields and values, or stay on Raw JSON if you prefer. If a raw body, headers or query parameters aren't a valid JSON object, the task run shows a clear message explaining what to fix. * Give a task a condition expression so it runs only when the condition is met. Use it to skip steps that don't apply to a document or to branch your flow without extra tasks. * Find Similar Examples tasks now have their own details view in the Review tab. It shows the search parameters, such as database, table, strategy and column matches, next to the matched examples in a table. Resizing a column in review tables now keeps neighboring columns in place. **Improved** * Your inbox is now split into Notifications and My Work tabs, each with its own count, so updates and the review work assigned to you no longer compete for attention. My Work groups items by flow, and you can mark notifications read or unread one at a time or all at once. Work you've already completed shows as completed when you return to it, and review queues refresh right after you act. * Search results show an icon for each task type and display full run IDs. Use Show in table to jump into the data view filtered to that run, scrolled to the matching task's column, or Go to task to open the flow with that task centered. * Human review tasks that review items one by one now accept simple values, such as a single number or text, as the reviewed output for each item, not only structured objects. This lets you put a person in the loop on more kinds of task output. * Python tasks can declare a typed output, and each run's result is checked against it. Mismatches are caught at the task itself instead of surfacing in later steps of your flow. * The confidence score toggle in extraction tasks is now disabled for models that don't return confidence scores, and it switches off automatically if you change to one of them. Gemini 2.5 models now support confidence scores. * In member and worker group management, the Teams, Flows and Workers columns expand into a searchable list. Open the full list in a side panel to see everyone or everything assigned at a glance. * Filter the list of flow executions by date: the List flow executions endpoint accepts created\_after, created\_before, updated\_after and updated\_before (ISO 8601, inclusive), so you can fetch just the runs from a time window. **Fixed** * Attribute mapping in SSO settings is easier: paste your identity provider's metadata URL or XML and pick from the claims it lists, or type a custom attribute name. Long claim names scroll fully into view. ## Store API credentials once and reuse them across your flows A new Credentials tab in Resources lets you save API keys and tokens once and use them in API and webhook tasks, with values kept masked. New teams can now sign up on their own and start on the free tier, review screens are easier to edit, save and re-run, and merge tasks gain inner, left, right and outer joins. **New** * Manage API credentials in the new Credentials tab under Resources and reuse them across your flows. API tasks can map a stored credential into request headers, and webhook tasks can authenticate with one. Credential values stay masked in task results, logs and edit forms, so you no longer paste secrets into individual tasks. * Sign up on your own: create an account and organization from the signup page with a supported sign-in provider or a magic link, and start on the free tier without waiting for an invitation. * Re-run a task's run straight from the review screen in My Work, if your role allows it. Choose to re-run every task or only the tasks affected by changes, and you move on to the next item in your work queue automatically. **Improved** * Review screens are easier to work in: collapse or expand individual task panes, save source edits with a Save button, add or remove tags, and confirm before leaving with unsaved changes. Reviews use the exact flow version each run executed with, shown as a copyable flow definition version in task details, and merge reviews highlight invalid cells as soon as they load, with tables that fit the available width. * Merge tasks now support inner, left, right and outer joins on a shared join key, so you can combine data sets the way you would in a spreadsheet or database. The join key appears once in the output and other columns are labeled with their collection's alias, so joined results are easy to read and use in later tasks. * The runs table now shows a Created At column, so you can see when each run started and audit your history at a glance. * SharePoint integrations now notice when the monitored folder has been deleted. The integration editor clears the missing folder so you can pick a new one and keep documents flowing in. **Fixed** * Date filters in flow details now cover the same days for everyone, whatever their time zone, including when you share a filtered link. ## Resize and collapse review panels, and filter My Work by run Review screens now adapt to your workspace with collapsible, resizable panels and resizable side-by-side task cards. Run tables are easier to navigate, with clickable inputs, a Run ID filter in My Work and clear sort indicators. **New** * Filter My Work by Run ID. Add the new Run ID filter, enter a run's ID, and the list narrows to the review tasks from that run, so you can focus on one execution without scrolling through everything else. **Improved** * Document and text review screens adapt better to your space. You can hide or resize the extractions panel, and hide the page overview, which also tucks away automatically when space is tight. Your panel choices are remembered. Each section now fits the screen and scrolls on its own. When two task cards sit side by side in a review, drag the divider between them to resize, and the widths snap to tidy positions. * Run tables are quicker to navigate. Click a metadata badge or a file in a run's inputs to jump straight to the task details, and the table is less cluttered with the Created At column removed. * It's now clear how a table is sorted. The Sort button shows the active sort (Created at or Updated at) with an arrow for its direction, and the Created At column header shows a matching arrow, including for the default newest-first order. The sort button also has a descriptive label for screen readers. * Edited tasks are easier to spot. An Edited badge marks tasks whose output has been edited, and the re-run notice now appears only while downstream tasks still need a re-run, with a See details link to open the task and a Re-run downstream button. ## Require SSO and MFA for your organization, and review tasks side by side Organization admins can now require single sign-on and multi-factor authentication for everyone, and restore deleted items from the new Trash bin. Multi-input human review gets a card-based, side-by-side layout, and a new Review Flow page lets you compare several tasks of a run at once. **New** * Admins can now require SSO sign-in, multi-factor authentication, or both for their whole organization from the Security section of the organization settings (SSO requires a configured SSO provider). Members who haven't set up MFA are guided through enrollment with a QR code or secret key, and members of an SSO-only organization are directed to Continue with SSO when they sign in. * A new Trash bin, available to admins from the profile menu, lists deleted flows, members, resources and databases, sorted newest or oldest first, and lets you restore any of them with one click. Restored items reappear in their lists right away, so an accidental delete is easy to undo. * The new Review Flow page lets you compare the results of several tasks from the same run side by side. Hover over a row in the data table and click Review, then use Add Task to Review to add, remove or reset the tasks you want to inspect, and your layout is remembered. **Improved** * The multi-input Human In The Loop task now uses a card-based review layout that can show several task results side by side. A Layout menu lets you reorder, hide, or switch each source between full and half width and toggle its inputs, and your layout is remembered in your browser. Reviews can also target individual items inside an output collection, and if someone else is already reviewing a task, an inline banner tells you so and the task opens read-only. * Merge review keeps columns in a predictable order that follows your field mapping, shows the expected type in a tooltip when a cell value is invalid, and keeps your cursor in place while you edit. Saving is only enabled once every cell is valid, so you catch mistakes before submitting. * The flow data view has a Created At column and a From/To date filter, so you can find items created in a specific period. Open-ended ranges work too, for example everything created since a given day. * The real-time data table stays responsive on larger flows. Task results show their final status right away, columns keep their order when you show or hide them, and the filter menu always reflects the view you switch to. * Browser tabs now show the name of the flow or work item you have open, so you can tell several open tabs apart at a glance. * When a task's output configuration needs attention, the flow's validation now shows a clear message explaining what to fix. **Fixed** * The agent prompt editor now keeps your cursor position while you type. * When you cancel a flow run, any tasks still running or waiting are now marked as cancelled too. ## Review tasks that lock to one reviewer and track what changed Human review gets a clearer screen, a rebuilt merge table, one-reviewer-at-a-time task claims and a new output showing what reviewers changed. Table extraction is more reliable, review screens handle image documents smoothly, and flows with large outputs open faster. **New** * When you open a review task that someone else is already working on, you now see who has it and can move straight on with Go to next. Tasks another reviewer has started no longer appear in your queue, so two people don't end up reviewing the same item at once. * Human review tasks now have a was\_changed output that shows, for each editable input, whether the reviewer changed it. Use it in later tasks to route corrected items differently or to see how often reviewers adjust results. * Text and number extraction fields can now be set to return a single value instead of a list. The output is one value or empty, which gives later tasks a simpler shape to work with, and the review screen marks these fields as single value. * Choose your own default view for each flow. The view you mark as Default opens first for you, without changing what your teammates see. **Improved** * The review screen in My Work and Task Details is easier to work through. Each source has a header with its task icon, and when a review has several sources you get a counter and expand or collapse per source; every item shows whether it is editable or read-only. You can edit and save individual items in a completed review, and re-running a flow refreshes its open reviews so reviewers always work on the latest results. * Human review tasks now ask for at least one assigned user or worker group when you configure them, so every review reaches someone. * Merge reviews now use the same table as text-to-structured reviews. Edit cells in place, resize columns, add or delete rows from the right-click menu, and scroll sideways through wide tables. * Review screens for document extraction and classification now display image files such as JPGs as smoothly as PDFs, choosing the right viewer from the file type. In the document-to-text view, large images keep an even split with the output panel. * Table extraction is more reliable. It returns clean rows keyed by your configured columns, captures every row in the document, and handles values with currency symbols, thousand separators or units. If a first pass comes back empty, it automatically tries again. * The Find Similar Examples task now returns matching rows keyed by the columns of the table you select, so you can reference individual columns in later tasks. * Flows with large task outputs open faster. Heavy outputs load on demand, their cells show Loading until they arrive, and row details show the full output. The Review tab loads only the task you pick, which keeps live updates light. * Your profile page now has separate sections for account details and for changing your password, with checks that a new password has at least 8 characters and matches its confirmation. The Credits link in the sidebar now takes you to your organization's billing page. **Fixed** * Email attachments with encoded filenames now keep their full original name. ## Manage your whole organization from one place, and review PDFs page by page A new Organization area brings members, worker groups, service accounts and SSO together in one place. Review pages get a paged PDF viewer, and your inbox now tells you when you're added to a team or invited to a flow. **New** * A new Organization area brings your organization's settings together in one place: organization profile, members and their roles, worker groups, service accounts with their API keys, and SSO settings. Admins can add, edit and remove members and change roles without going through their personal profile. * Your inbox now tells you when you're added to a team or invited to work on a flow, with the flow's name and a direct link to open it. When you join a worker group that is already assigned to active flows, you'll get an inbox notification for each of those flows so you can start working right away. **Improved** * Review pages now show PDFs in a paged viewer with page-by-page navigation and a page indicator, so long documents load quickly and stay easy to move through. The document viewer has a download action that saves the file directly, and review screens scroll as a single card with sticky section headers. * The runs table on a flow loads faster and remembers your view, filters, sort order and page in the address bar, so you can bookmark or share exactly what you're looking at. You can also search for columns when customizing the table. * The Write to Database and Find Similar Examples tasks now work with your table's real columns. Pick columns from a selector, map values to them directly, and choose whether all clauses or any clause must match when searching for similar examples. * The Multi-input task's output fields can now be of type Object, with their own nested sub-fields, alongside Collections, so you can describe structured results such as an address more precisely. Metadata fields you configure on a file input can now be mapped one by one, and Excel attachments on incoming emails are recognized as spreadsheets. **Fixed** * When a review is submitted while your organization is at its concurrent-run limit, the run now waits for a free slot and then continues automatically. * Notify tasks now add or remove their tag on the selected task, including when that task's output is referenced as a whole. ## Review several tasks at once and teach flows from past examples A new multi-input Human In The Loop task lets one reviewer check several earlier tasks in a single review, and your organization now has its own database: create tables in Resources, then save results and reuse past examples from your flows. Webhook tasks gain configurable retries with a clear view of every delivery attempt. **New** * A new Human In The Loop (multi-input) task lets one reviewer check the results of several earlier tasks in a single review. Builders choose which items reviewers can edit and which they only see for context, and reviewers can edit merged collections directly in the table. Every reviewed item becomes its own output, so later steps can use the corrected data right away. * Two new tasks help your flows learn from earlier work: Write to Database saves results to a table you pick, and Find Similar Examples looks up comparable past records to give the next step useful context. The table picker warns you about missing columns before you run, so setup mistakes show up early. * Webhook tasks now let you decide how deliveries are retried. Open Retry Settings on the task to set the number of retries, the wait between them and which status codes should be retried. In the run details, pick any attempt from a dropdown to see when it was sent and the response it got, with the latest attempt selected by default. * Your organization now has its own database. In Resources, create tables and columns, choose column types, set primary keys and relationships between tables, and browse the data in each table, ready for your flows to read and write. **Improved** * Flows that accept several kinds of input now get a tailored review view that shows which source started the run and the exact data it received. Multi-input flows that accept files can now be started with the Run action and file upload, and their files and details appear in the Runs and My Work tables. * The flow list in your hub is now a full table with resizable columns that remember their widths, and a header that stays in view as you scroll. * Long column headers and task titles are easier to read: hover over them to see the full text, and headers show their icon where one is available. Selected rows are now highlighted across the whole row, including pinned columns. * Python tasks can now use the jsondiff library, so you can compare two JSON documents and work with the differences directly in your code. **Fixed** * Run tables and the review tab now stay up to date as runs progress and when you re-run tasks. * Flows triggered by email now read the sender and date correctly across more email formats. ## Invite whole teams to flows and keep track of what's unread You can now invite teams to a flow, mark inbox notifications read or unread, and preview files right from your runs. My Work, work mode and the runs table are also easier to navigate. **New** * Invite whole teams to a flow, not just individual people. The flow's sharing panel now lists invited members and invited teams separately, and team members get access based on their role, along with an email invitation. When you assign people or teams to a human review task, anyone not yet invited to the flow is flagged with a quick way to invite them, and the search box clears after each pick so you can add several quickly. * Mark inbox notifications as read or unread, one at a time or all at once from the inbox header menu. Your inbox now shows both read and unread items, and the badge counts only what you haven't read yet, so it's easier to see what still needs your attention. * Preview files and attachments from a run in a full-height side panel, step through multiple attachments, and jump straight to the task that produced them. The Files and Metadata columns in My Work and Runs now show files from every input type, including email, Google Drive, SharePoint and SFTP. * Download the source document with one click while reviewing a document or text extraction task. Downloaded files keep a sensible name and extension, so they're easy to file away. * Turn confidence scores and bounding boxes on or off per task when you configure document extraction. The settings detect what the selected model supports, enable only the options it can use, and pick a suitable default reasoning effort when you switch models. **Improved** * My Work now loads one page of tasks at a time, with a page-size selector (10, 25 or 50), first and last page controls, and the total number of tasks shown. Large queues open quickly and stay easy to move through. * In work mode you can switch to another run from the sidebar to look at it. Runs outside your work queue are clearly marked and read-only, and if you have unsaved changes you're asked whether to discard them before switching. * The runs table keeps queued runs out of the list and shows separate queued and running counts in the footer instead. Task start and completion times now show to the second, time to complete appears for finished tasks, and cancelled tasks are marked individually in flow review. * Setting up a Multi-input task is clearer. Edit its output schema in a dedicated dialog where you can add and manage fields and sub-fields, then see a compact summary on the task. Output mappings have separate edit and read-only modes, and each trigger highlights any fields that are not mapped yet. * Team pages are easier to manage: edit a team's name and description in place, search its members in a table showing role, email and date added, and remove members or delete the team from the same page. * The flow editor handles groups and sticky notes more smoothly. Importing a flow brings its groups and notes along with its tasks, auto-layout leaves them where you put them, and dragging tasks into and out of groups is smoother, even in large flows. Re-running tasks or runs now saves your unsaved changes first. ## Start one flow from several inputs and rotate pages while you review Flows can now accept more than one input source and map them into a single set of fields, and review screens let you rotate document pages. Excel files preview inline, tags can be added at upload, and notification settings have a cleaner layout. **New** * Run a flow from more than one input source, such as an email, a file upload or a form. The new Multi-input task lets you add the input triggers you want, define one output schema and map each trigger's fields into it, so the rest of your flow works the same no matter how the work arrived. Files you upload from the Run button go straight to the right input automatically. * Rotate document pages in 90-degree steps while reviewing Classify, Doc to Structured and Text to Structured tasks. Rotate a single page from its context menu, a whole document in one click, or use the rotate button in the document toolbar. Bounding boxes step aside while a page is rotated and can be switched back on. Rotation only changes your view, so sideways scans are quick to read and the original file stays untouched. * Excel files now preview inline in task details and hover cards. You see the first sheet as a formatted table with its total row count and a download button; files larger than 5 MB offer a download instead. **Improved** * Add tags while you upload files or URLs to run a flow, so runs are organized from the start. In task details and My Work, the tag bar now shows the tags for the item you're viewing and follows your selection as you move between items. * The Notifications tab in flow settings has a cleaner layout with separate Email and Inbox cards. Set an hourly or daily email digest in a single line, add recipients with a searchable picker, and preview the email subject and body with your flow's actual name. * Paging through runs in the Table view is easier: jump to the first or last page and choose 10, 25 or 50 runs per page, and your choice is remembered. A single icon on the run number highlights runs that need attention in the columns you're viewing, and columns you reveal return to their natural position. * The From JSON task can now extract specific fields from items in an array, including arrays nested inside objects, and can target keys that contain dots. This makes it easier to pull exactly the values you need from complex JSON, and the builder stays in sync as you edit or remove fields. * When a human review task is assigned to a worker group, everyone in that group automatically gets access to the flow. People who join the group later are added to flows where the group still has open review tasks, so reviewers can start right away without waiting for an invitation. * When your organization has many runs in progress, new runs wait in a queue and start automatically as capacity frees up. Queued work is balanced fairly across your flows, so one busy flow doesn't hold up the others. * Organization administrators can now delete any database in their organization, while other users can delete the databases they own. * Long flow names show in full when you hover over them in card and list views, and card titles have more room. Worker tasks are now listed as Processing tasks, model settings are labeled AI model, and the My Work badge turns grey when you have nothing waiting. ## Get run alerts by email and in your Inbox, and process Excel files You can now set per-flow alerts that notify you by email digest or in your in-app Inbox when runs need attention. Document processing also gains Excel support, image attachments from email, auto-rotation and whole-document classification. **New** * Set up run alerts for each flow from the new Notifications tab in flow settings. Get alerted when a run errors or keeps running longer than a time you choose, pick the people or teams to notify, and receive hourly or daily email digests, so your team hears about runs that need attention without watching the dashboard. * Flow notifications now also arrive in your in-app Inbox, grouped by flow alongside your review tasks, with an unread count that updates live. Jump straight to the flow from a notification, or copy its run ID to share it. * Receive File, Receive Email and SharePoint tasks now accept Excel spreadsheets (.xlsx and .xls), and Receive Email also picks up JPEG and PNG attachments alongside PDFs. Use Doc to Text to turn the first sheet of a spreadsheet into text, and its data then shows as a table when you review Text to Structured results. Tasks that don't support a file type tell you so clearly as soon as they start. * Document Classifier, Doc to Structured and Doc to Text tasks have a new auto-rotate setting that straightens scanned or sideways pages before they are read. It is off by default. With Doc to Structured, the rotated document is shown with the extraction results. * Classification tasks can now classify a whole document at once instead of page by page, with an optional page range to focus on the pages that matter. The task output also lists which pages were used for classification. * Edit your templates in a full-screen editor with live validation, update their name, description, tags and visibility, or delete templates you no longer need. If you try to leave with unsaved changes, you're asked first, so you won't lose work by accident. * GPT-5.4, GPT-5.4 mini and GPT-5.4 nano are now available in the model selector for AI tasks that use the Global processing region, giving you more choice between quality, speed and cost. **Improved** * Drawing a box on a document during review now fills in the text right away, reading it from the PDF directly or recognizing text in scanned pages when needed. Overlapping highlights stay easy to tell apart, and when extracting with Gemini models, each value of a multi-value field gets its own highlight. * Task details now show which flow you're in, plus a Flow Execution section with the flow and run IDs, when the run was created and last updated, and who last modified it. Human review tasks placed after a Branch or Validation task now show the original document and results from the task that produced them. * In the Data view, filter run status, task status and tags by "contains one of" or "does not contain", and hover truncated filenames to read them in full. In My Work, click anywhere on a row to open it and see the new Run ID column. You can also delete a flow straight from its header, and documents load more smoothly in the viewer. * Creating a flow in the Hub now starts with naming it, including when you start from a template, and a new Created By filter helps you find your own flows or a colleague's. The Hub also points out empty flows older than 30 days so you can clean them up in one step. * Configuring tasks is faster: dropdowns throughout the app are now searchable, the Notify task's tag field lets you pick an existing tag or create a new one, and task settings have clearer tooltips explaining what they do. Selected tasks and their connections stand out more clearly in the flow diagram. * The review screen now shows a clear explanation, with options to re-run or open the flow setup, whenever a task needs attention, and tasks automatically retry on temporary issues with connected services. * Google Drive and SharePoint triggers now work through large batches of files page by page, so even very large folders are handled smoothly. * The Write to SFTP task can now rename files by adding a prefix or suffix to the original filename, including values referenced from earlier tasks, so output files follow your naming conventions. * Admins can search, sort and page through teams, create and edit them in dialogs, manage members, and delete several teams at once. The Users tables now show each user's teams. * Your profile page now shows your organization's details, with one-click copy buttons for IDs and other read-only fields. **Fixed** * Task statuses now always reflect the final outcome of a run, including runs that end early or are cancelled. ## Choose from the latest Gemini models, with European and global options You can now pick Gemini 2.5 Flash Lite and the newest Gemini 3 and 3.1 preview models for your tasks, and bounding-box extraction works with more Gemini 2.5 models. Reviewing work is smoother too, with clear unsaved-changes handling and edits that show up right away. **New** * Gemini 2.5 Flash Lite and the Gemini 3 Flash, Gemini 3.1 Pro and Gemini 3.1 Flash Lite preview models are now available when you choose a model for a task. Each Gemini model offers both a European and a global region option. Model names in the selector are easier to read, and flows that use an older model name keep working with no changes needed. **Improved** * Bounding-box extraction now also works with Gemini 2.5 Flash and Gemini 2.5 Flash Lite, so you have more model choices for locating extracted values on the page. Extraction also handles more model response formats, including a separate location for each value in multi-value fields, so results are more consistent. * Reviewing work is smoother. In the work queue, an Unsaved changes indicator appears next to Complete work, you're asked to confirm before leaving an item with unsaved edits, and Complete work takes you straight to the next item. Key-value pairs you add show up in the task output right away, and the Review tab's task selector now shows full task names. ## Save edits, auto-rerun stale tasks, and find any task fast in Flow View Review now shows clearly which results were edited and which are out of date, and can re-run affected tasks for you automatically. Flow View, templates, flow versions and run filters also get easier to work with. **New** * A task result can now be marked as both edited and stale, so you can see at a glance which outputs were changed by hand and which are out of date because something upstream changed. You can also filter the data table by Edited. On the review page you save corrections with a Save button, you're asked before leaving with unsaved edits, and hovering the Edited banner shows when the task was edited. * Turn on the new Auto-rerun downstream stale tasks setting for a flow and, when you update a task's output, the tasks that depend on it re-run on their own. You no longer need to track down and restart each affected task after a correction. * In Flow View, select any task to highlight its connections while the rest of the flow fades back, and use task search to jump straight to the task you need. Results are ordered by where tasks sit in the flow, and large flows with many tasks stay smooth and responsive as you work. * Give flow versions your own names, star the ones you use most and switch on the Favourites filter to see only those, and search versions by name to find the right one quickly. The version list now shows the email of the person who last modified each version. * Add your own tags to flows and use them to search and filter your flow list, so you can organise flows by team, customer process or project. * The template library has a My Templates tab, tag filters and tags on every template card. You can edit the name, description, tags and visibility of templates you created, and delete your own templates when you no longer need them. **Improved** * Filter runs by the status of individual tasks and exclude runs with specific tags, making it easier to find exactly the runs you need to look at. Saved views keep their filters, the status column in the runs table is wider and resizable, and the app now consistently uses the word Run. * Data table cells are cleaner and easier to read: hovering a cell shows a redesigned card with type icons and a table view for lists of values, and tags, file attachments and status badges show their details in tooltips. Run tags appear on hover in review, all tags share one consistent look, and every task status cell opens its details with a click. * My Work now has its own dedicated pages: a work queue for each flow and a focused page for each work item, and inbox links take you straight there. When you open a task that is still waiting for a worker, you see a clear Waiting for Worker status. Workers and reviewers with no flows assigned yet see a dedicated empty state with a quick refresh link. * Classifying and splitting multi-page documents is faster because pages are now classified in parallel. Page rotation is more reliable at turning sideways or upside-down pages upright, and it can reuse the page angles detected during text extraction to skip extra processing. * Your layout choices, such as cards or list view for your flows, the sidebar state and collapsed templates, are now remembered across sessions and devices. * Every task type now has its own distinct icon, and integration cards show a matching icon when no logo is available. You can also ask for a missing integration directly from the integration catalog with the Request Integration button. * Large flows with many tasks now run noticeably faster, thanks to smarter reuse of intermediate results while a run is in progress. **Fixed** * File URLs for split documents and split text in flow outputs can now be downloaded through the file download endpoints. → [Downloading Files](/guides/downloading-files) ## Save flows explicitly, restore past versions, and route review to teams Flows now have explicit saving with a full version history you can restore from, and Human In The Loop tasks can be assigned to whole teams. Run tables, filters and review pages also got a round of upgrades. **New** * Flows now have version history. Open it from the flow menu to view past versions and restore any of them. Changes are saved when you choose to save, with live validation as you edit, and if you leave with unsaved edits you can recover them when you come back. Moving tasks around on the canvas doesn't create a new version. * Admins can now create teams and assign Human In The Loop tasks to a whole team instead of a single person. When a team member starts a task it becomes theirs, and if it is left unfinished it goes back to the team for someone else to pick up. Teams and their members are managed from the new Teams tab in Admin settings. * When you duplicate a flow that receives input from email, cloud storage, SFTP or an integration, you now see which tasks are affected and choose whether to clone the flow as-is or reset their input settings. This keeps a copy from accidentally picking up documents meant for the original flow. * Image rotation tasks have their own review page showing the source and output documents side by side. You can rotate PDFs and images by 90 degrees right from the review screen and the corrected document is saved as the task output. * Tasks and their parameters now show built-in help tooltips in the flow builder, so you can see what each setting does without leaving the page. **Improved** * Filter flow runs by task name or look one up by its exact execution ID. When a task is selected, the tag list narrows to the tags used on that task, which makes it quicker to find the runs you need. * The table view of flow runs shows more at a glance. Each run number carries a count of failed tasks and a marker for cancelled runs, tags appear on each task execution with a count badge, and edited task outputs are marked as edited. From the hover card you can add or remove tags, confirm or unconfirm a task output, and see the details of whichever execution you are viewing. * Human Review tasks are now called Human In The Loop tasks, and task search matches display names as well as task types. Your work list no longer shows tasks from cancelled runs, and if a task becomes unavailable while you're on it, you're taken straight to the next item. * Flow views can now be removed as the default, and default views are listed first so your main view is always easy to find. * The integrations page has a new sidebar with categories and per-category counts for easier browsing. You can also open the integrations catalog straight from the Add Task panel to explore what's available. **Fixed** * If an invitation link has expired, requesting a new one from the sign-in screen now sends a fresh invitation that works right away. ## Give reviewers context, build custom Runs views and draw to fill table cells Review tasks now carry messages that point reviewers to what matters, and a Work completed badge shows when work is done. You can also draw directly on the document to fill table cells, build your own Runs views, see at a glance which runs are awaiting a reviewer, and save any flow as a template. **New** * Give every task in your flow a description: choose Edit description from the task's menu and type it inline. In a Human Review task, you can pick the validations that matter most, and if one of them doesn't pass, its description appears as a message on the reviewer's screen, so reviewers know exactly what to look at. * Create custom Runs views alongside your table views, with a column set built for runs and one-click copying of run IDs. The Files column in the runs table is now called Input, and setting a view as the default is labelled Set as Default for Everybody so it is clear who it affects. * When reviewing extracted tables, click into a cell and draw a box around text in the document to fill that cell. Click a table's name to open it side by side with the document; your selected table and column widths are remembered as you move between tasks and runs, and tables with only a few columns now fill the panel. * Set vectorization parameters on a task: choose a source task and decide for each output whether it is used as a single value or as a collection. This gives you control over how a task fans out across items and how results are gathered for the tasks that follow. * Save any flow as a template from the new Template tab in the Share dialog, with a name, description, tags and who can see it. Start new flows from your saved templates in the Flow hub, where you can browse and search them. **Improved** * Code tasks use a new code editor with Python syntax highlighting, and typing # suggests references to other tasks in your flow. Your code keeps its indentation and formatting exactly as you write it, and Tab and Shift+Tab indent and outdent lines. * Completed review tasks show a Work completed badge in the task header. Click Info on the badge to open the task's details, where you can see who completed the work. * My Work is always available to reviewers and shows a clear message when nothing is assigned yet. Work mode makes it obvious when you're viewing a task outside your queue, takes you back to My Work after you finish a single item, and keeps your edits and cursor in place while you review. * Runs that are waiting on a person now show an amber Awaiting Worker status and return to Processing as soon as the review is done, so you can see at a glance which runs need someone's attention. * SFTP tasks let you give folder mappings a display name, fill in the name automatically when you pick a folder, and rename items in place by clicking their title. Folder browsing shows each folder once as you navigate. * When building JSON in a task, you can choose a Reference value type that pulls in the referenced value from earlier tasks, and fields save smoothly as you type. * The MCP server now exposes the full public API as tools, so AI agents connected over MCP can do everything the public API supports, authenticated with your API key. → [MCP Server](/api-reference/mcp-server) **Fixed** * Flow invitation emails now link each invitee to the right place for their role. ## Filter My Work, pick worker landing pages, and connect agents over MCP Workers get a clearer daily flow, with filtering and sorting in My Work, a landing page chosen by their admin, and guidance as they work through their queue. Runs show their status at a glance, and AI agents can now build and edit flows in SuperAI Flows through the new MCP server. **New** * Connect Claude Code, Claude Desktop or any other MCP-compatible client to SuperAI Flows through the new MCP server. Using a service account API key, your agent can browse the available task types, create flows, read and update flow definitions, and generate file download links, so you can build workflows from the assistant you already use. → [MCP Server](/api-reference/mcp-server) * Admins can choose where workers land after signing in: the Hub, or the Data or Work tab of their most recently active assigned flow. Set it once under Admin Tools > Worker Entry Customization, and workers go straight to their work (they land on the Hub when nothing is waiting). * My Work now has filters and sorting. Narrow your tasks by tags or metadata, sort by created or updated time, and by default the longest-waiting tasks come up first. * Task Details now shows a clear explanation when a task needs attention: the task name and the exact message, with one-click options to re-run it, open the flow setup, or, in Work mode, skip to the next task. **Improved** * Work mode guides workers through their queue. A banner tells you when a task isn't part of your work queue or who already completed it, Confirm can now be undone with Unconfirm, and an All done! dialog takes you back to My Work when you finish. Results submitted for a task are checked against the output fields your flow defines, so mismatched values are flagged right away. * The Reviewer role is now called Worker across the app, invitations and emails, and what each role can do is clearer: creating and deleting tags follows the user's role permissions. * Runs now show their status in a dedicated column, in both the data view and the runs view. In the data view, clicking any task cell, even one still running or skipped, opens its details. In the runs view, tags take you to the related task, with a short list to pick from when a tag appears on several tasks. The selection bar now offers View Task Details and shows Cancel only for runs that can still be cancelled. * Tables are easier to work with. Run number and status stay pinned on the left as you scroll, an optional Execution ID column in the data view lets you copy IDs with one click, and Flow ID, Execution ID and other details in Task Details can be copied from the side panel. * Re-running flows with human review steps is smoother. Each re-run starts with fresh review tasks, you'll see a notice if a review task you had open was replaced by a re-run, and tasks waiting on people now read Waiting for worker. * Python code tasks can do more. You can now import requests to call external APIs, magic to detect file types, and io to work with in-memory files, so a single code step can fetch, inspect and send data. * The JSON builder handles arrays of structured items. Define an item schema, nest arrays and objects, choose a type per item, and expand or collapse nested fields while you build. ## Work through review items in My Work and cancel runs you no longer need A new My Work tab and work mode let reviewers move through their assigned items one after another, and you can now cancel runs that are in progress. Data views get pinned and resizable columns, runs can be filtered by metadata, and your credit balance now shows your monthly allowance and additional credits separately. **New** * Cancel runs that are still in progress with the new Cancel button, available to users with the right permission. Cancelled runs are clearly marked with their own status and a neutral row style in your tables, so you can tell them apart from completed or failed runs at a glance. * The new My Work tab lists the review items assigned to you. Select items and enter work mode to step through them one by one: when you finish an item you move straight to the next open one, completed items stay done, and a banner shows the email of any other reviewer working on the same item so you don't duplicate effort. * Filter runs by the metadata collected with your uploaded files. Pick from the metadata keys and values already used in the flow and select several values per filter to narrow the runs view to exactly the runs you need. * Usage is now measured in credits. Your balance shows your monthly plan allowance, with its reset date, separately from any additional credits, so it's easy to track what you have left. Run and task details returned by the API now include the credits each one consumed. * You can now reference the entire output of a previous task in a task's configuration, not just individual fields, right from the reference picker. A new Transform task passes referenced data on to the next steps of your flow. **Improved** * Data views are easier to shape around your work. Pin task columns to the left or right, drag to resize columns, and have both saved with the view. The Runs view can now be chosen as your default, and switching between views keeps filters, counts and layout in step with the view you picked. * Bulk actions in the runs table now show how many rows you have selected, for example Re-run (4) or Cancel (4), so you always know how many runs an action will affect. * Reviewing is smoother. A flow can open its review in a custom view you choose, review screens share a consistent set of actions such as Re-run and Go to flow editor, and each state has its own clear empty screen. The inbox now says New work item and links directly to the item or your work queue. * Tags in the review view have a new design: search the tags available in your flow, create a new one inline, and get a confirmation each time a tag is added or removed. * Setting up SFTP tasks is easier. Browse and pick folders from a folder tree that loads as you expand it, see how many files a folder contains before you process it, and choose from dropdowns with clear labels. * SFTP, Google Drive and SharePoint tasks now show their recognizable logos on the canvas, and SharePoint receive results can be opened in the review screen. * When the AI builds a flow for you, it now gives each task a short title that describes its role, so your flow is easier to read in the editor and in your results. * Starting a run with input that doesn't match the flow now returns a clear validation error right away, listing what to fix, and no run is created. → [Error Codes](/api-reference/errors) ## Build and parse JSON in flows, and pull files from SFTP folders Two new task types let you extract fields from JSON and build structured JSON inside a flow, and a new SFTP integration watches your folders and starts a flow for each file. Flow tables also get saved filters and sorting, tag filters, and faster browsing of long flow lists. **New** * Two new JSON tasks are available in the flow builder. The extraction task reads JSON input and pulls out the fields you choose, including nested paths, with type conversion and a strict or lenient mode. The construction task builds structured JSON from a schema you define, with nested objects and arrays and a live preview, so you can shape output for downstream systems without custom code. * A new SFTP integration watches one or more folders on your SFTP server and starts a flow for each file that arrives. Once a file is processed, it's moved to a folder you choose or deleted. When you add SFTP credentials, pick password or SSH key under Authentication Method. * You can now re-run a run's tasks without leaving the Review tab. The task selector shows which tasks need attention and updates as the run progresses, and a Re-run all tasks option sits in the same menu. When the task you're reviewing is out of date, a Re-run link refreshes it in place. * Custom views on a flow now save their filters and sort order along with the columns. Use the new Sort and Filter controls on the flow table, including filtering runs by any task tag used in the flow, and the view opens exactly as you left it next time. * Manage service accounts and their API keys from the web app. You can rename a service account, edit an API key's name and description, and delete individual keys or the whole account from per-row Edit and Delete actions. Deleting a service account also revokes its API keys. → [Authentication](/api-reference/authentication) **Improved** * The flows list now loads 20 flows at a time with a See More button, and search and sorting by created or updated date now work across all of your flows. Workspaces with many flows open noticeably faster. * You can now edit saved integration credentials. The edit form opens with the credential's name and authentication type already selected, so you can update a password, key or secret without recreating the credential. * The runs table has a new Metadata column that shows the metadata attached to each run's incoming file. Hover over it to see every value and who last changed it, and tags now appear as consistent badges. **Fixed** * Renaming and reordering tasks in a flow now saves as expected. ## Review runs in batches and connect SharePoint to your flows Human review gets a dedicated flow: select runs and review them in a batch, with task details and instructions alongside. SharePoint is now available as an integration, and the inbox groups your review tasks by flow. **New** * Review runs in batches. When a flow includes a human review step, the runs list shows each run's review status, and you can select runs and choose Review to work through the ones waiting for you. A bar at the top shows that a review is in progress and lets you exit at any time, and Finish Review submits each review and takes you to the next run in your selection. * Connect SharePoint to your flows. Add a SharePoint integration from the integration catalog, either by signing in with Microsoft or with your app's tenant ID, client ID and client secret, and give it a name of your choice. Flows can then receive files from the SharePoint site, library and folder you pick. **Improved** * Select See task details during a review to open a side panel with two tabs, Notes and Instructions and Metadata. Metadata shows when the task ran and was reviewed and how long it took, so you have the context for a decision without leaving the review. * Your inbox now groups tasks by flow in collapsible sections with a count for each flow. Each task shows which step needs review, a status indicator and when it was created, and you can jump straight to it with Review item or open the flow's runs with Review overview. * Copy values with one click. Webhook payloads and text form fields now have copy buttons, joining API keys and task outputs, and every copy button confirms when the value is on your clipboard. * Zoom documents up to 500 percent while you review them, and remove tags you no longer need. Viewer controls now show clearer icons and labels that adapt to your screen size. * Reviews now keep themselves tidy when you step away. After 15 minutes in a review you're asked whether to continue or exit, and after 30 minutes the review closes and returns you to the flow's runs so the item is free for someone else. * Integrations show clear, readable names throughout the catalog, forms and dialogs, and Google Drive now appears with its own logo. * Text fields marked read-only in a task's schema, such as the auto-generated address of a Receive Email task, now appear as read-only in forms. The flow menu now reads Copy flow definition and Import flow definition, and each page of the web app follows the permissions of your role. * Flow execution lists now sort the same way everywhere, with the most recently started runs first by default, and live updates keep your chosen sort order, filters and page size as new runs arrive. The List flow executions API now also sorts by creation time by default. * The interactive API reference is now at /api/docs and /api/redoc, and the OpenAPI specification at /api/openapi.json, covering the full public API. If you load the specification from /openapi.json, switch to the new path. **Fixed** * Text files saved with a UTF-8 byte order mark (BOM) are now fully supported. # Downloading Files Source: https://docs.flows.super.ai/guides/downloading-files Download files from gs:// URLs returned in your flow execution outputs. When SuperAI Flows processes documents, task outputs often include file references as `gs://` URLs. These point to files stored in Google Cloud Storage, but you don't need to understand GCS internals — the File API handles everything. Example `gs://` URL in a task output: ```json theme={null} { "document_url": "gs://superai-file-upload-prod-eu/flows/255a17d0-5c21-47d9-8e0b-a08b48436f0a/documents/f8230da2-4136-4ffb-acfe-db9318970ea2" } ``` ## Prerequisites * **curl** — for making HTTP requests * **jq** — for parsing JSON in shell scripts (optional, but recommended) * **A SuperAI Flows API key** — get one from the dashboard under **Settings → API Keys** ## Quick start Download a file in one command: ```bash theme={null} curl -f -L -H "X-API-Key: saf_your_api_key" \ "https://flows.super.ai/api/files/download?uri=gs://superai-file-upload-prod-eu/flows/255a17d0-5c21-47d9-8e0b-a08b48436f0a/documents/f8230da2-4136-4ffb-acfe-db9318970ea2" \ -o downloaded_file.pdf ``` * The `-L` flag tells curl to follow the redirect to the actual download URL. * The `-f` flag makes curl fail with an error instead of saving error responses as your file. ## Authentication Both file endpoints require authentication. You can use either method: | Method | Header | Example | | - | - | - | | **API Key** (recommended) | `X-API-Key` | `X-API-Key: saf_abc123...` | | **JWT Token** | `Authorization` | `Authorization: Bearer eyJhbGci...` | About API keys: * API keys start with the `saf_` prefix (e.g., `saf_org_550e8400_abc123...`). * Get your API key from the dashboard under **Settings → API Keys**. * Store keys in environment variables — never hardcode them in scripts. About JWT tokens: obtained by authenticating with your email and password. See the [API Quickstart](/quickstart#authentication). Tokens expire after 1 hour and must be refreshed. ## Two ways to download ### Option 1: Direct download (GET) Use `GET /api/files/download` for the simplest approach. This endpoint redirects you to a temporary signed URL. ```bash theme={null} curl -f -L -H "X-API-Key: $SAF_API_KEY" \ "https://flows.super.ai/api/files/download?uri=gs://bucket/path/to/file" \ -o output_file.pdf ``` If your URI contains special characters, URL-encode it first: ```bash theme={null} ENCODED_URI=$(printf '%s' "$GS_URL" | jq -sRr @uri) curl -f -L -H "X-API-Key: $SAF_API_KEY" \ "https://flows.super.ai/api/files/download?uri=$ENCODED_URI" -o file.pdf ``` | Parameter | Required | Description | | - | - | - | | `uri` | Yes | The `gs://` URL from your task output (URL-encoded) | | `redirect` | No | Set to `false` to get JSON instead of a redirect (default: `true`) | **Response:** 302 redirect to a pre-signed download URL (valid for 1 hour). ### Option 2: Resolve URL first (POST) Use `POST /api/files/resolve` when you need the download URL for further processing or want to keep URIs out of server logs. ```bash theme={null} curl -X POST "https://flows.super.ai/api/files/resolve" \ -H "X-API-Key: $SAF_API_KEY" \ -H "Content-Type: application/json" \ -d '{"uri": "gs://bucket/path/to/file"}' ``` ```json theme={null} { "download_url": "https://storage.googleapis.com/bucket/path/to/file?X-Goog-Algorithm=...", "expires_at": "2025-01-15T15:00:00+00:00", "expires_in_seconds": 3600 } ``` Then download using the returned URL: ```bash theme={null} curl -o output_file.pdf "https://storage.googleapis.com/bucket/path/to/file?X-Goog-Algorithm=..." ``` ## Complete example: download after flow completion This script executes a flow, waits for completion, and downloads any output files: ```bash theme={null} #!/bin/bash set -e # Configuration — use environment variables for API key API_KEY="${SAF_API_KEY:-saf_your_api_key}" FLOW_ID="your-flow-id" BASE_URL="https://flows.super.ai" MAX_ATTEMPTS=60 # 5 minutes timeout (60 * 5 seconds) # 1. Create flow execution echo "Starting flow execution..." EXEC_RESPONSE=$(curl -s -X POST "$BASE_URL/api/flow-executions" \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d "{ \"flow_id\": \"$FLOW_ID\", \"input\": { \"filename\": \"invoice.pdf\", \"mime_type\": \"application/pdf\", \"document_url\": \"https://cdn.super.ai/invoice-example.pdf\" } }") EXEC_ID=$(echo "$EXEC_RESPONSE" | jq -r .id) if [ "$EXEC_ID" = "null" ] || [ -z "$EXEC_ID" ]; then echo "Failed to create execution. Response: $EXEC_RESPONSE" exit 1 fi echo "Execution started: $EXEC_ID" # 2. Wait for completion ATTEMPT=0 while [ $ATTEMPT -lt $MAX_ATTEMPTS ]; do STATUS=$(curl -s "$BASE_URL/api/flow-executions/$EXEC_ID" \ -H "X-API-Key: $API_KEY" | jq -r .status) echo "Status: $STATUS (attempt $((ATTEMPT + 1))/$MAX_ATTEMPTS)" if [ "$STATUS" = "completed" ]; then break elif [ "$STATUS" = "failed" ]; then echo "Execution failed!"; exit 1; fi ATTEMPT=$((ATTEMPT + 1)) sleep 5 done # 3. Get task outputs RESULTS=$(curl -s "$BASE_URL/api/task-executions?flow_execution_id=$EXEC_ID" \ -H "X-API-Key: $API_KEY") # 4. Download any gs:// URLs from the output (requires jq) echo "$RESULTS" | jq -r '.. | select(type == "string" and startswith("gs://"))' 2>/dev/null | while read -r GS_URL; do if [ -n "$GS_URL" ]; then FILENAME=$(basename "$GS_URL") ENCODED_URI=$(printf '%s' "$GS_URL" | jq -sRr @uri) if curl -f -L -H "X-API-Key: $API_KEY" \ "$BASE_URL/api/files/download?uri=$ENCODED_URI" -o "$FILENAME"; then echo "Downloaded: $FILENAME" else echo "Failed to download: $FILENAME" fi fi done echo "Done!" ``` ## Error handling | Status | Description | Common causes | | - | - | - | | 400 | Bad Request | URI doesn't start with `gs://`, malformed URI, path traversal attempt | | 401 | Unauthorized | Missing or invalid API key / token | | 403 | Forbidden | File belongs to a different organization, invalid bucket | | 404 | Not Found | Flow doesn't exist, you lack access, or the file was deleted from storage | | 500 | Server Error | Internal error generating download URL | Example error response: ```json theme={null} { "error": { "message": "Access denied: you do not have access to this file", "code": "forbidden" }, "request_id": "01K8KABR6S16YETA2SZPVBS9SP" } ``` Include the `request_id` when contacting support for faster resolution. Always use `-f -L` with curl on the GET endpoint: `-L` follows the redirect to the actual download URL, and `-f` makes curl return a non-zero exit code on HTTP 4xx/5xx errors instead of silently saving an error response as your output file. ## Security * **Organization-scoped access** — You can only download files from flows your organization owns. * **Temporary URLs** — Pre-signed download URLs expire after 1 hour. * **Path validation** — The API rejects path traversal attempts. * **Bucket validation** — Only files from the authorized storage bucket can be accessed. For sensitive files, prefer `POST /api/files/resolve` to keep URIs out of server access logs. ## FAQ Currently only `gs://` URIs (Google Cloud Storage) are supported. Pre-signed URLs are valid for **1 hour**. Request a new URL if your download fails after this time. No. You can only download files from flows that belong to your organization. No — pass the full URI exactly as received from the task output. Use `GET /api/files/download` for simple downloads with curl. Use `POST /api/files/resolve` when you need the URL for programmatic use or want to keep URIs out of logs. Need help? Email [support@super.ai](mailto:support@super.ai) and include your `request_id` and flow ID. # Introduction Source: https://docs.flows.super.ai/index 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. # API Quickstart Source: https://docs.flows.super.ai/quickstart Start processing documents with SuperAI Flows in under 5 minutes — authenticate, run your first workflow, and retrieve results. This guide shows you how to authenticate, run your first workflow, and retrieve results. ## Process a document in 60 seconds Run this single script to authenticate, create a flow, and process your first invoice: ```bash theme={null} # 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", "data_type": "string", "instructions": ""}, {"id": "total", "title": "total", "data_type": "float", "instructions": "identify the total amount"}, {"id": "account_owner", "title": "Account Owner", "data_type": "string", "instructions": "Identify the account owner"} ], "worker": "gpt-4.1", "input_data": "{{d61f3643-52d9-4ff3-bee7-7a3e26ca013f.page_contents}}", "document_url": "{{d61f3643-52d9-4ff3-bee7-7a3e26ca013f.document_url}}", "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}}" } } ] } }] } }') 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 "View results: https://flows.super.ai/flows/$FLOW_ID?view=data" ``` 1. **Authenticated** with your SuperAI account. 2. **Created a 4-task invoice processing flow**: Receive File → Convert to Text → Extract Invoice Data → Validate. 3. **Started processing** a sample invoice PDF. 4. Got back a flow ID and execution ID to track progress. Check the dashboard link to watch your flow process the document. Got an error? Jump to [Troubleshooting](#troubleshooting). ## What are SuperAI Flows? SuperAI 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 ## Flow definition example Flows are defined in declarative YAML that's both human-readable and type-safe. Here's a complete document processing workflow: ```yaml theme={null} 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 a `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 * A SuperAI account ([sign up free](https://flows.super.ai)) * Your login email and password * `curl` and `jq` installed (for testing examples) ## Authentication SuperAI uses JWT-based authentication. All API requests require a valid access token. This is a public endpoint — no auth required. ```bash theme={null} curl https://flows.super.ai/api/auth/anon-key ``` ```json theme={null} { "anon_key": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` ```bash theme={null} 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"}' ``` ```json theme={null} { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 3600, "token_type": "bearer" } ``` ```bash theme={null} 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 | Tokens grant full account access — treat them like passwords. Store them in environment variables or secret managers, never in code, and always use HTTPS. When your access token expires, use the refresh token to get a new one without re-authenticating: ```bash theme={null} 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 Start a flow by creating a flow execution with your input data. ```bash theme={null} 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" } }' ``` ```json theme={null} { "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" } ``` 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 the flow is updated) The input object structure depends on your flow's configuration. For file-based flows, provide `filename`, `mime_type`, and `document_url`. Other flows may have different input schemas — check the flow's `input_schema`. ### Check execution status ```bash theme={null} curl "https://flows.super.ai/api/flow-executions/df77dc65-909b-430e-bff1-9e9ecf315a80" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ```json theme={null} { "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: ```bash theme={null} curl "https://flows.super.ai/api/task-executions?flow_execution_id=df77dc65-909b-430e-bff1-9e9ecf315a80" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ```json theme={null} { "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. 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 payload: ```json theme={null} { "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 } } } } ``` Your webhook endpoint should validate the authorization header (if provided via the `x-webhook-token` header), process the payload, and return a 2xx status code to acknowledge receipt. ## Troubleshooting * Verify your credentials work in the web UI first at [flows.super.ai](https://flows.super.ai). * Check for special characters in your password; wrap it in single quotes to preserve them: `export PASSWORD='your-password'`. * Verify the anonymous key is valid — it should be a long JWT string. * Verify the flow was created successfully (check the flow creation response). * List all flows you have access to: `curl https://flows.super.ai/api/flows -H "Authorization: Bearer $TOKEN"`. * Confirm you're using the correct UUID and are logged into the correct organization — flows are organization-specific. Your token expired after 1 hour. Use the refresh token to obtain a new access token (see [Authentication](#authentication)). * Validate your JSON is well-formed (pipe it through `jq`). * For custom flows, check the required input schema: `curl "https://flows.super.ai/api/flows/$FLOW_ID" -H "Authorization: Bearer $TOKEN" | jq .input_schema`. Some flows take minutes for complex documents. Use webhooks instead of polling, and inspect task executions to 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}'`. The API implements fair-use rate limiting. If you receive 429 (Too Many Requests), wait before retrying and implement exponential backoff. Still stuck? Check [status.super.ai](https://status.super.ai), then contact [support@super.ai](mailto:support@super.ai) with your flow execution ID and the `request_id` from any error responses. ## 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) | Errors follow a consistent format. See the full [Error Codes reference](/api-reference/errors). ```json theme={null} { "error": { "code": "not_found", "message": "Flow not found" }, "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8" } ``` ## Next steps Retrieve `gs://` files returned in your flow outputs. Full endpoint documentation with schemas.