Super.AI

SuperAI Flows is a workflow orchestration platform that enables you to design, deploy, and monitor automated workflows at scale.

Build complex workflows using our declarative YAML DSL, execute them reliably with Temporal.io, and integrate seamlessly with AI models, cloud storage, and enterprise systems.

**Key Capabilities:**
- **Workflow Management**: Define workflows as code with version control and automated execution
- **Task Orchestration**: Chain together API calls, data processing, and AI operations
- **Real-time Monitoring**: Track execution progress with WebSocket notifications and comprehensive logging
- **Multi-tenant Architecture**: Organization-scoped resources with role-based access control

**API Versioning and Breaking Changes:**

We follow a strict compatibility policy to ensure your integrations remain stable:

- **Non-breaking changes** (safe, no action required):
  - Adding new API endpoints
  - Adding new optional query parameters to existing endpoints
  - Adding new fields to API responses
  - Adding new values to existing enums

- **Breaking changes** (requires client updates):
  - Removing or renaming API endpoints
  - Removing query parameters or request fields
  - Removing response fields
  - Changing field types or validation rules
  - Removing values from existing enums

**Client Implementation Requirements:**

Your API clients MUST be designed to gracefully handle additional fields in responses. We may add new fields to any response object without considering this a breaking change. Ensure your JSON parsers ignore unknown fields rather than raising errors.

**Backward Compatibility Guarantee:**

We commit to maintaining backward compatibility for all non-breaking changes. Breaking changes will be:
- Announced at least 15 days in advance
- Documented in our changelog with migration guide

For the latest API updates and migration guides, see our changelog.

SuperAI Flow Platform

Administrative operations for managing users and organizations.

Admin endpoints provide comprehensive user and organization management capabilities for platform administrators. These operations are restricted to users with administrative privileges and enable the core tenant management functionality of the platform.

**Key concepts:**
- **Organizations**: Top-level tenants that contain users and isolate data
- **Users**: Individual accounts with roles and permissions
- **Roles**: Define access levels (org_admin, backoffice, member, etc.)
- **Status**: Track account state (active, inactive, suspended)

**User management features:**
- Create and provision new user accounts
- Update user profiles and roles
- Manage user status and access
- Link users to organizations
- Sync with authentication system

**Organization management features:**
- Create and configure organizations
- Update organization settings and metadata
- Manage organization status
- View organization users and resources

**Use these endpoints to:**
- Onboard new organizations and their initial users
- Manage user roles and permissions across the platform
- Deactivate or reactivate user accounts
- Update organization and user information
- Perform bulk administrative operations

Admin endpoints are the control plane for multi-tenant platform management and user lifecycle operations.

admin

Retrieve all organizations across the entire platform.

Returns a complete list of all organizations in the system, regardless of
active status. Use this for administrative oversight, reporting, and
organization management tasks.

Context:
    - Returns both active and inactive organizations
    - Includes organization metadata (creation date, modification date)
    - Each organization represents an isolated tenant in the system
    - Organizations are the top-level entity for user and flow grouping
    - No pagination implemented yet (suitable for < 1000 organizations)

Behavior:
    1. Queries all organizations from database
    2. Orders results by creation date (newest first)
    3. Returns complete list without filtering

Performance Notes:
    - Current implementation loads all organizations in memory
    - Suitable for platforms with < 1000 organizations
    - For larger datasets, pagination should be implemented

Use Cases:
    - Admin dashboard showing all organizations
    - Organization management interfaces
    - Reporting and analytics on organization count
    - Audit and compliance reviews

Related Endpoints:
    - POST /admin/organizations - Create new organization
    - GET /admin/organizations/{id} - Get single organization details
    - PATCH /admin/organizations/{id}/deactivate - Deactivate organization

List all organizations

Create a new isolated tenant organization.

Each organization acts as a data boundary with its own users, flows, and
executions. Organizations are the top-level entity for multi-tenancy and
access control.

Context:
    - Organizations are created in active state by default
    - Each organization gets a unique UUID identifier
    - Organization names must be unique across the platform
    - New organizations start with no users (add users separately)
    - Organization isolation ensures data cannot leak across tenants
    - Creation timestamp tracked for audit purposes

Behavior:
    1. Validates organization name is unique
    2. Creates organization record in database
    3. Generates UUID identifier
    4. Sets timestamps for creation and modification
    5. Returns created organization with all metadata

Use Cases:
    - Onboarding new customer or department
    - Creating sandbox/test organizations for development
    - Setting up multi-tenant environments
    - Organization provisioning via automated workflows

Related Endpoints:
    - GET /admin/organizations - List all organizations
    - PUT /admin/organizations/{id} - Update organization details
    - POST /admin/organizations/{id}/users - Add users to organization
    - DELETE /admin/organizations/{id} - Delete organization

Create new organization

Permanently delete an organization and all associated data.

This endpoint performs a hard delete of the organization and ALL related
entities including users, flows, executions, and task data. This operation
is IRREVERSIBLE. For temporary deactivation, use PATCH /deactivate instead.

Context:
    - HARD DELETE: Data is permanently removed from database
    - Cascades to all related entities (users, flows, executions, tasks)
    - Cannot be undone - use with extreme caution
    - Recommended to deactivate first and delete only after confirmation
    - Running workflows may fail if organization is deleted
    - For data retention compliance, consider soft delete via deactivate
    - No response body returned (204 No Content status)

Behavior:
    1. Validates organization exists by ID
    2. Checks for foreign key constraints
    3. Deletes all related entities in order:
       - User records
       - Flow definitions
       - Flow executions
       - Task outputs
       - Task statuses
    4. Deletes organization record
    5. Returns 204 No Content
Use Cases:
    - Remove test/sandbox organizations after development
    - Comply with GDPR "right to be forgotten" requests
    - Clean up organizations created by mistake
    - Decommission organizations with no production data
    - Automated cleanup of expired trial organizations

Safer Alternative:
    For reversible deactivation, use:
    PATCH /admin/organizations/{id}/deactivate

Related Endpoints:
    - PATCH /admin/organizations/{id}/deactivate - Soft deactivation (recommended)
    - GET /admin/organizations/{id} - Verify organization before deletion
    - GET /admin/organizations/{id}/users/count - Check user count before delete

Delete organization

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
    - Useful for verifying organization exists before user creation
    - Response includes audit timestamps

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:
    - Verify organization exists before creating users
    - Check organization active status
    - Retrieve organization name for display purposes
    - Validate organization ID from external systems
    - Pre-operation existence checks

Related Endpoints:
    - GET /admin/organizations - List all organizations
    - PUT /admin/organizations/{id} - Update organization
    - GET /admin/organizations/{id}/users - List organization users
    - GET /admin/organizations/{id}/users/count - Count organization users

Get organization by ID

Update organization properties with partial update support.

This endpoint allows modification of organization name and active status.
All fields are optional, enabling partial updates where only specified
fields are changed. Useful for renaming organizations or toggling active status.

Context:
    - Supports partial updates (only provided fields are updated)
    - Organization ID cannot be changed (immutable identifier)
    - Name uniqueness validated if name is being updated
    - Updating is_active affects user login ability
    - Timestamps automatically updated on modification
    - For deactivation with cascade, use PATCH /deactivate endpoint instead

Behavior:
    1. Validates organization exists by ID
    2. Checks name uniqueness if name is being updated
    3. Applies only the provided field updates
    4. Updates modified_at timestamp
    5. Persists changes to database
    6. Returns updated organization
Use Cases:
    - Rename organization after company rebrand
    - Temporarily disable organization access (set is_active=False)
    - Re-enable previously disabled organization (set is_active=True)
    - Correct typos in organization names
    - Bulk organization updates via automation

Related Endpoints:
    - GET /admin/organizations/{id} - Retrieve current organization state
    - PATCH /admin/organizations/{id}/deactivate - Deactivate with user cascade
    - POST /admin/organizations - Create new organization
    - DELETE /admin/organizations/{id} - Delete organization

Update organization

Deactivate organization and cascade deactivation to all associated users.

This endpoint performs a cascading deactivation that marks the organization
as inactive AND deactivates all users belonging to the organization. This is
different from PUT with is_active=False, which only affects the organization.
Use this for offboarding customers or suspending organization access.

Context:
    - Sets organization is_active to False
    - Cascades deactivation to all organization users
    - Deactivated users cannot log in or access the system
    - Does NOT delete data (soft deactivation for audit trail)
    - Does NOT stop running workflows (they complete normally)
    - Deactivation can be reversed by setting is_active=True via PUT
    - All flow executions and data remain intact

Behavior:
    1. Validates organization exists by ID
    2. Sets organization is_active to False
    3. Queries all users in the organization
    4. Sets each user's status to inactive
    5. Updates organization modified_at timestamp
    6. Persists all changes to database
    7. Returns updated organization
Side Effects:
    - All users in organization immediately lose access
    - Users cannot log in after deactivation
    - Running workflows continue but new executions cannot be created
    - Organization no longer appears in active organization lists
    - WebSocket connections for deactivated users may be terminated

Use Cases:
    - Customer offboarding or subscription cancellation
    - Temporary suspension due to payment issues
    - Compliance requirement to disable organization access
    - Security incident response (immediately disable all access)
    - Decommissioning departments or teams

Reactivation:
    To reactivate, use PUT /admin/organizations/{id} with is_active=True
    Note: User reactivation must be done individually after org reactivation

Related Endpoints:
    - PUT /admin/organizations/{id} - Reactivate organization
    - GET /admin/organizations/{id}/users - View affected users
    - GET /admin/organizations/{id} - Check deactivation status
    - DELETE /admin/organizations/{id} - Permanently delete organization

Deactivate organization

Retrieve all users belonging to a specific organization.

This endpoint returns a complete list of users within an organization,
including the organization name for each user. Use this to manage organization
membership, audit user access, or populate organization user interfaces.

Context:
    - Returns users regardless of their active/inactive status
    - Includes organization name in each user response for convenience
    - Users are ordered by creation date (newest first)
    - Each user includes full profile information and role
    - Organization must exist (404 if not found)
    - No pagination implemented yet (loads all users in memory)

Behavior:
    1. Validates organization exists by ID
    2. Queries all users with matching organization_id
    3. Joins with organization table to include organization_name
    4. Orders results by created_at descending
    5. Returns complete user list with organization details
Performance Notes:
    - Current implementation loads all users in memory
    - Suitable for organizations with < 1000 users
    - For larger organizations, pagination should be added (see TODOs.md)
    - Database query includes JOIN with organization table

Use Cases:
    - Display organization members in admin dashboard
    - Generate user access reports for specific organization
    - Audit which users have access to organization resources
    - Populate user selection dropdowns filtered by organization
    - Export organization user lists for compliance

Related Endpoints:
    - POST /admin/organizations/{id}/users - Add user to organization
    - GET /admin/organizations/{id}/users/count - Get user count only
    - GET /admin/users - List all users across organizations
    - GET /admin/users/{user_id} - Get individual user details

List organization users

Create a new user within a specific organization.

This endpoint creates a user account in the platform database and authentication
system. The user receives an email invitation to set their password and activate
their account. This ensures proper multi-tenant isolation.

Context:
    - Creates user in platform database and authentication system
    - Sends email invitation to user with password setup link
    - User starts in inactive status until they accept invitation
    - Email must be unique within the organization
    - Organization ID from path parameter overrides request body
    - User role determines permission level (admin, member, viewer)
    - Authentication synchronization ensures consistency

Behavior:
    1. Validates organization exists and is active
    2. Checks email is not already used in this organization
    3. Creates user record in platform database
    4. Creates user in authentication system
    5. Sends email invitation to user with password setup link
    6. Returns user details (user must accept invitation separately)
Side Effects:
    - User created in platform database
    - User created in authentication system (pending invitation acceptance)
    - Email invitation sent to user's email address
    - User appears in organization user lists immediately
    - User cannot log in until they accept invitation and set password

Use Cases:
    - Onboard new team member to organization
    - Provision user accounts during organization setup
    - Create admin users for customer organizations
    - Add temporary contractors or guests to organization

Related Endpoints:
    - GET /admin/organizations/{id}/users - List all organization users
    - POST /admin/users - Create user without organization context
    - GET /admin/users/{user_id} - View created user details
    - DELETE /admin/users/{user_id} - Remove user if created by mistake

Create user in organization

Get the total count of users in a specific organization.

This endpoint returns an integer count of all users belonging to an organization,
regardless of their active/inactive status. Use this for quota checks, billing
calculations, or displaying user count without loading full user details.

Context:
    - Counts all users in organization (active and inactive)
    - More efficient than fetching full user list when only count is needed
    - Useful for pagination calculations and quota enforcement
    - Returns integer directly (not wrapped in object)
    - Includes users in all statuses

Behavior:
    1. Validates organization exists by ID
    2. Executes COUNT query on users table filtered by organization_id
    3. Returns integer count directly
Performance Notes:
    - Very efficient - uses database COUNT query (no data loading)
    - Response time: < 50ms typically
    - Suitable for frequent polling or quota checks
    - Database index on organization_id ensures fast counting

Use Cases:
    - Display user count in organization dashboard
    - Check organization user quota before creating new users
    - Calculate per-user billing for organization
    - Determine if organization has any users before deletion
    - Monitor organization growth over time

Related Endpoints:
    - GET /admin/organizations/{id}/users - Get full user list with details
    - POST /admin/organizations/{id}/users - Add user to organization
    - GET /admin/organizations/{id} - Get organization details

Count organization users

Retrieve all users across all organizations with organization names.

This endpoint returns a complete list of users from all organizations in
the platform, including each user's organization name. Use this for global
user management, cross-organization reporting, and admin dashboards.

Context:
    - Returns users from ALL organizations (platform-wide view)
    - Includes organization name for each user
    - Users ordered by creation date (newest first)
    - No filtering by organization (use organization-specific endpoint for that)
    - ⚠️ PAGINATION NOT IMPLEMENTED - loads all users in memory
    - For production with many users, pagination should be added (see TODOs.md)
Behavior:
    1. Queries all users from database
    2. Joins with organization table to include organization_name
    3. Orders results by created_at descending
    4. Returns complete user list with organization details
Performance Warning:
    - ⚠️ Current implementation loads ALL users in memory
    - May cause timeouts with > 10,000 users
    - May cause high memory usage on server
    - Pagination implementation planned (see docs/api/TODOs.md)
    - For production, use organization-specific user list endpoints when possible

Use Cases:
    - Global admin dashboard showing all platform users
    - User search across all organizations
    - Platform-wide user analytics and reporting
    - Compliance audits requiring full user list
    - Export all users for backup or migration

Recommended Alternative for Large Datasets:
    For organizations with many users, use:
    GET /admin/organizations/{id}/users (filters to single organization)

Related Endpoints:
    - GET /admin/organizations/{id}/users - List users for specific organization (preferred)
    - POST /admin/users - Create user across organizations
    - GET /admin/users/{user_id} - Get individual user details
    - GET /admin/users/by-name/{name} - Search user by name

Future Improvement:
    Pagination will be added in future release. See docs/api/TODOs.md for details.

List all users

Create a new user with flexible organization assignment.

This endpoint creates a user account in the platform database and authentication
system. Unlike the organization-scoped endpoint, this allows creating users with
organization_id specified in the request body. Use this for bulk user creation
or when organization context is not available in URL.

Context:
    - Creates user in platform database and authentication system
    - Sends email invitation to user with password setup link
    - Requires organization_id in request body (no path parameter)
    - User starts in inactive status until they accept invitation
    - Email must be unique within the organization
    - User role determines permission level
    - Authentication synchronization ensures consistency

Behavior:
    1. Validates organization_id is provided in request body
    2. Validates organization exists and is active
    3. Checks email is not already used in this organization
    4. Creates user record in platform database
    5. Creates user in authentication system
    6. Sends email invitation to user with password setup link
    7. Returns user details (user must accept invitation separately)
Side Effects:
    - User created in platform database
    - User created in authentication system (pending invitation acceptance)
    - Email invitation sent to user's email address
    - User appears in organization user lists immediately
    - User cannot log in until they accept invitation and set password

Use Cases:
    - Bulk user creation via CSV import or API integration
    - Create users when organization context not available in URL
    - Automated user provisioning from external systems
    - Onboard multiple users across different organizations
    - Integration with identity providers (SCIM, SAML)

Comparison with Organization-Scoped Endpoint:
    - POST /admin/organizations/{id}/users - Use when organization known in URL
    - POST /admin/users - Use for bulk operations or flexible creation

Related Endpoints:
    - POST /admin/organizations/{id}/users - Alternative with organization in URL
    - GET /admin/users/{user_id} - View created user details
    - GET /admin/users - List all users
    - DELETE /admin/users/{user_id} - Remove user if created by mistake

Create user

Retrieve user information by searching for their name.

This endpoint searches for a user by name and returns their details if found.
The name parameter is matched against the user's stored name field. Use this
when you have a user's name but not their UUID.

Context:
    - Searches by exact name match (case-sensitive)
    - Returns first matching user if multiple users have same name
    - Does not search across first_name and last_name separately
    - User must exist in database
    - Returns 404 with clear message if user not found

Behavior:
    1. Searches database for user with matching name
    2. Returns first matching user if found
    3. Returns 404 error with descriptive message if no match
Use Cases:
    - Lookup user when only name is known
    - Verify user exists by name before operations
    - User search in admin interfaces
    - Integration with external systems using names instead of UUIDs

Recommended Alternative:
    For more reliable lookups, use GET /admin/users/{user_id} with UUID

Related Endpoints:
    - GET /admin/users/{user_id} - Get user by UUID (preferred for reliability)
    - GET /admin/users - List all users (for browsing)
    - GET /admin/organizations/{id}/users - List users in organization

Get user by name

Permanently delete a user from both database and authentication system.

This endpoint performs a hard delete of the user, removing them from both
the platform database AND the authentication system. This operation is IRREVERSIBLE.
The user will immediately lose access and cannot log in. All user data is
permanently removed.

Context:
    - HARD DELETE: User permanently removed from database and authentication system
    - Synchronizes deletion across platform database and authentication system
    - User immediately loses all access to the system
    - Cannot be undone - use with extreme caution
    - For temporary deactivation, update user status to inactive instead
    - User's created flows and executions may remain (check cascade rules)
    - No response body returned (204 No Content status)

Behavior:
    1. Validates user exists by ID
    2. Deletes user from authentication system
    3. Deletes user record from platform database
    4. Returns 204 No Content if successful
    5. Returns 404 if user not found
Side Effects:
    - User permanently removed from system
    - User's login credentials invalidated
    - Active sessions terminated immediately
    - User's API tokens revoked
    - May affect flows/executions depending on cascade rules

WARNING - Data Loss:
    This operation PERMANENTLY DELETES:
    - User profile information
    - User authentication credentials
    - User role and permissions
    - May affect user's flows and executions (check before deletion)

Use Cases:
    - Remove user after offboarding from organization
    - Comply with GDPR "right to be forgotten" requests
    - Clean up test users after development
    - Remove accounts created by mistake
    - Automated cleanup of inactive trial users

Safer Alternative:
    For reversible deactivation without deletion:
    1. Update user status to inactive via user update endpoint
    2. User account preserved but login disabled
    3. Can be reactivated later if needed

Pre-Deletion Checklist:
    - Verify user_id is correct
    - Check if user owns flows or executions
    - Consider reassigning user's resources
    - Backup user data if needed for records
    - Confirm deletion is intentional

Related Endpoints:
    - GET /admin/users/{user_id} - Verify user before deletion
    - GET /admin/organizations/{id}/users - Check organization membership
    - POST /admin/users - Create new user if deleted by mistake

Delete user

Retrieve detailed information for a specific user by their unique identifier.

This endpoint fetches complete user details including profile information,
organization membership, role, and status. Use this to verify user existence,
check user details before operations, or display user profiles.

Context:
    - Returns user from any organization (admin has global access)
    - Includes organization_id but NOT organization_name (use with-org endpoint for that)
    - User ID must be a valid UUID
    - Returns user regardless of active/inactive status
    - Response includes audit timestamps

Behavior:
    1. Validates user_id is valid UUID format
    2. Queries database for user by ID
    3. Returns user if found
    4. Raises 404 error if user does not exist
Use Cases:
    - Verify user exists before performing operations
    - Display user profile in admin interface
    - Validate user ID from external systems
    - Check user status and role before permission changes
    - Retrieve user details for audit logs

Related Endpoints:
    - GET /admin/users/by-name/{name} - Search user by name instead of ID
    - GET /admin/users - List all users
    - GET /admin/organizations/{id}/users - List users in specific organization
    - DELETE /admin/users/{user_id} - Delete user

Get user by ID

Authentication operations for user authentication, authorization, and session management.

Authentication endpoints handle user identity verification, token generation, and access control throughout the platform. The system uses JWT (JSON Web Token) based authentication managed through core.flows.super.ai.

**Authentication flow:**
1. Obtain credentials from your account at core.flows.super.ai
2. Authenticate to receive JWT access token and refresh token
3. Include access token in API requests via Authorization header
4. API validates tokens and extracts user identity and organization context
5. Tokens expire after 1 hour and must be refreshed

**Key concepts:**
- **Bearer Tokens**: Short-lived JWT tokens (1 hour) used for API requests
- **Anon-Key**: Long-lived API key used to authenticate to the authentication API.
- **Refresh Tokens**: Long-lived tokens used to obtain new access tokens
- **Protected Routes**: Most endpoints require valid authentication
- **Public Endpoints**: Limited whitelisted paths accessible without auth

**Getting started with authentication:**

1. **Obtain your Anonymous Key** (public endpoint - no authentication required):
   ```bash
   curl https://flows.super.ai/api/auth/anon-key
   ```

2. **Authenticate** to receive your tokens:
   ```bash
   curl -X POST 'https://core.flows.super.ai/auth/v1/token?grant_type=password' \
     -H 'Content-Type: application/json' \
     -H 'apikey: ANON_KEY' \
     -d '{"email": "you@example.com", "password": "your-password"}'
   ```
   This will return a JWT access token and refresh token.

3. **Use the access token** in your requests:
   ```bash
   curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        https://flows.super.ai/api/flows
   ```

**Token management:**
- Access tokens expire after 1 hour
- Use refresh tokens to obtain new access tokens without re-authenticating
- Store tokens securely and never commit them to version control

All API endpoints (except whitelisted public paths) require authentication. Include your bearer token in the Authorization header: `Bearer <token>`

auth

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 - Resend invitation to existing users
    - 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

Retrieve authentication API key

Resend invitation email to an existing user account.

Triggers a new invitation email when the original invitation has expired,
was not received, or the user needs another copy. The new invitation
includes a fresh authentication link and account setup instructions.

Context:
    - User must already exist in the system with pending or active status
    - Email service managed by Supabase authentication backend
    - Invitation link expires after configured timeout (typically 24-72 hours)
    - Multiple invitations can be sent to the same user
    - Each invitation invalidates previous invitation tokens
    - Does not modify user account status or profile data

Behavior:
    1. Validates email format in request body
    2. Logs invitation request for audit purposes
    3. Calls Supabase admin service to generate and send invitation
    4. Queues invitation email for delivery via external email service
    5. Returns success response immediately (email delivery is async)
    6. Raises 500 error if authentication service is unavailable

Use Cases:
    - User reports not receiving original invitation email
    - Invitation link has expired (typically after 24-72 hours)
    - User accidentally deleted invitation email
    - Organization admin needs to re-invite inactive user
    - Testing user onboarding flow in development

Email Delivery:
    - Invitation sent asynchronously by Supabase auth service
    - success=true indicates request was accepted, not that email was delivered
    - Check email service logs for actual delivery confirmation
    - Email may be delayed due to rate limiting or provider issues
    - User should check spam/junk folder if email not received

Security Considerations:
    - Each invitation generates unique time-limited authentication token
    - Previous invitation tokens are invalidated when new one is sent
    - Email address must match existing user account (no arbitrary emails)
    - Rate limiting recommended to prevent invitation spam

Related Endpoints:
    - POST /admin/organizations/{org_id}/users - Create new user with initial invite
    - GET /profile/me - User profile after successful authentication

Resend user invitation email

Flow execution operations for running and monitoring workflows.

Flow executions represent runtime instances of flows. When you execute a flow, a new flow execution is created with its own unique ID, status, and execution context. Each execution is independent and maintains its own state, input data, and results.

**Key concepts:**
- **Execution Status**: Tracks the lifecycle (running, completed, failed, cancelled)
- **Run Number**: Sequential identifier for executions of the same flow
- **Execution Context**: Contains input parameters, user information, and metadata
- **Task Results**: Stores outputs from each task within the execution

**Use these endpoints to:**
- Start new flow executions with custom input parameters
- Monitor execution progress and status in real-time
- Retrieve execution history and detailed results
- Filter and search executions by status, date, or flow
- Cancel running executions when needed
- Access task-level execution details and outputs

Flow executions transform flow definitions into actual work and deliverable results.

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 and include optional run number calculation.

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)
    - Run numbers calculated on-demand (performance impact)

Filtering Logic:
    - Status filter: Returns executions containing tasks with ANY of specified statuses
    - Tag filter: Returns executions containing tasks with ANY of specified tags
    - 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

Run Numbers:
    - include_run_number=true: Calculates sequential number (1, 2, 3...)
    - Based on creation time for the flow
    - Includes deleted executions in count (may have gaps)
    - Performance impact: Additional database query per execution
    - Recommended: Use only when displaying in UI

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 updated_at desc (most recently updated first)

Performance Considerations:
    - Without run_number: ~50ms for 100 results
    - With run_number: ~200ms for 100 results (N+1 query issue)
    - 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
    - With run numbers: ?flow_id=xxx&include_run_number=true

Related Endpoints:
    - GET /flow-executions/{id} - Get single execution details
    - POST /flow-executions - Create new execution
    - GET /flows/{id} - Get flow definition details

List flow executions with filtering and pagination

Create a new flow execution and start workflow processing.

This endpoint creates a flow execution record and immediately starts the associated
workflow processing. The execution is created with status 'running' and will be
processed asynchronously by the execution engine.

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

Execution Flow:
    1. Validates flow exists and user has access
    2. Creates execution record in database
    3. Starts workflow processing asynchronously
    4. Sends WebSocket notification to connected clients
    5. 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

Create and start a flow execution

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

Soft delete a flow execution

Retrieve detailed information for a specific flow execution.

Fetch a single flow execution by its unique identifier. Returns execution
metadata including status, input data, timestamps, and optionally the
sequential run number within its flow.

Context:
    - Retrieves single execution regardless of status (except deleted)
    - Soft-deleted executions return 404 Not Found
    - Includes full input data as provided at creation
    - Run number calculated on-demand if requested
    - Useful for monitoring execution progress

Run Number Calculation:
    - When include_run_number=true, calculates sequential position
    - Based on creation timestamp among all executions for this flow
    - Includes deleted executions (may have gaps in visible numbers)
    - Performance: Adds ~10-20ms per request
    - Useful for displaying "Run #42" in UI

Use Cases:
    - Check status of long-running execution
    - Retrieve input data for debugging
    - Display execution details in UI
    - Audit execution history with run numbers
    - Poll for execution completion

Performance Notes:
    - Without run_number: ~10ms average response time
    - With run_number: ~25ms 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

Retrieve a specific flow execution

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.

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

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 → running
    - Does not create new execution record

Performance Notes:
    - Response time: < 200ms (workflow starts asynchronously)
    - 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

Re-execute a flow execution

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 not automatically updated
    - 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

Add task status updates (Internal API)

Flow management operations for defining and organizing workflows.

Flows represent workflow definitions with tasks, dependencies, and execution logic. They serve as reusable templates that can be executed multiple times with different inputs.

**What is a flow?**
A flow consists of:
- **Tasks**: Individual units of work that perform specific actions
- **Dependencies**: Relationships between tasks that define execution order
- **Configuration**: Settings and parameters that control flow behavior

**Use these endpoints to:**
- Create new flow definitions from scratch or import from YAML
- List and search existing flows in your organization
- Retrieve detailed flow information including task definitions
- Update flow configurations and task parameters
- Delete flows that are no longer needed

Flows are the foundation of your workflow automation—once defined, they can be executed via the flow-executions endpoints.

flows

List all flows accessible to the authenticated user.

Returns all flows within the user's organization, ordered by creation date (newest first).
Each flow includes its latest version by default.

## Expansion Parameters
Use query parameters to include additional computed fields. See FlowResponse model
documentation for details on available expansion parameters and their performance impact.

## Common Use Cases
- Display flows in dashboard/listing page
- Populate flow selector dropdown
- Validate flow definitions in batch

List all 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

Create a new flow

Generate pre-signed URL for downloading a flow file.

Creates a temporary download URL for a previously uploaded file.
URLs are valid for 1 hour and can be shared safely without exposing
storage credentials.

## 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 download URL

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

## Important Notes
- This is a soft delete, not a permanent deletion
- Associated executions and files are NOT deleted
- Deleted flows cannot be undeleted via API (contact support)

Delete a flow

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

Retrieve a flow by 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

Partially update a flow

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 flow definition

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.

## Use Cases
- Display uploaded files in UI
- Verify file uploads completed successfully
- Retrieve file keys for download URL generation

List flow files

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 a single task in flow

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.

## 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

## Supported File Types
- Documents: PDF, DOCX, TXT, CSV
- Images: PNG, JPG, GIF
- Archives: ZIP, TAR
- Maximum file size: 100MB

Generate file upload URL

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 all versions of a flow

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 specific flow version

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 task summaries for flow version

Integration operations for connecting flows to external services and platforms.

Integrations enable your workflows to interact with third-party services, databases, storage systems, and communication platforms. They provide a unified interface for managing credentials, testing connections, and configuring service-specific features.

**Supported integration types:**
- **Databases**: PostgreSQL, MySQL, and other SQL databases
- **Storage**: SFTP, cloud storage, and file systems
- **Communication**: Email (SMTP, SES), webhooks, notifications
- **Collaboration**: SharePoint, Google Drive, document management
- **Custom**: Plugin architecture for extending functionality

**Key concepts:**
- **Credentials**: Securely stored authentication information per integration
- **Plugins**: Modular integration implementations with discovery and registration
- **OAuth Flows**: Automated authorization for third-party services
- **Webhooks**: Inbound event handling from external platforms
- **Connection Testing**: Validate credentials and connectivity before use

**Use these endpoints to:**
- Configure and manage integration credentials
- Test connections to external services
- Handle OAuth authorization flows for cloud services
- Set up and manage webhooks for inbound events
- Discover available integration capabilities
- Access integration-specific features (folders, schemas, etc.)

Integrations bridge your workflows with the external world, enabling powerful automation across your entire technology stack.

integrations

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 integration catalog

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 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 integration credentials

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 credentials by provider

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 credential

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 by 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

Update credential

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 credential secrets

List all databases accessible to the authenticated user.

Returns all database integrations created by the user, including:
- Database metadata and configuration
- Row and column counts
- Creation and update timestamps
- Current status

Use Cases:
    - Display user's databases in UI
    - Select database for workflow configuration
    - Monitor database integration status

List user databases

Create Database

Delete a database integration.

Removes the database integration and its associated data. This operation
may affect workflows that reference this database.

Use Cases:
    - Clean up unused database integrations
    - Remove test databases
    - Decommission data sources

Note:
    Currently returns success without performing actual deletion.
    Full implementation pending.

Delete database

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 by ID

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 database columns

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.

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

Generate database upload URL

Compare existing CSV with new CSV for replace operation.

Compare Csv For Replace

Complete file upload and process the file.

Complete File Upload

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

Preview CSV file before import

Replace existing database data with new file upload.

Replace File Upload

Manually trigger email processing (for testing).

Process Emails

Create a new email task with a unique email address.

Create Email Task

Get Email Task Status

Get Google access token (proxied to legacy system).

Get Google Access Token From Credential

Google OAuth authorization (proxied to legacy system).

Google Authorize

List Google Drive folders by email (proxied to legacy system).

List Google Drive Folders By Email

List Google Drive folders (proxied to legacy system).

List Google Drive Folders

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 all registered plugins

Execute PostgreSQL task using the new plugin system.

Execute Postgres Plugin Task

Test PostgreSQL connection using the new plugin system.

Test Postgres Plugin Connection

Create SharePoint integration using new plugin architecture.

Create Sharepoint Integration

Get SharePoint sites for a credential (new plugin architecture).

Get Sharepoint Sites

Get SharePoint folders for a site (new plugin architecture).

Get Sharepoint Folders

Create Sharepoint Webhook Token

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 plugin capabilities

Test PostgreSQL connection (proxied to legacy system).

Test Postgres Connection

Test PostgreSQL connection by credential ID (proxied to legacy system).

Test Postgres Connection By Credential Id

Test SFTP connection by attempting to connect and write a test file.

Test Sftp Connection

Start SharePoint OAuth 2.0 Authorization-Code flow for multi-tenant access.

Sharepoint Authorize

Handle OAuth callback from Microsoft SharePoint/Graph API.

Sharepoint Callback

Get Sharepoint Credentials

Delete Sharepoint Integration

Handle SharePoint webhook notifications for file changes.

Sharepoint Webhook Handler

User profile operations for viewing and updating account information.

Profile endpoints allow authenticated users to view and update their own account information and preferences. These endpoints operate on the currently authenticated user (determined from the JWT token) and do not require specifying a user ID.

**Account information includes:**
- **Personal Details**: First name, last name, email
- **Organization**: Associated organization and role
- **Status**: Account status and permissions
- **Metadata**: Created/updated timestamps

**Use these endpoints to:**
- Retrieve current user information for display
- Update personal details (name, preferences)
- View organization membership and role
- Access account metadata

Profile endpoints provide self-service account management capabilities, reducing the need for administrative intervention for routine updates.

**Note:** All profile endpoints are protected and automatically scope to the authenticated user. Email and organization changes require admin privileges.

profile

Retrieve complete profile information for the currently authenticated user.

Returns the full user profile including personal information, role, status,
and organization membership. The user is automatically identified from their
authentication credentials. No user ID parameter is needed.

Context:
    - Returns user regardless of active/inactive/pending status
    - Includes organization_id for multi-tenant access control
    - Profile data is read-only via this endpoint (use PUT /profile/me to update)
    - User role determines API permissions across the platform

Behavior:
    1. Extracts user_id from authenticated user context
    2. Queries database for complete user profile by user_id
    3. Returns user profile if found
    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.)
    - Verify user's organization for multi-tenant data filtering
    - Determine user status for account activation workflows
    - Fetch user details after authentication to initialize session

Related Endpoints:
    - PUT /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 current user profile

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)

Update current user profile

Task data operations for flow validation, schema discovery, and dynamic configuration.

The task-data endpoint analyzes flow definitions to extract task output schemas, dynamic configuration options, and validation errors. This is essential for building flow configuration UIs, validating flows before execution, and understanding task data structures.

**Primary Use Cases:**
- **Flow Builder UI**: Get task output schemas for validating downstream task inputs
- **Schema Discovery**: Understand the structure of data each task produces
- **Dynamic Configuration**: Retrieve runtime-dependent options (e.g., available spreadsheets, database tables)
- **Flow Validation**: Validate flow definitions programmatically before saving or executing
- **Custom Integrations**: Build tools that work with SuperAI Flows programmatically

**What You Get:**
- **Output Schemas**: JSON Schema definitions for each task's output structure
- **Dynamic Data**: Runtime-dependent configuration options (dropdown choices, conditional fields)
- **Validation Errors**: Detailed error messages for invalid flow definitions

**How It Works:**
1. Submit a flow definition in SuperAI Flows DSL format
2. The endpoint validates the structure and loads each task executor
3. For each task, it extracts the output schema and any dynamic configuration data
4. Returns all schemas, dynamic data, and any validation errors encountered

**Key Concepts:**
- **Output Schema**: JSON Schema describing the structure of data a task produces
- **Dynamic Data**: Configuration options that depend on user credentials or external state (e.g., list of Google Sheets accessible with your credentials)
- **Validation Levels**: Basic (structure only) vs Full (includes semantic validation)

**Integration Notes:**
- The flow builder frontend uses this endpoint to power the task configuration UI
- Flows API uses this validation internally when creating/updating flows
- Response includes validation errors even on HTTP 200 - always check `validation_errors` field
- May make external API calls to fetch dynamic data, so response time varies (100ms-2s typical)

**Related Endpoints:**
- `GET /task-executors`: List available task executor types and their schemas
- `POST /flows`: Create flow (uses task-data validation internally)
- `PUT /flows/{flow_id}`: Update flow (uses task-data validation internally)

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

Analyze flow definition and extract schemas

Task execution operations for tracking individual task runs within flow executions.

Task executions represent individual task runs within a flow execution. Each task in a flow execution has its own task execution record that tracks its lifecycle, inputs, outputs, and status.

**What is tracked:**
- **Status**: Current state (pending, running, completed, failed, skipped)
- **Input/Output**: Data passed to and produced by the task
- **Timing**: Start time, end time, and duration
- **Errors**: Failure details and error messages
- **Tags**: Metadata and categorization

**Use these endpoints to:**
- Query task execution status for debugging
- Retrieve task outputs for analysis
- Debug task failures with detailed error information
- Track task performance and timing
- Monitor task execution progress within flows

Task executions provide granular visibility into workflow execution, essential for debugging and optimization.

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

List task executions with filtering

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

Create a task execution record

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. Updates the task execution record in the database
2. Recalculates task output summaries for the parent flow execution
3. Identifies downstream tasks that depend on the updated task (stale tasks)
4. 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

Update task execution and optionally re-execute flow

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

Retrieve a specific task execution

Task executor operations for discovering available task types and their capabilities.

Task executors define the available task types that can be used in flow definitions. Each executor specifies its input schema, execution behavior, and capabilities. This endpoint enables programmatic discovery of task types for building flows dynamically.

**What task executors provide:**
- **Input Schema**: JSON Schema defining required and optional parameters
- **Output Schema**: Expected output structure and data types
- **Description**: Human-readable explanation of functionality
- **Agent Prompts**: Instructions for AI-powered flow generation

**Use these endpoints to:**
- Discover available task types for flow building
- View task input/output schemas for validation
- Understand task capabilities and requirements
- Build flow builder UIs with dynamic task lists
- Enable AI agents to select appropriate tasks

Task executors enable dynamic, flexible workflow creation by providing a registry of available operations.

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_url, 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

List all available task executors

Task output operations for storing and retrieving task execution results.

Task outputs store the results produced by task executions in a structured, queryable format. While task executions track the full lifecycle (input, output, error, status), task outputs focus specifically on the final output data formatted for display, analysis, and downstream consumption.

**Key characteristics:**
- **Summary Field**: Structured output data ready for consumption
- **Historical Record**: Permanent storage of task results
- **Queryable**: Filter and search outputs by task, execution, or flow
- **Linked**: Connected to parent flow execution and task execution

**Use these endpoints to:**
- Store task results after successful execution
- Retrieve outputs for specific tasks or entire executions
- Query historical outputs for analysis and reporting
- Access formatted results for display in dashboards
- Feed outputs to downstream tasks or external systems

Task outputs provide the data foundation for workflow analytics, debugging, and result visualization.

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

List all 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

Create task output

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

Get task output by ID

Task tag operations for categorizing and organizing tasks with metadata.

Task tags provide metadata and categorization for tasks within flow executions. Tags enable flexible organization, filtering, and grouping of tasks beyond their structural relationships.

**What tags enable:**
- **Categorization**: Group related tasks across different flows
- **Filtering**: Query executions by tag criteria
- **Metadata**: Attach custom key-value pairs to tasks
- **Organization**: Create logical groupings for reporting

**Use these endpoints to:**
- Manage task labels and categories
- Add organizational metadata to tasks
- Query tasks by tag criteria
- Build custom views and dashboards

Task tags provide flexible organization capabilities that enhance workflow management and analysis.

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

List active task tags for a flow execution

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)

Sections

Ask an AI

Code with AI