Super.ai organizations API

openapi: 3.1.0
info:
  title: SuperAI Flow Platform auth organizations 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: organizations
  description: Organization operations for viewing credit balance and organization-scoped information.
  x-displayName: Organizations
paths:
  /api/organizations/worker-groups:
    get:
      tags:
      - organizations
      summary: List all worker groups
      description: List all worker groups for the current organization (paginated).
      operationId: list_worker_groups_api_organizations_worker_groups_get
      parameters:
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          description: Number of records to skip.
          default: 0
          title: Offset
        description: Number of records to skip.
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 250
          minimum: 1
          description: Maximum number of records to return.
          default: 50
          title: Limit
        description: Maximum number of records to return.
      responses:
        '200':
          description: Worker groups retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroupListResponse'
        '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'
        '403':
          description: Forbidden - Insufficient permissions to access this resource
          content:
            application/json:
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    error:
                      message: You do not have permission to access this resource
                      code: forbidden
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                wrong_organization:
                  summary: Resource belongs to different organization
                  value:
                    error:
                      message: This resource belongs to a different organization
                      code: forbidden
                    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: []
    post:
      tags:
      - organizations
      summary: Create a worker group
      description: Create a new worker group in the current organization.
      operationId: create_worker_group_api_organizations_worker_groups_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkerGroupCreateRequest'
      responses:
        '201':
          description: Worker group created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroupDetailResponse'
        '409':
          description: Worker group name already exists
          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'
        '403':
          description: Forbidden - Insufficient permissions to access this resource
          content:
            application/json:
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    error:
                      message: You do not have permission to access this resource
                      code: forbidden
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                wrong_organization:
                  summary: Resource belongs to different organization
                  value:
                    error:
                      message: This resource belongs to a different organization
                      code: forbidden
                    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/organizations/worker-groups/{group_id}:
    get:
      tags:
      - organizations
      summary: Get a worker group
      description: Get details of a specific worker group including its members.
      operationId: get_worker_group_api_organizations_worker_groups__group_id__get
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      responses:
        '200':
          description: Worker group retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroupDetailResponse'
        '404':
          description: Worker group 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'
        '403':
          description: Forbidden - Insufficient permissions to access this resource
          content:
            application/json:
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    error:
                      message: You do not have permission to access this resource
                      code: forbidden
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                wrong_organization:
                  summary: Resource belongs to different organization
                  value:
                    error:
                      message: This resource belongs to a different organization
                      code: forbidden
                    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: []
    put:
      tags:
      - organizations
      summary: Update a worker group
      description: Update a worker group's name and/or description.
      operationId: update_worker_group_api_organizations_worker_groups__group_id__put
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkerGroupUpdateRequest'
      responses:
        '200':
          description: Worker group updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroupDetailResponse'
        '404':
          description: Worker group not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Worker group name already exists
          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'
        '403':
          description: Forbidden - Insufficient permissions to access this resource
          content:
            application/json:
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    error:
                      message: You do not have permission to access this resource
                      code: forbidden
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                wrong_organization:
                  summary: Resource belongs to different organization
                  value:
                    error:
                      message: This resource belongs to a different organization
                      code: forbidden
                    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:
      - organizations
      summary: Delete a worker group
      description: Soft-delete a worker group. Existing HITL task assignments are preserved.
      operationId: delete_worker_group_api_organizations_worker_groups__group_id__delete
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      responses:
        '204':
          description: Worker group deleted successfully
        '404':
          description: Worker group 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'
        '403':
          description: Forbidden - Insufficient permissions to access this resource
          content:
            application/json:
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    error:
                      message: You do not have permission to access this resource
                      code: forbidden
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                wrong_organization:
                  summary: Resource belongs to different organization
                  value:
                    error:
                      message: This resource belongs to a different organization
                      code: forbidden
                    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/organizations/worker-groups/{group_id}/members:
    post:
      tags:
      - organizations
      summary: Add or remove members from a worker group
      description: 'Add and/or remove members from a worker group in a single call.


        Users in add_user_ids that are already members are silently skipped.

        Users in remove_user_ids that are not members are silently ignored.'
      operationId: update_worker_group_members_api_organizations_worker_groups__group_id__members_post
      parameters:
      - name: group_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Group Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkerGroupMembersUpdateRequest'
      responses:
        '200':
          description: Members updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerGroupDetailResponse'
        '404':
          description: Worker group 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'
        '403':
          description: Forbidden - Insufficient permissions to access this resource
          content:
            application/json:
              examples:
                insufficient_permissions:
                  summary: Insufficient permissions
                  value:
                    error:
                      message: You do not have permission to access this resource
                      code: forbidden
                    request_id: 01K8KABR6S16YETA2SZPVBS9SP
                wrong_organization:
                  summary: Resource belongs to different organization
                  value:
                    error:
                      message: This resource belongs to a different organization
                      code: forbidden
                    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/organizations/credits:
    get:
      tags:
      - organizations
      summary: Get credit balance for current user's organization
      description: 'Get credit balance for the current user''s organization.


        Returns the current credit balance including grants, consumption, and remaining credits

        for the authenticated user''s organization. Consumption is read from the

        credit_usage_summary materialized view, refreshed every 10 minutes.


        **Authorization**:

        - Organization admins and users can view their own organization''s credits

        - RLS policies enforce organization-level data isolation at database level


        **Context**:

        - Credits are tracked at the organization level, not per user

        - Grants are permanent allocations (cannot be revoked)

        - Credits consumed track usage across all users in the organization


        **Use Cases**:

        - Display credit balance in user dashboard

        - Check remaining credits before starting workflows

        - Monitor organization usage


        **Related Endpoints**:

        - POST /admin/organizations/{id}/grants - Admin can grant additional credits (backoffice only)


        **Security**:

        - @require_roles decorator enforces role-based access

        - Uses current_user.organization_id (no path parameter to validate)

        - RLS policies provide database-level enforcement'
      operationId: get_organization_credits_api_organizations_credits_get
      responses:
        '200':
          description: Credit balance retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreditBalanceResponse'
        '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/organizations/settings:
    put:
      tags:
      - organizations
      summary: Update organization settings
      description: "Update organization settings.\n\nThis endpoint replaces settings in the organization's settings JSONB column.\nOnly admins can update settings. Uses JWT token to identify the organization.\n\nConfiguration Options for worker_landing_page:\n    - hub: Workers land on the Hub page\n    - assigned_flow_data_tab: Workers land on their assigned flow's Data Tab\n    - assigned_flow_work_tab: Workers land on their assigned flow's Work Tab\n\nReturns:\n    Full organization object with updated settings\n\nNote:\n    To retrieve settings, use the standard organization endpoint which includes\n    settings in OrganizationResponse via RLS policies."
      operationId: update_organization_settings_api_organizations_settings_put
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrganizationSettings'
        required: true
      responses:
        '200':
          description: Settings updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/app__api__organization__organization_api_model__OrganizationResponse'
        '400':
          description: Invalid settings value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Insufficient permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Organization not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '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/organizations/{organization_id}:
    get:
      tags:
      - organizations
      summary: Get organization by ID
      description: "Retrieve detailed information for a specific organization.\n\nFetches complete metadata for a single organization using its unique identifier.\nUse this to verify organization existence, check active status, or retrieve\norganization details before performing related operations.\n\nContext:\n    - Returns organization regardless of active/inactive status\n    - Does not include user count or related entity counts\n    - Organization ID must be a valid UUID\n\nBehavior:\n    1. Validates organization_id is valid UUID format\n    2. Queries database for organization by ID\n    3. Returns organization if found\n    4. Raises 404 error if organization does not exist\n\nUse Cases:\n    - Retrieve organization details"
      operationId: get_organization_api_organizations__organization_id__get
      parameters:
      - name: organization_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: Unique identifier of th

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