Super.ai integrations API

openapi: 3.1.0
info:
  title: SuperAI Flow Platform auth integrations API
  description: "SuperAI Flows is a workflow orchestration platform that enables you to design, deploy, and monitor automated workflows at scale.\n\nBuild complex workflows using our declarative YAML DSL, execute them reliably, and integrate seamlessly with AI models, cloud storage, and enterprise systems.\n\n**Key Capabilities:**\n- **Workflow Management**: Define workflows as code with version control and automated execution\n- **Task Orchestration**: Chain together API calls, data processing, and AI operations\n- **Real-time Monitoring**: Track execution progress with WebSocket notifications and comprehensive logging\n- **Multi-tenant Architecture**: Organization-scoped resources with role-based access control\n\n**API Versioning and Breaking Changes:**\n\nWe follow a strict compatibility policy to ensure your integrations remain stable:\n\n- **Non-breaking changes** (safe, no action required):\n  - Adding new API endpoints\n  - Adding new optional query parameters to existing endpoints\n  - Adding new fields to API responses\n  - Adding new values to existing enums\n\n- **Breaking changes** (requires client updates):\n  - Removing or renaming API endpoints\n  - Removing query parameters or request fields\n  - Removing response fields\n  - Changing field types or validation rules\n  - Removing values from existing enums\n\n**Client Implementation Requirements:**\n\nYour 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.\n\n**Backward Compatibility Guarantee:**\n\nWe commit to maintaining backward compatibility for all non-breaking changes. Breaking changes will be:\n- Announced at least 15 days in advance\n- Documented in our changelog with migration guide\n\nFor the latest API updates and migration guides, see our changelog."
  version: 0.1.0
tags:
- name: integrations
  description: '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.'
  x-displayName: Integrations
paths:
  /api/integrations/database:
    get:
      tags:
      - integrations
      summary: List user databases
      description: "List all databases accessible to the authenticated user.\n\nReturns all databases, including:\n- Database metadata and configuration\n- Row and column counts\n- Creation and update timestamps\n- Current status\n\nUse Cases:\n    - Display databases in UI\n    - Select database for workflow configuration\n    - Monitor database integration status"
      operationId: list_databases_api_integrations_database_get
      responses:
        '200':
          description: List of databases successfully retrieved
          content:
            application/json:
              schema:
                items:
                  additionalProperties: true
                  type: object
                type: array
                title: Response List Databases Api Integrations Database Get
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    post:
      tags:
      - integrations
      summary: Create Database
      description: Create a new CSV database instance.
      operationId: create_database_api_integrations_database_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentFileCreateRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFileResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/integrations/database/managed:
    post:
      tags:
      - integrations
      summary: Create managed database
      description: "Create a managed PostgreSQL database for the organization.\n\nCreates a dedicated database on the customer Cloud SQL instance with:\n- Database name: tenant_{org_id}\n- Role: tenant_{org_id}_rw with ALL PRIVILEGES\n- app_admin user can CONNECT and SET ROLE to access the database\n\nOnly one managed database per organization is allowed.\n\nUse Cases:\n    - Create isolated database for organization data\n    - Store structured data with SQL queries\n    - Enable multi-tenant data isolation"
      operationId: create_managed_database_api_integrations_database_managed_post
      responses:
        '201':
          description: Managed database created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentFileResponse'
        '409':
          description: Database already exists for this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/integrations/database/managed/tables:
    get:
      tags:
      - integrations
      summary: List tables in managed database
      description: "List all tables in a managed database with row counts.\n\nReturns table names and their row counts for schema management.\nUses organization_id from user context to identify the database.\n\nUse Cases:\n    - Display available tables in schema management UI\n    - Monitor table sizes"
      operationId: list_managed_database_tables_api_integrations_database_managed_tables_get
      responses:
        '200':
          description: List of tables retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableListResponse'
        '404':
          description: Database not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    post:
      tags:
      - integrations
      summary: Create table in managed database
      description: "Create a new table in a managed database.\n\nCreates a table with specified columns using tenant_admin credentials.\nUses organization_id from user context to identify the database.\n\nUse Cases:\n    - Add new tables to managed database\n    - Define custom schema for organization data"
      operationId: create_managed_database_table_api_integrations_database_managed_tables_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTableRequest'
        required: true
      responses:
        '201':
          description: Table created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTableResponse'
        '400':
          description: Invalid table definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/integrations/database/managed/tables/{table_name}/columns:
    get:
      tags:
      - integrations
      summary: Get table columns from managed database
      description: "Get column definitions from a table in a managed database.\n\nReturns column names and types for foreign key reference selection.\n\nUse Cases:\n    - Display available columns for foreign key selection\n    - Validate foreign key references"
      operationId: get_managed_database_table_columns_api_integrations_database_managed_tables__table_name__columns_get
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,62}$
          title: Table Name
      responses:
        '200':
          description: Table columns retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableColumnsResponse'
        '404':
          description: Table not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/integrations/database/managed/tables/{table_name}/data:
    get:
      tags:
      - integrations
      summary: Get table data from managed database
      description: "Get all data from a table in a managed database.\n\nUses app_admin with SET ROLE to fetch data with read-only access.\nUses organization_id from user context to identify the database.\n\nUse Cases:\n    - Display table contents in schema management UI\n    - View organization data"
      operationId: get_managed_database_table_data_api_integrations_database_managed_tables__table_name__data_get
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,62}$
          title: Table Name
      responses:
        '200':
          description: Table data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TableDataResponse'
        '404':
          description: Table not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/integrations/database/managed/tables/{table_name}/rows:
    post:
      tags:
      - integrations
      summary: Insert one row into a managed-DB table
      description: 'Insert a single row into a managed-DB table and return the inserted row.


        Column names in `values` must match the table schema. Values are bound via parameterised SQL.'
      operationId: insert_managed_database_row_api_integrations_database_managed_tables__table_name__rows_post
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,62}$
          title: Table Name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InsertRowRequest'
      responses:
        '201':
          description: Row inserted successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsertRowResponse'
        '400':
          description: Invalid values payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Table not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Constraint violation (unique / FK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid value for column type / NOT NULL / unknown column
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/integrations/database/managed/tables/{table_name}/query:
    post:
      tags:
      - integrations
      summary: Query a managed-DB table with exact-match filters
      description: 'Run a parameterised SELECT against a managed-DB table.


        Supports a list of match clauses against columns. Each clause is either a ''whole'' exact-match

        or a ''json_keys'' match against keys inside a JSONB column. Clauses combine via `combinator` at

        the top level (AND or OR; defaults to AND). Returns rows ordered by `order_by` if provided,

        capped to `limit` (max 1000). The API surface is generic — ICL is the first consumer ("Write

        To Database" + ICL Retrieve tasks); future use cases reuse it without bespoke service methods.'
      operationId: query_managed_database_table_api_integrations_database_managed_tables__table_name__query_post
      parameters:
      - name: table_name
        in: path
        required: true
        schema:
          type: string
          pattern: ^[a-zA-Z_][a-zA-Z0-9_]{0,62}$
          title: Table Name
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QueryTableRequest'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryTableResponse'
        '400':
          description: Invalid query payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Table not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid value for column type / unknown column
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
  /api/integrations/database/{db_id}:
    get:
      tags:
      - integrations
      summary: Get database by ID
      description: "Retrieve detailed information for a specific database.\n\nReturns complete database configuration including:\n- Database metadata (name, description, status)\n- File information (location, size)\n- Schema details (row count, column count)\n- Timestamps and audit information\n\nUse Cases:\n    - Display database details in UI\n    - Validate database exists before operations\n    - Retrieve configuration for workflow tasks"
      operationId: get_database_api_integrations_database__db_id__get
      parameters:
      - name: db_id
        in: path
        required: true
        schema:
          type: string
          title: Db Id
      responses:
        '200':
          description: Database details retrieved successfully
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Get Database Api Integrations Database  Db Id  Get
        '404':
          description: Database not found with the specified ID
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Missing or invalid authentication credentials
          content:
            application/json:
              examples:
                missing_token:
                  summary: Missing authentication token
                  value:
                    error:
                      message: Authentication required
                      code: unauthorized
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                invalid_token:
                  summary: Invalid or expired token
                  value:
                    error:
                      message: Invalid authentication token
                      code: unauthorized
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error - An unexpected error occurred
          content:
            application/json:
              examples:
                internal_error:
                  summary: Internal server error
                  value:
                    error:
                      message: Internal server error
                      code: internal_error
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                repository_error:
                  summary: Database error
                  value:
                    error:
                      message: Database operation failed
                      code: repository_error
                    request_id: 01K8KACP7D2XFGHJ9KLM4NPQR8
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - BearerAuth: []
      - APIKeyAuth: []
    delete:
      tags:
      - integrations
      summary: Delete database
      description: 'Delete a database integration.


        Removes the database integration and its associated CSV file from storage.

        This operation may affe

# --- truncated at 32 KB (155 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/superai/refs/heads/main/openapi/superai-integrations-api-openapi.yml