{
  "components": {
    "schemas": {
      "AcceptWorkflowAction": {
        "description": "Action to accept the proposed workflow.",
        "properties": {
          "action": {
            "const": "accept_workflow",
            "default": "accept_workflow",
            "title": "Action",
            "type": "string"
          },
          "flow_definition": {
            "additionalProperties": true,
            "description": "The workflow definition to accept",
            "title": "Flow Definition",
            "type": "object"
          },
          "message_type": {
            "const": "action",
            "default": "action",
            "title": "Message Type",
            "type": "string"
          }
        },
        "required": [
          "flow_definition"
        ],
        "title": "AcceptWorkflowAction",
        "type": "object"
      },
      "ActionBody": {
        "description": "Base body for action messages.",
        "properties": {
          "action_type": {
            "title": "Action Type",
            "type": "string"
          },
          "data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ConfirmationRequestData"
              },
              {
                "$ref": "#/components/schemas/MissingTaskParamsData"
              },
              {
                "$ref": "#/components/schemas/AssumedParametersData"
              },
              {
                "$ref": "#/components/schemas/ErrorSummaryData"
              },
              {
                "$ref": "#/components/schemas/RunWorkflowRequestData"
              }
            ],
            "title": "Data"
          },
          "type": {
            "const": "action",
            "default": "action",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "action_type",
          "data"
        ],
        "title": "ActionBody",
        "type": "object"
      },
      "AddTaskStatusRequest": {
        "description": "Batch request to add multiple task status updates.\n\nAllows system workers to report status changes for multiple tasks\nin a single API call for improved performance.",
        "properties": {
          "statuses": {
            "description": "Array of task status updates to apply. Minimum: 1 update, Maximum: 100 updates per request. Updates are processed in order provided.",
            "example": [
              {
                "status": "completed",
                "task_name": "extract_data"
              },
              {
                "status": "running",
                "task_name": "validate_results"
              }
            ],
            "items": {
              "$ref": "#/components/schemas/AddTaskStatusRequestItem"
            },
            "maxItems": 100,
            "minItems": 1,
            "title": "Statuses",
            "type": "array"
          }
        },
        "required": [
          "statuses"
        ],
        "title": "AddTaskStatusRequest",
        "type": "object"
      },
      "AddTaskStatusRequestItem": {
        "description": "Single task status update in a batch request.\n\nRepresents one task's status change within a flow execution.\nUsed by system workers to report task execution progress.",
        "properties": {
          "status": {
            "anyOf": [
              {
                "maxLength": 50,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New status value for the task. Common values: 'running', 'completed', 'failed', 'skipped'. Nullable to support status clearing. No validation enforced - execution engine determines valid statuses.",
            "example": "completed",
            "title": "Status"
          },
          "task_name": {
            "description": "Name of the task as defined in flow definition. Must match exactly (case-sensitive). Examples: 'extract_data', 'send_email', 'validate_input'",
            "example": "process_document",
            "maxLength": 255,
            "minLength": 1,
            "title": "Task Name",
            "type": "string"
          }
        },
        "required": [
          "task_name"
        ],
        "title": "AddTaskStatusRequestItem",
        "type": "object"
      },
      "AgentResponseChunk": {
        "description": "Represents a chunk of the agent's response.\n\nAttributes:\n    type: The type of chunk (assistant, reasoning, tool_call, tool_return).\n    content: The content of the chunk.",
        "properties": {
          "content": {
            "title": "Content"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "type",
          "content"
        ],
        "title": "AgentResponseChunk",
        "type": "object"
      },
      "AnonKeyResponse": {
        "description": "Response model for anonymous authentication key retrieval.\n\nReturns the authentication key required for client applications to\nauthenticate with the authentication API hosted at core.flows.super.ai.",
        "properties": {
          "anon_key": {
            "description": "Anonymous authentication key for client applications. Use this key to authenticate API requests to the authentication service. Include this in your authentication API calls as the 'apikey' header. This key is safe to use in client-side applications and does not grant administrative privileges. It enables password authentication and token generation for users.",
            "examples": [
              "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFiY2RlZmdoaWprbG1ub3BxcnN0Iiwicm9sZSI6ImFub24iLCJpYXQiOjE2ODkwMDAwMDAsImV4cCI6MTg0Njc2ODAwMH0.signature"
            ],
            "title": "Anon Key",
            "type": "string"
          }
        },
        "required": [
          "anon_key"
        ],
        "title": "AnonKeyResponse",
        "type": "object"
      },
      "ApiInfo": {
        "description": "API prefix and base URL information.",
        "properties": {
          "base_url": {
            "description": "Full base URL for API endpoints",
            "examples": [
              "/api"
            ],
            "title": "Base Url",
            "type": "string"
          },
          "prefix": {
            "description": "API path prefix for all endpoints",
            "examples": [
              "/api"
            ],
            "title": "Prefix",
            "type": "string"
          }
        },
        "required": [
          "prefix",
          "base_url"
        ],
        "title": "ApiInfo",
        "type": "object"
      },
      "ApiKeyCreateRequest": {
        "description": "Public API request payload for creating a new API key.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional description explaining the purpose and usage of this API key.",
            "example": "API key for external integrations",
            "title": "Description"
          },
          "name": {
            "description": "Human-readable name for this API key.",
            "example": "API Key",
            "maxLength": 255,
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "title": "ApiKeyCreateRequest",
        "type": "object"
      },
      "ApiKeyCreateResponse": {
        "description": "Response model for API key creation including the full token.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "service_account_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Service Account Id"
          },
          "token": {
            "description": "Full authentication token. This is the only time the full token is shown. Store it securely as it cannot be retrieved later.",
            "example": "saf_org_550e8400_abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
            "title": "Token",
            "type": "string"
          },
          "token_prefix": {
            "title": "Token Prefix",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "user_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "User Id"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "name",
          "token",
          "token_prefix",
          "organization_id"
        ],
        "title": "ApiKeyCreateResponse",
        "type": "object"
      },
      "ApiKeyResponse": {
        "description": "Response model for API key operations.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional description explaining the purpose and usage of this API key.",
            "example": "API key for external integrations",
            "title": "Description"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "name": {
            "description": "Human-readable name for this API key.",
            "example": "API Key",
            "maxLength": 255,
            "title": "Name",
            "type": "string"
          },
          "organization_id": {
            "description": "UUID of the organization this API key belongs to.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "service_account_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "UUID of the service account this API key belongs to. NULL for user keys.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "title": "Service Account Id"
          },
          "token_prefix": {
            "description": "Prefix of the authentication token for display purposes. Full token is only shown once during creation.",
            "example": "saf_org_550e8400_abc123",
            "maxLength": 40,
            "title": "Token Prefix",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "user_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "UUID of the user this API key belongs to. NULL for service account keys.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "title": "User Id"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "name",
          "token_prefix",
          "organization_id"
        ],
        "title": "ApiKeyResponse",
        "type": "object"
      },
      "AssumedParametersData": {
        "description": "Data for assumed parameters actions.",
        "properties": {
          "tasks_with_assumptions": {
            "additionalProperties": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Tasks With Assumptions",
            "type": "object"
          }
        },
        "required": [
          "tasks_with_assumptions"
        ],
        "title": "AssumedParametersData",
        "type": "object"
      },
      "Body_process_audio_file_agent_transcription_post": {
        "properties": {
          "audio_file": {
            "description": "Audio file to transcribe (multipart/form-data). Supported formats: MP3, WAV, M4A, OGG, FLAC, AAC, OPUS, WebM. Max size depends on server configuration (typically 100MB).",
            "format": "binary",
            "title": "Audio File",
            "type": "string"
          }
        },
        "required": [
          "audio_file"
        ],
        "title": "Body_process_audio_file_agent_transcription_post",
        "type": "object"
      },
      "CSVMetadata": {
        "description": "Metadata about a CSV file.",
        "properties": {
          "delimiter": {
            "description": "CSV delimiter character used",
            "examples": [
              ","
            ],
            "title": "Delimiter",
            "type": "string"
          },
          "file_size": {
            "description": "File size in bytes",
            "examples": [
              2048576
            ],
            "minimum": 0.0,
            "title": "File Size",
            "type": "integer"
          },
          "file_size_mb": {
            "description": "File size in megabytes",
            "examples": [
              1.95
            ],
            "minimum": 0.0,
            "title": "File Size Mb",
            "type": "number"
          },
          "has_header": {
            "description": "Whether the CSV file has a header row",
            "examples": [
              true
            ],
            "title": "Has Header",
            "type": "boolean"
          },
          "total_columns": {
            "description": "Total number of columns",
            "examples": [
              12
            ],
            "minimum": 0.0,
            "title": "Total Columns",
            "type": "integer"
          },
          "total_rows": {
            "description": "Total number of data rows (excluding header)",
            "examples": [
              15420
            ],
            "minimum": 0.0,
            "title": "Total Rows",
            "type": "integer"
          }
        },
        "required": [
          "total_rows",
          "total_columns",
          "file_size",
          "file_size_mb",
          "has_header",
          "delimiter"
        ],
        "title": "CSVMetadata",
        "type": "object"
      },
      "CSVPreviewResponse": {
        "description": "Response containing CSV file preview.\n\nReturned by POST /database/{db_id}/upload/preview endpoint.\nShows first 5 rows and file metadata before final upload.",
        "example": {
          "headers": [
            "id",
            "name",
            "email",
            "created_at",
            "revenue"
          ],
          "metadata": {
            "delimiter": ",",
            "file_size": 2048576,
            "file_size_mb": 1.95,
            "has_header": true,
            "total_columns": 5,
            "total_rows": 15420
          },
          "preview_rows": [
            [
              "1",
              "John Doe",
              "john@example.com",
              "2024-01-15",
              "1250.00"
            ],
            [
              "2",
              "Jane Smith",
              "jane@example.com",
              "2024-01-16",
              "980.50"
            ],
            [
              "3",
              "Bob Johnson",
              "bob@example.com",
              "2024-01-17",
              "2100.75"
            ]
          ]
        },
        "properties": {
          "headers": {
            "description": "Column headers from the CSV file. If has_header=false, generated as column_1, column_2, etc.",
            "examples": [
              [
                "id",
                "name",
                "email",
                "created_at",
                "revenue"
              ]
            ],
            "items": {
              "type": "string"
            },
            "title": "Headers",
            "type": "array"
          },
          "metadata": {
            "$ref": "#/components/schemas/CSVMetadata",
            "description": "File metadata and statistics"
          },
          "preview_rows": {
            "description": "First 5 data rows from the CSV file for preview",
            "examples": [
              [
                [
                  "1",
                  "John Doe",
                  "john@example.com",
                  "2024-01-15",
                  "1250.00"
                ],
                [
                  "2",
                  "Jane Smith",
                  "jane@example.com",
                  "2024-01-16",
                  "980.50"
                ]
              ]
            ],
            "items": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "title": "Preview Rows",
            "type": "array"
          }
        },
        "required": [
          "headers",
          "preview_rows",
          "metadata"
        ],
        "title": "CSVPreviewResponse",
        "type": "object"
      },
      "CancelAction": {
        "description": "Action to cancel active processing.",
        "properties": {
          "action": {
            "const": "cancel",
            "default": "cancel",
            "title": "Action",
            "type": "string"
          },
          "message_type": {
            "const": "action",
            "default": "action",
            "title": "Message Type",
            "type": "string"
          }
        },
        "title": "CancelAction",
        "type": "object"
      },
      "ChatMessageResponse": {
        "description": "Response model for a chat message (used for database operations).\n\nAttributes:\n    id: Unique identifier for the message.\n    created_at: When the message was created.\n    updated_at: When the message was last updated.\n    sender: Who sent the message ('user' or 'assistant').\n    body: The content of the message.",
        "properties": {
          "body": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/StatusBody"
              },
              {
                "$ref": "#/components/schemas/ReasoningBody"
              },
              {
                "$ref": "#/components/schemas/MessageBody"
              },
              {
                "$ref": "#/components/schemas/WorkflowUpdateBody"
              },
              {
                "$ref": "#/components/schemas/ActionBody"
              },
              {
                "$ref": "#/components/schemas/TransitionToBuildBody"
              }
            ],
            "title": "Body"
          },
          "conversation_id": {
            "format": "uuid",
            "title": "Conversation Id",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "flow_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Flow ID associated with the conversation",
            "title": "Flow Id"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "sender": {
            "$ref": "#/components/schemas/MessageSender"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "sender",
          "body",
          "conversation_id"
        ],
        "title": "ChatMessageResponse",
        "type": "object"
      },
      "ChatMessagesListResponse": {
        "description": "Response model for listing chat messages.\n\nReturns paginated conversation history in chronological order (oldest first).\nIncludes all message types: text, reasoning, status, actions, workflow updates.",
        "properties": {
          "limit": {
            "description": "Number of messages per page (1-100)",
            "title": "Limit",
            "type": "integer"
          },
          "messages": {
            "description": "List of chat messages with polymorphic bodies",
            "items": {
              "$ref": "#/components/schemas/ChatMessageResponse"
            },
            "title": "Messages",
            "type": "array"
          },
          "page": {
            "description": "Current page number (starting from 1)",
            "title": "Page",
            "type": "integer"
          },
          "total": {
            "description": "Total number of messages in conversation",
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "messages",
          "total",
          "page",
          "limit"
        ],
        "title": "ChatMessagesListResponse",
        "type": "object"
      },
      "ChatStreamRequest": {
        "description": "Request model for sending messages to conversational agent with streaming response.\n\nThis model wraps the polymorphic UserMessage type which supports both text\nmessages and action commands. The message type determines agent behavior\nand response processing.",
        "properties": {
          "message": {
            "$ref": "#/components/schemas/UserMessage",
            "description": "User message or action to send to agent. Polymorphic field supporting: \n\n**UserTextMessage**: Regular text message\n  - message: Natural language text for agent\n  - message_type: 'user_message'\n\n**ConfirmPlanAction**: Confirm proposed workflow plan\n  - action: 'confirm_plan'\n  - message_type: 'action'\n\n**CancelAction**: Cancel active processing\n  - action: 'cancel'\n  - message_type: 'action'\n\n**AcceptWorkflowAction**: Accept generated workflow\n  - action: 'accept_workflow'\n  - flow_definition: dict - Workflow to accept\n  - message_type: 'action'\n\n**RejectWorkflowAction**: Reject workflow with feedback\n  - action: 'reject_workflow'\n  - flow_definition: dict - Workflow to reject\n  - message_type: 'action'\n\n**InitiateErrorResolveAction**: Start error resolution\n  - action: 'initiate_error_resolve'\n  - message_type: 'action'\n\n**ResolveErrorsAction**: Apply error fixes\n  - action: 'resolve_errors'\n  - message_type: 'action'",
            "examples": [
              {
                "message": "Create a workflow that sends daily email reports",
                "message_type": "user_message"
              },
              {
                "action": "confirm_plan",
                "message_type": "action"
              },
              {
                "action": "accept_workflow",
                "flow_definition": {
                  "tasks": []
                },
                "message_type": "action"
              }
            ]
          }
        },
        "required": [
          "message"
        ],
        "title": "ChatStreamRequest",
        "type": "object"
      },
      "ConfirmPlanAction": {
        "description": "Action to confirm the plan and transition to build phase.",
        "properties": {
          "action": {
            "const": "confirm_plan",
            "default": "confirm_plan",
            "title": "Action",
            "type": "string"
          },
          "message_type": {
            "const": "action",
            "default": "action",
            "title": "Message Type",
            "type": "string"
          }
        },
        "title": "ConfirmPlanAction",
        "type": "object"
      },
      "ConfirmationRequestData": {
        "description": "Data for confirmation request actions.",
        "properties": {
          "accept": {
            "additionalProperties": true,
            "title": "Accept",
            "type": "object"
          },
          "reject": {
            "additionalProperties": true,
            "title": "Reject",
            "type": "object"
          }
        },
        "required": [
          "accept",
          "reject"
        ],
        "title": "ConfirmationRequestData",
        "type": "object"
      },
      "ConversationPhase": {
        "description": "Enumeration for conversation phases.",
        "enum": [
          "plan",
          "build"
        ],
        "title": "ConversationPhase",
        "type": "string"
      },
      "ConversationResponse": {
        "description": "Response model for a conversation.\n\nAttributes:\n    id: Unique identifier for the conversation.\n    created_at: When the conversation was created.\n    updated_at: When the conversation was last updated.\n    user_id: ID of the user who owns this conversation.\n    flow_id: ID of the flow which is bound with this conversation.\n    phase: Current conversation phase (planning/building/execution/error_resolution).",
        "properties": {
          "created_at": {
            "description": "Conversation creation timestamp (ISO 8601 UTC)",
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "flow_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Associated workflow identifier (UUID)",
            "title": "Flow Id"
          },
          "id": {
            "description": "Unique conversation identifier (UUID)",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "phase": {
            "description": "Current phase: planning, building, execution, or error_resolution",
            "title": "Phase",
            "type": "string"
          },
          "updated_at": {
            "description": "Last activity timestamp (ISO 8601 UTC)",
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "user_id": {
            "description": "Owner user identifier (matches JWT)",
            "title": "User Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "user_id",
          "phase"
        ],
        "title": "ConversationResponse",
        "type": "object"
      },
      "ConversationsListResponse": {
        "description": "Response model for listing conversations.\n\nReturns all conversations for authenticated user, ordered by creation date (newest first).",
        "properties": {
          "conversations": {
            "description": "List of user's conversations",
            "items": {
              "$ref": "#/components/schemas/ConversationResponse"
            },
            "title": "Conversations",
            "type": "array"
          },
          "total": {
            "description": "Total number of conversations for this user",
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "conversations",
          "total"
        ],
        "title": "ConversationsListResponse",
        "type": "object"
      },
      "CreateConversationResponse": {
        "description": "Response model for successful conversation creation.\n\nContains identifiers for the new conversation session and associated workflow.\nUse these IDs for subsequent operations like sending messages, retrieving\nhistory, or updating workflow state.",
        "properties": {
          "conversation_id": {
            "description": "Unique identifier for the created conversation session (UUID format). Use for: POST /agent/conversations/{id}/chat/stream (send messages), GET /agent/conversations/{id}/messages (retrieve history), PATCH /agent/conversations/{id} (update phase). Persists indefinitely for audit trail.",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "title": "Conversation Id",
            "type": "string"
          },
          "flow_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Workflow identifier associated with this conversation (UUID format). Either existing flow_id (if provided in request) or newly created. Use for: GET /api/flows/{id} (retrieve definition), POST /api/flow-executions (execute workflow), PUT /api/flows/{id} (update directly).",
            "examples": [
              "660e8400-e29b-41d4-a716-446655440001"
            ],
            "title": "Flow Id"
          }
        },
        "required": [
          "conversation_id",
          "flow_id"
        ],
        "title": "CreateConversationResponse",
        "type": "object"
      },
      "CreateCreditGrantRequest": {
        "description": "Request to create a credit grant.",
        "properties": {
          "amount": {
            "description": "Credits to grant (must be positive)",
            "exclusiveMinimum": 0.0,
            "title": "Amount",
            "type": "integer"
          },
          "reason": {
            "default": "Manual grant by admin",
            "description": "Reason for grant",
            "maxLength": 500,
            "title": "Reason",
            "type": "string"
          }
        },
        "required": [
          "amount"
        ],
        "title": "CreateCreditGrantRequest",
        "type": "object"
      },
      "CreateOrganizationRequest": {
        "description": "API request model for creating a new organization.\n\nOrganizations represent isolated tenants with their own users, flows,\nand executions. Each organization maintains data isolation and separate\naccess control.",
        "properties": {
          "is_active": {
            "default": true,
            "description": "Whether the organization is active. Active organizations allow user logins and flow executions. Inactive organizations are read-only. Default: True (organization created in active state)",
            "title": "Is Active",
            "type": "boolean"
          },
          "name": {
            "description": "Organization display name. Must be unique across the platform. Used in UI, reports, and organization selection interfaces. Constraints: 1-200 characters, cannot be empty or whitespace only.",
            "examples": [
              "Acme Corporation",
              "Engineering Team",
              "Customer Success"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "title": "CreateOrganizationRequest",
        "type": "object"
      },
      "CreateProductRequest": {
        "description": "Request model for creating a new billable product.\n\nUsed to register new products in the usage tracking system.\nAll products must have a name, unit, and provider defined.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "maxLength": 1000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional detailed description of the product. Explains what the product represents and how it's consumed. Useful for billing reports and usage dashboards.",
            "examples": [
              "Input and output tokens consumed by GPT-4 model inference"
            ],
            "title": "Description"
          },
          "estimated_cost_per_unit": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Estimated cost per unit of consumption in USD. Used to calculate total estimated cost for usage records. May be null if cost data is unavailable. Example: 0.00003 for $0.03 per 1000 tokens",
            "examples": [
              3e-05,
              0.001,
              0.1
            ],
            "title": "Estimated Cost Per Unit"
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional additional product metadata. Flexible field for provider-specific details, pricing tiers, model versions, or other contextual information. Structure varies by product type.",
            "examples": [
              {
                "model": "gpt-4-turbo",
                "region": "us-east-1",
                "tier": "standard"
              }
            ],
            "title": "Metadata"
          },
          "name": {
            "description": "Product display name. Must be unique across all products. Human-readable identifier for the billable resource. Examples: 'GPT-4 Tokens', 'Claude Sonnet API Calls', 'Compute Minutes'",
            "examples": [
              "GPT-4 Tokens",
              "Claude Sonnet API Calls"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Name",
            "type": "string"
          },
          "provider": {
            "description": "Service provider or vendor supplying the product. Used to group costs by provider for billing analysis. Examples: 'OpenAI', 'Anthropic', 'AWS', 'GCP', 'Azure'",
            "examples": [
              "OpenAI",
              "Anthropic",
              "AWS",
              "Google Cloud"
            ],
            "maxLength": 100,
            "minLength": 1,
            "title": "Provider",
            "type": "string"
          },
          "unit": {
            "description": "Unit of measurement for product consumption. Used to quantify usage amounts. Must be consistent. Examples: 'tokens', 'requests', 'seconds', 'GB', 'minutes'",
            "examples": [
              "tokens",
              "requests",
              "seconds",
              "GB"
            ],
            "maxLength": 50,
            "minLength": 1,
            "title": "Unit",
            "type": "string"
          }
        },
        "required": [
          "name",
          "unit",
          "provider"
        ],
        "title": "CreateProductRequest",
        "type": "object"
      },
      "CreateTaskExecutionRequest": {
        "description": "Request model for creating or updating a task execution.\n\nThis model is used by system workers to report task execution state.\nFields are intentionally simplified to reduce worker complexity.\nThe server infers additional fields like organization_id and timestamps.",
        "properties": {
          "error": {
            "description": "Error information when task execution fails. Only set when status is 'failed'. Contains error message, type, and stack trace. Structure: {'message': str, 'type': str, 'traceback': str} Used for debugging and error reporting.",
            "examples": [
              {
                "message": "Connection timeout after 30s",
                "traceback": "...",
                "type": "ConnectionError"
              }
            ],
            "title": "Error"
          },
          "flow_execution_id": {
            "description": "ID of the parent flow execution containing this task. Used to determine organization_id and maintain execution hierarchy.",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "input": {
            "description": "Input parameters provided to the task executor. Schema varies by task type. Can be dict, list, or primitive types. NULL if task has no input parameters.",
            "examples": [
              {
                "recipient": "user@example.com",
                "subject": "Hello"
              },
              [
                1,
                2,
                3,
                4,
                5
              ],
              "simple string input"
            ],
            "title": "Input"
          },
          "output": {
            "description": "Output data produced by the task executor upon completion. Only set when status is 'completed'. NULL for queued/running/failed states. Available to downstream tasks via {{task_name.output}} syntax.",
            "examples": [
              {
                "email_id": "msg_123",
                "sent_at": "2025-01-23T10:30:00Z"
              },
              {
                "errors": 0,
                "processed_rows": 150
              }
            ],
            "title": "Output"
          },
          "status": {
            "description": "Current execution status of the task. Valid values: 'queued', 'running', 'completed', 'failed', 'cancelled'. Server validates against ExecutionStatus enum. Status transitions are: queued \u2192 running \u2192 (completed|failed|cancelled).",
            "examples": [
              "running",
              "completed",
              "failed"
            ],
            "title": "Status",
            "type": "string"
          },
          "task_execution_idx": {
            "description": "Zero-based execution index for this task. Increments for each execution of the same task (retries, loops). Combines with flow_execution_id and task_name to form unique identifier.",
            "examples": [
              0,
              1,
              2
            ],
            "minimum": 0.0,
            "title": "Task Execution Idx",
            "type": "integer"
          },
          "task_name": {
            "description": "Name of the task as defined in the flow definition YAML. Must match a task name in the flow's task list. Case-sensitive identifier used for task lookups.",
            "examples": [
              "send_email",
              "process_data",
              "validate_input"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Task Name",
            "type": "string"
          }
        },
        "required": [
          "flow_execution_id",
          "task_name",
          "task_execution_idx",
          "status"
        ],
        "title": "CreateTaskExecutionRequest",
        "type": "object"
      },
      "CreateUsageRequest": {
        "description": "Request model for creating a new usage record.\n\nRecords consumption of a product during a flow execution.\nUsed for usage tracking and cost estimation.",
        "properties": {
          "amount": {
            "description": "Quantity of units consumed. Must be a positive integer. Example: 1500 for 1500 tokens, 10 for 10 API requests",
            "examples": [
              1500,
              10,
              3600
            ],
            "exclusiveMinimum": 0.0,
            "title": "Amount",
            "type": "integer"
          },
          "estimated_cost": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional pre-calculated estimated cost in USD. If provided, overrides product's estimated_cost_per_unit calculation. Useful when exact cost is known from provider.",
            "examples": [
              0.045,
              0.01,
              1.25
            ],
            "title": "Estimated Cost"
          },
          "flow_execution_id": {
            "description": "Identifier of the flow execution that consumed the product. Links usage to specific workflow run for traceability. Must be a valid flow execution ID.",
            "examples": [
              "abc12345-6789-def0-1234-56789abcdef0"
            ],
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional metadata about the usage context. May include task_name, model parameters, or other details. Structure varies by product type.",
            "examples": [
              {
                "model": "gpt-4",
                "task_name": "generate_summary",
                "tokens_input": 1000,
                "tokens_output": 500
              }
            ],
            "title": "Metadata"
          },
          "product_id": {
            "description": "Identifier of the product that was consumed. Must reference an existing product in the system. Use GET /internal/products to list available products.",
            "examples": [
              "7c9e6679-7425-40de-944b-e07fc1f90ae7"
            ],
            "format": "uuid",
            "title": "Product Id",
            "type": "string"
          }
        },
        "required": [
          "flow_execution_id",
          "product_id",
          "amount"
        ],
        "title": "CreateUsageRequest",
        "type": "object"
      },
      "CreateUserRequest": {
        "description": "API request model for creating a new user.\n\nCreates a user in both the platform and authentication system.\nThe user receives an email invitation to activate their account and set\na password. User creation is atomic across both systems.",
        "properties": {
          "email": {
            "description": "User's email address. Required, must be valid email format. Used for login, authentication, and invitation emails. Must be unique within the organization. Email invitation automatically sent to this address upon user creation.",
            "examples": [
              "john.doe@example.com",
              "jane.smith@company.com"
            ],
            "format": "email",
            "title": "Email",
            "type": "string"
          },
          "first_name": {
            "description": "User's first name. Required. Used in UI displays and email communications. Constraints: 1-100 characters, cannot be empty.",
            "examples": [
              "John",
              "Jane",
              "Alex"
            ],
            "maxLength": 100,
            "minLength": 1,
            "title": "First Name",
            "type": "string"
          },
          "is_active": {
            "default": true,
            "description": "Whether user account is active. Optional, defaults to True. Inactive users cannot log in or access the system. Note: User must still accept email invitation to log in, even if is_active is True. Default: True (user created in active state pending invitation acceptance)",
            "title": "Is Active",
            "type": "boolean"
          },
          "last_name": {
            "description": "User's last name. Required. Used in UI displays and email communications. Constraints: 1-100 characters, cannot be empty.",
            "examples": [
              "Doe",
              "Smith",
              "Johnson"
            ],
            "maxLength": 100,
            "minLength": 1,
            "title": "Last Name",
            "type": "string"
          },
          "organization_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "UUID of the organization to create user in. Optional. When using POST /admin/organizations/{id}/users endpoint, this field is ignored and path parameter is used instead. When using POST /admin/users endpoint, this field is required. Organization must exist and be active.",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "title": "Organization Id"
          },
          "role": {
            "description": "User's role within the organization. Required. Determines permission level and feature access. Valid values: 'org_admin', 'backoffice', 'app_user', 'integration'. \n\nRole permissions:\n- 'org_admin': Full access to organization resources and user management\n- 'backoffice': Super admin with platform-level access\n- 'app_user': Can create and manage own flows and executions\n- 'integration': Service account for integrations and automated workflows",
            "examples": [
              "org_admin",
              "app_user",
              "backoffice"
            ],
            "title": "Role",
            "type": "string"
          }
        },
        "required": [
          "first_name",
          "last_name",
          "email",
          "role"
        ],
        "title": "CreateUserRequest",
        "type": "object"
      },
      "CredentialProvider": {
        "description": "Credential provider model",
        "properties": {
          "credential_schema": {
            "additionalProperties": true,
            "title": "Credential Schema",
            "type": "object"
          },
          "is_oauth": {
            "title": "Is Oauth",
            "type": "boolean"
          },
          "name": {
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "is_oauth",
          "name",
          "credential_schema"
        ],
        "title": "CredentialProvider",
        "type": "object"
      },
      "CredentialTypeEnum": {
        "enum": [
          "api_key",
          "oauth2",
          "user_password",
          "key_file",
          "client_credentials",
          "sharepoint_receive",
          "google_drive_receive"
        ],
        "title": "CredentialTypeEnum",
        "type": "string"
      },
      "CredentialsResponse": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "provider": {
            "$ref": "#/components/schemas/ProviderApiEnum"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "user_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "User Id"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "name",
          "provider"
        ],
        "title": "CredentialsResponse",
        "type": "object"
      },
      "CreditBalanceResponse": {
        "description": "Credit balance for an organization (M1: grants only, no usage yet).",
        "properties": {
          "credits_consumed": {
            "default": 0,
            "description": "Credits consumed (always 0 for M1)",
            "title": "Credits Consumed",
            "type": "integer"
          },
          "credits_granted": {
            "description": "Total credits granted to organization",
            "title": "Credits Granted",
            "type": "integer"
          },
          "credits_remaining": {
            "description": "Credits remaining (same as granted for M1)",
            "title": "Credits Remaining",
            "type": "integer"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "credits_granted",
          "credits_remaining"
        ],
        "title": "CreditBalanceResponse",
        "type": "object"
      },
      "CreditGrantResponse": {
        "description": "Single credit grant response.",
        "properties": {
          "amount": {
            "title": "Amount",
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "granted_by": {
            "title": "Granted By",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "reason": {
            "title": "Reason",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "organization_id",
          "amount",
          "reason",
          "granted_by"
        ],
        "title": "CreditGrantResponse",
        "type": "object"
      },
      "DatabaseColumnsResponse": {
        "description": "Response containing database column information.\n\nReturned by GET /database/{db_id}/columns endpoint.",
        "example": {
          "column_count": 6,
          "columns": [
            "id",
            "name",
            "email",
            "created_at",
            "revenue",
            "region"
          ],
          "database_id": "123e4567-e89b-12d3-a456-426614174000"
        },
        "properties": {
          "column_count": {
            "description": "Total number of columns",
            "examples": [
              6
            ],
            "minimum": 0.0,
            "title": "Column Count",
            "type": "integer"
          },
          "columns": {
            "description": "List of column names in the database",
            "examples": [
              [
                "id",
                "name",
                "email",
                "created_at",
                "revenue",
                "region"
              ]
            ],
            "items": {
              "type": "string"
            },
            "title": "Columns",
            "type": "array"
          },
          "database_id": {
            "description": "Database identifier",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000"
            ],
            "title": "Database Id",
            "type": "string"
          }
        },
        "required": [
          "database_id",
          "columns",
          "column_count"
        ],
        "title": "DatabaseColumnsResponse",
        "type": "object"
      },
      "DatabaseDownloadResponse": {
        "description": "Response containing download URL for database file.",
        "properties": {
          "download_url": {
            "description": "Pre-signed URL for downloading the database file from cloud storage.",
            "examples": [
              "https://storage.googleapis.com/bucket/path/file.csv?signature=abc123&expires=1640000000"
            ],
            "title": "Download Url",
            "type": "string"
          }
        },
        "required": [
          "download_url"
        ],
        "title": "DatabaseDownloadResponse",
        "type": "object"
      },
      "DirectAgentRequest": {
        "description": "Request model for stateless agent invocation without conversation context.\n\nUse this model for one-off agent operations that don't require conversational\nhistory or state persistence. Suitable for automation, testing, and quick\nworkflow operations.",
        "properties": {
          "agent_type": {
            "default": "WORKFLOW_BUILDER",
            "description": "Type of agent to invoke. Determines agent's capabilities and behavior. \n\nValid values:\n\n**WORKFLOW_BUILDER** (default):\nConstructs complete workflow definitions from requirements. Selects tasks, configures parameters, and validates structure. Use for: Creating new workflows, modifying existing workflows, adding tasks and integrations.\n\n**WORKFLOW_PLANNER**:\nAnalyzes requirements and plans task structure without building. Proposes task breakdown, dependencies, and integration requirements. Use for: Planning complex workflows, understanding requirements, estimating complexity before building.\n\n**WORKFLOW_SUMMARIZER**:\nSummarizes and explains existing workflow state. Identifies issues, suggests improvements, explains task purposes. Use for: Understanding workflows, debugging, reviewing configurations, getting improvement suggestions.",
            "examples": [
              "WORKFLOW_BUILDER",
              "WORKFLOW_PLANNER",
              "WORKFLOW_SUMMARIZER"
            ],
            "title": "Agent Type",
            "type": "string"
          },
          "prompt": {
            "description": "Natural language prompt or question for agent. Agent interprets based on agent_type and workflow_state. \n\nPrompt should clearly describe the task or question. Include relevant details for accurate agent response. \n\nExamples by agent type:\n\n**WORKFLOW_BUILDER**:\n- 'Create a workflow that processes daily sales reports'\n- 'Add email notification task to existing workflow'\n- 'Generate workflow for customer onboarding process'\n\n**WORKFLOW_PLANNER**:\n- 'Plan tasks needed for automated invoice generation'\n- 'Break down customer data migration into steps'\n- 'Identify dependencies for multi-stage deployment'\n\n**WORKFLOW_SUMMARIZER**:\n- 'Summarize the current workflow state'\n- 'Explain what this workflow does'\n- 'Identify incomplete or misconfigured tasks'",
            "examples": [
              "Create a workflow that sends weekly summary emails",
              "Plan tasks for automated customer onboarding",
              "Summarize this workflow and suggest improvements"
            ],
            "minLength": 1,
            "title": "Prompt",
            "type": "string"
          },
          "workflow_state": {
            "additionalProperties": true,
            "description": "Optional workflow context for agent to reference. Provides existing workflow state for modifications or analysis. \n\nStructure:\n- tasks: List of task objects (required)\n  - id: Task identifier\n  - type: Task executor type\n  - parameters: Task configuration\n- dependencies: Dict mapping task IDs to prerequisite IDs (optional)\n- metadata: Workflow-level settings (optional)\n\nUse cases:\n- Empty state {\"tasks\": []}: Create new workflow from scratch\n- With tasks: Modify or analyze existing workflow\n- Full workflow: Comprehensive analysis or summarization",
            "examples": [
              {
                "tasks": []
              },
              {
                "tasks": [
                  {
                    "id": "task1",
                    "parameters": {},
                    "type": "send_email"
                  }
                ]
              },
              {
                "dependencies": {
                  "t2": [
                    "t1"
                  ]
                },
                "tasks": [
                  {
                    "id": "t1",
                    "type": "fetch_data"
                  },
                  {
                    "id": "t2",
                    "type": "process"
                  }
                ]
              }
            ],
            "title": "Workflow State",
            "type": "object"
          }
        },
        "required": [
          "prompt"
        ],
        "title": "DirectAgentRequest",
        "type": "object"
      },
      "DirectAgentResponse": {
        "description": "Response from direct agent invocation.\n\nAttributes:\n    chunks: List of response chunks from the agent.",
        "properties": {
          "chunks": {
            "items": {
              "$ref": "#/components/schemas/AgentResponseChunk"
            },
            "title": "Chunks",
            "type": "array"
          }
        },
        "required": [
          "chunks"
        ],
        "title": "DirectAgentResponse",
        "type": "object"
      },
      "DocumentFileCreateRequest": {
        "description": "Request to create a new document file entry.",
        "properties": {
          "credential_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Credential ID for PostgreSQL databases",
            "title": "Credential Id"
          },
          "database_type": {
            "default": "csv",
            "description": "Type of database",
            "enum": [
              "csv",
              "postgres"
            ],
            "title": "Database Type",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Document description",
            "title": "Description"
          },
          "name": {
            "description": "Document name",
            "title": "Name",
            "type": "string"
          },
          "table_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Table name for PostgreSQL databases",
            "title": "Table Name"
          }
        },
        "required": [
          "name"
        ],
        "title": "DocumentFileCreateRequest",
        "type": "object"
      },
      "DocumentFileResponse": {
        "description": "Response for document file operations.",
        "properties": {
          "created_at": {
            "description": "Creation timestamp",
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "current_file_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current file ID in bucket",
            "title": "Current File Id"
          },
          "current_table_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Current dataset name",
            "title": "Current Table Name"
          },
          "database_type": {
            "description": "Type of database",
            "enum": [
              "csv",
              "postgres"
            ],
            "title": "Database Type",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Document description",
            "title": "Description"
          },
          "id": {
            "description": "Document file ID",
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "default": "system",
            "description": "User ID (UUID string) or 'system' of the actor who last modified the file. For users, stores UUID string; for integrations, stores type value; for system changes, stores 'system'.",
            "title": "Modified By",
            "type": "string"
          },
          "name": {
            "description": "Document name",
            "title": "Name",
            "type": "string"
          },
          "revision_count": {
            "default": 0,
            "description": "Number of file revisions",
            "title": "Revision Count",
            "type": "integer"
          },
          "status": {
            "description": "File status",
            "title": "Status",
            "type": "string"
          },
          "total_rows": {
            "default": 0,
            "description": "Total rows in current file",
            "title": "Total Rows",
            "type": "integer"
          },
          "updated_at": {
            "description": "Last update timestamp",
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "database_type",
          "status",
          "created_at",
          "updated_at"
        ],
        "title": "DocumentFileResponse",
        "type": "object"
      },
      "DocumentationLinks": {
        "description": "Links to API documentation resources.",
        "properties": {
          "interactive": {
            "description": "External interactive documentation portal",
            "examples": [
              "https://docs.flows.super.ai"
            ],
            "title": "Interactive",
            "type": "string"
          },
          "openapi": {
            "description": "Swagger UI interactive documentation",
            "examples": [
              "/api/docs"
            ],
            "title": "Openapi",
            "type": "string"
          },
          "openapi_json": {
            "description": "Raw OpenAPI specification in JSON format",
            "examples": [
              "/api/openapi.json"
            ],
            "title": "Openapi Json",
            "type": "string"
          },
          "redoc": {
            "description": "ReDoc alternative documentation UI",
            "examples": [
              "/api/redoc"
            ],
            "title": "Redoc",
            "type": "string"
          }
        },
        "required": [
          "openapi",
          "redoc",
          "openapi_json",
          "interactive"
        ],
        "title": "DocumentationLinks",
        "type": "object"
      },
      "EmailTaskRequest": {
        "description": "Request to create an email task.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Task description",
            "title": "Description"
          },
          "flow_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Flow ID for deduplication",
            "title": "Flow Id"
          },
          "name": {
            "description": "Task name",
            "title": "Name",
            "type": "string"
          },
          "task_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Task name for deduplication",
            "title": "Task Name"
          }
        },
        "required": [
          "name"
        ],
        "title": "EmailTaskRequest",
        "type": "object"
      },
      "EmailTaskResponse": {
        "description": "Response from email task creation.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Task description",
            "title": "Description"
          },
          "email_address": {
            "description": "Generated email address",
            "title": "Email Address",
            "type": "string"
          },
          "name": {
            "description": "Task name",
            "title": "Name",
            "type": "string"
          },
          "status": {
            "default": "active",
            "description": "Task status",
            "title": "Status",
            "type": "string"
          },
          "task_id": {
            "description": "Unique task identifier",
            "title": "Task Id",
            "type": "string"
          }
        },
        "required": [
          "task_id",
          "email_address",
          "name"
        ],
        "title": "EmailTaskResponse",
        "type": "object"
      },
      "EmailTaskStatus": {
        "description": "Status of an email task.",
        "properties": {
          "created_at": {
            "title": "Created At",
            "type": "string"
          },
          "email_address": {
            "title": "Email Address",
            "type": "string"
          },
          "email_count": {
            "default": 0,
            "title": "Email Count",
            "type": "integer"
          },
          "last_email_received": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Last Email Received"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "task_id": {
            "title": "Task Id",
            "type": "string"
          }
        },
        "required": [
          "task_id",
          "email_address",
          "status",
          "created_at"
        ],
        "title": "EmailTaskStatus",
        "type": "object"
      },
      "ErrorDetail": {
        "description": "Standard error detail structure.\n\nThis model matches the error format returned by the centralized\nexception handlers in app/api/errors/handlers.py.",
        "properties": {
          "code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Machine-readable error code for programmatic handling",
            "title": "Code"
          },
          "details": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Additional error context, validation errors, or debugging information",
            "title": "Details"
          },
          "message": {
            "description": "Human-readable error message",
            "title": "Message",
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "title": "ErrorDetail",
        "type": "object"
      },
      "ErrorDetails": {
        "properties": {
          "ctx": {
            "additionalProperties": true,
            "title": "Ctx",
            "type": "object"
          },
          "input": {
            "title": "Input"
          },
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "title": "Loc",
            "type": "array"
          },
          "msg": {
            "title": "Msg",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          },
          "url": {
            "title": "Url",
            "type": "string"
          }
        },
        "required": [
          "type",
          "loc",
          "msg",
          "input"
        ],
        "title": "ErrorDetails",
        "type": "object"
      },
      "ErrorResponse": {
        "description": "Standard API error response structure.\n\nAll error responses from the API follow this format, ensuring\nconsistent error handling for API consumers.\n\nExample:\n    {\n        \"error\": {\n            \"message\": \"Flow not found\",\n            \"code\": \"not_found\"\n        },\n        \"request_id\": \"01K8KABR6S16YETA2SZPVBS9SP\"\n    }",
        "examples": [
          {
            "error": {
              "code": "not_found",
              "message": "Resource not found"
            },
            "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
          }
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          },
          "request_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Unique request identifier in ULID format for debugging and support. Example: 01K8KABR6S16YETA2SZPVBS9SP",
            "title": "Request Id"
          }
        },
        "required": [
          "error"
        ],
        "title": "ErrorResponse",
        "type": "object"
      },
      "ErrorSummary": {
        "description": "Summary of errors for a specific task parameter.",
        "properties": {
          "error_message": {
            "title": "Error Message",
            "type": "string"
          }
        },
        "required": [
          "error_message"
        ],
        "title": "ErrorSummary",
        "type": "object"
      },
      "ErrorSummaryData": {
        "description": "Data for error summary actions.",
        "properties": {
          "flow_errors": {
            "items": {
              "$ref": "#/components/schemas/ErrorSummary"
            },
            "title": "Flow Errors",
            "type": "array"
          },
          "task_errors": {
            "items": {
              "$ref": "#/components/schemas/TaskErrorData"
            },
            "title": "Task Errors",
            "type": "array"
          }
        },
        "required": [
          "task_errors",
          "flow_errors"
        ],
        "title": "ErrorSummaryData",
        "type": "object"
      },
      "ExecutionStatus": {
        "description": "Valid status values for flow execution lifecycle.\n\nStatus Transitions:\n    queued \u2192 running \u2192 in_progress \u2192 completed\n                                   \u2192 failed\n\n    Any status \u2192 deleted (soft delete)\n    completed/failed \u2192 stale (data outdated)\n\nStatus Definitions:\n    - queued: Execution created but workflow not yet started\n    - running: Workflow started, initial tasks executing\n    - in_progress: Workflow actively processing tasks\n    - completed: All tasks finished successfully\n    - failed: One or more tasks failed, workflow stopped\n    - deleted: Soft deleted, hidden from list operations\n    - stale: Previously completed but data is now outdated",
        "enum": [
          "queued",
          "running",
          "in_progress",
          "completed",
          "failed",
          "deleted",
          "stale",
          "awaiting_input"
        ],
        "title": "ExecutionStatus",
        "type": "string"
      },
      "FileUploadCompleteRequest": {
        "description": "Request to complete file upload and process the file.",
        "properties": {
          "delimiter": {
            "default": ",",
            "description": "CSV delimiter character",
            "title": "Delimiter",
            "type": "string"
          },
          "has_header": {
            "default": true,
            "description": "Whether CSV has header row",
            "title": "Has Header",
            "type": "boolean"
          },
          "table_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Override table name (optional)",
            "title": "Table Name"
          },
          "upload_id": {
            "description": "Upload identifier from prepare step",
            "title": "Upload Id",
            "type": "string"
          }
        },
        "required": [
          "upload_id"
        ],
        "title": "FileUploadCompleteRequest",
        "type": "object"
      },
      "FlowCreateRequest": {
        "description": "Request body for creating a new flow.\n\nFlows represent workflow definitions with tasks, dependencies, and execution logic.\nUpon creation, flows are assigned version 1 and status 'draft'.",
        "properties": {
          "definition": {
            "additionalProperties": true,
            "description": "Flow definition in DSL format. Must include tasks array, edges array, and version. See Flow DSL documentation for schema details.",
            "title": "Definition",
            "type": "object"
          },
          "description": {
            "anyOf": [
              {
                "maxLength": 5000,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional detailed description of the flow's purpose and behavior. Supports markdown.",
            "title": "Description"
          },
          "display_name": {
            "description": "Human-readable name for the flow. Displayed in UI and logs.",
            "maxLength": 255,
            "minLength": 1,
            "title": "Display Name",
            "type": "string"
          },
          "settings": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FlowSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Flow-level configuration settings."
          },
          "visibility": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Access control level. Determines who can view and execute this flow. Options: 'private' (creator only), 'organization' (all org members), 'public' (anyone with link).",
            "title": "Visibility"
          }
        },
        "required": [
          "display_name",
          "definition"
        ],
        "title": "FlowCreateRequest",
        "type": "object"
      },
      "FlowDefinitionUpdate": {
        "description": "Model for flow definition update request.",
        "properties": {
          "definition": {
            "additionalProperties": true,
            "title": "Definition",
            "type": "object"
          }
        },
        "required": [
          "definition"
        ],
        "title": "FlowDefinitionUpdate",
        "type": "object"
      },
      "FlowExecutionCreateRequest": {
        "description": "Request payload for creating a new flow execution.\n\nThis model defines the required data to start a new flow execution.\nThe input schema must match the flow definition's expected input structure.",
        "properties": {
          "flow_id": {
            "description": "UUID of the flow definition to execute. Must be a valid, active flow accessible to your organization. The flow defines the workflow structure and task sequence.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Flow Id",
            "type": "string"
          },
          "input": {
            "additionalProperties": true,
            "description": "Input data for the flow execution. Schema is flow-specific. Common patterns: - Document processing: {'file_key': 'path/to/file.pdf'} - Data processing: {'document_url': 'gs://bucket/file.csv'} - Email processing: {'message_id': 'msg_123', 'attachments': []} Refer to flow definition for exact schema requirements.",
            "example": {
              "file_key": "documents/report.pdf",
              "options": {
                "language": "en"
              }
            },
            "title": "Input",
            "type": "object"
          }
        },
        "required": [
          "flow_id",
          "input"
        ],
        "title": "FlowExecutionCreateRequest",
        "type": "object"
      },
      "FlowExecutionResponse": {
        "description": "Response model for flow execution operations.\n\nRepresents a single flow execution instance with its current state and metadata.\nFlow executions are runtime instances of flow definitions that process input data\nthrough a series of tasks defined in the flow's workflow.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "flow_id": {
            "description": "UUID of the flow definition being executed. References the parent flow that defines the workflow structure.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Flow Id",
            "type": "string"
          },
          "flow_version": {
            "description": "Version number of the flow definition used for this execution. Execution continues on the same version even if flow is updated. Ensures consistency throughout execution lifecycle.",
            "example": 3,
            "minimum": 1.0,
            "title": "Flow Version",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "input": {
            "additionalProperties": true,
            "description": "Input data provided when execution was created. Schema is defined by the flow definition. Commonly includes: file_key, document_url, or custom parameters. Structure varies by flow type.",
            "example": {
              "file_key": "documents/abc123.pdf",
              "metadata": {
                "priority": "high"
              }
            },
            "title": "Input",
            "type": "object"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "UUID of the organization that owns this execution. Used for access control and data isolation. All executions are scoped to an organization.",
            "example": "660e8400-e29b-41d4-a716-446655440001",
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "status": {
            "description": "Current execution status. Possible values: 'queued', 'running', 'in_progress', 'completed', 'failed', 'deleted', 'stale'. Status transitions: queued \u2192 running \u2192 in_progress \u2192 completed/failed. Use 'completed' to indicate success, 'failed' for errors.",
            "example": "running",
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "flow_id",
          "flow_version",
          "status",
          "input",
          "organization_id"
        ],
        "title": "FlowExecutionResponse",
        "type": "object"
      },
      "FlowExecutionResponseWithRunNumber": {
        "description": "Flow execution response with optional sequential run number.\n\nExtends FlowExecutionResponse to include an optional run_number field\nthat indicates the sequential position of this execution among all\nexecutions for the same flow (including deleted ones).",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "flow_id": {
            "description": "UUID of the flow definition being executed. References the parent flow that defines the workflow structure.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Flow Id",
            "type": "string"
          },
          "flow_version": {
            "description": "Version number of the flow definition used for this execution. Execution continues on the same version even if flow is updated. Ensures consistency throughout execution lifecycle.",
            "example": 3,
            "minimum": 1.0,
            "title": "Flow Version",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "input": {
            "additionalProperties": true,
            "description": "Input data provided when execution was created. Schema is defined by the flow definition. Commonly includes: file_key, document_url, or custom parameters. Structure varies by flow type.",
            "example": {
              "file_key": "documents/abc123.pdf",
              "metadata": {
                "priority": "high"
              }
            },
            "title": "Input",
            "type": "object"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "UUID of the organization that owns this execution. Used for access control and data isolation. All executions are scoped to an organization.",
            "example": "660e8400-e29b-41d4-a716-446655440001",
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "run_number": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Sequential run number for this execution within its flow. Starts at 1 for the first execution and increments by creation time. Includes deleted executions in count, so visible numbers may have gaps. Only populated when include_run_number=true query parameter is set. Null when not requested to avoid performance overhead.",
            "example": 42,
            "title": "Run Number"
          },
          "status": {
            "description": "Current execution status. Possible values: 'queued', 'running', 'in_progress', 'completed', 'failed', 'deleted', 'stale'. Status transitions: queued \u2192 running \u2192 in_progress \u2192 completed/failed. Use 'completed' to indicate success, 'failed' for errors.",
            "example": "running",
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "flow_id",
          "flow_version",
          "status",
          "input",
          "organization_id"
        ],
        "title": "FlowExecutionResponseWithRunNumber",
        "type": "object"
      },
      "FlowInvitationBulkResponse": {
        "description": "Response model for bulk invitation creation/update.",
        "properties": {
          "flow_id": {
            "format": "uuid",
            "title": "Flow Id",
            "type": "string"
          },
          "invited_user_ids": {
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "title": "Invited User Ids",
            "type": "array"
          },
          "message": {
            "title": "Message",
            "type": "string"
          },
          "skipped_user_ids": {
            "description": "User IDs that were skipped (not reviewer/publisher role)",
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "title": "Skipped User Ids",
            "type": "array"
          },
          "total_invitations": {
            "title": "Total Invitations",
            "type": "integer"
          }
        },
        "required": [
          "flow_id",
          "invited_user_ids",
          "total_invitations",
          "message"
        ],
        "title": "FlowInvitationBulkResponse",
        "type": "object"
      },
      "FlowInvitationRequest": {
        "description": "Request model for creating flow invitations.",
        "properties": {
          "user_ids": {
            "description": "List of user IDs to invite to the flow",
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "minItems": 1,
            "title": "User Ids",
            "type": "array"
          }
        },
        "required": [
          "user_ids"
        ],
        "title": "FlowInvitationRequest",
        "type": "object"
      },
      "FlowInvitationResponse": {
        "description": "Response model for a flow invitation.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "email": {
            "title": "Email",
            "type": "string"
          },
          "first_name": {
            "title": "First Name",
            "type": "string"
          },
          "flow_id": {
            "format": "uuid",
            "title": "Flow Id",
            "type": "string"
          },
          "last_name": {
            "title": "Last Name",
            "type": "string"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "role": {
            "$ref": "#/components/schemas/UserRole"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "user_id": {
            "format": "uuid",
            "title": "User Id",
            "type": "string"
          }
        },
        "required": [
          "flow_id",
          "user_id",
          "email",
          "first_name",
          "last_name",
          "role",
          "organization_id",
          "created_at",
          "updated_at"
        ],
        "title": "FlowInvitationResponse",
        "type": "object"
      },
      "FlowResponse": {
        "description": "Response model for a flow object.\n\nRepresents a complete flow definition with metadata, execution statistics,\nand optional computed fields. Use query parameters to include additional\nfields that require extra processing.\n\n## Expansion Parameters\n\nControl which computed fields are included using these query parameters:\n\n- `include_ordered_task_names`: Adds `task_names` field with topological sort\n- `include_validation_errors`: Adds `validation_errors` field if flow is invalid\n- `include_dynamic_data`: Enriches each task in `definition` with runtime config options\n- `include_output_schemas`: Enriches each task in `definition` with JSON schema\n\n## Performance Considerations\n\nEach expansion parameter adds processing overhead. Only request fields you need:\n\n- Base response: ~50-100ms\n- `+ include_ordered_task_names`: +50ms for 20+ tasks\n- `+ include_dynamic_data`: +100-500ms (calls external APIs)\n- `+ include_output_schemas`: +10-50ms\n- `+ include_validation_errors`: No overhead (always validated)",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "definition": {
            "additionalProperties": true,
            "description": "Complete flow definition in DSL format. May be enriched with additional fields when using expansion parameters (include_dynamic_data, include_output_schemas). Enriched fields are added to each task within definition.tasks[].",
            "title": "Definition",
            "type": "object"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Detailed flow description",
            "title": "Description"
          },
          "display_name": {
            "description": "Human-readable flow name",
            "title": "Display Name",
            "type": "string"
          },
          "flow_executions_count": {
            "default": 0,
            "description": "Total number of times this flow has been executed across all versions",
            "title": "Flow Executions Count",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "is_latest": {
            "description": "Whether this is the latest version of the flow",
            "title": "Is Latest",
            "type": "boolean"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "Organization that owns this flow",
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "settings": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FlowSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "Flow-level configuration settings"
          },
          "status": {
            "description": "Flow lifecycle status. Values: 'draft' (editable), 'published' (ready for production use)",
            "title": "Status",
            "type": "string"
          },
          "task_names": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Topologically sorted list of task names in execution order. Only included when include_ordered_task_names=true. Useful for visualizing task dependencies and execution flow.",
            "title": "Task Names"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "validation_errors": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/ErrorDetails"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "DSL validation errors if the flow definition is malformed. Only included when include_validation_errors=true. Empty list indicates a valid flow. Each error contains location and message details.",
            "title": "Validation Errors"
          },
          "version": {
            "description": "Flow version number. Increments on each update.",
            "minimum": 1.0,
            "title": "Version",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "display_name",
          "version",
          "status",
          "is_latest",
          "organization_id",
          "definition"
        ],
        "title": "FlowResponse",
        "type": "object"
      },
      "FlowSettings": {
        "description": "Flow-level settings configuration.",
        "properties": {
          "reexecute_on_update": {
            "default": false,
            "description": "Reexecute stale tasks on flow update",
            "title": "Reexecute On Update",
            "type": "boolean"
          },
          "ttl": {
            "$ref": "#/components/schemas/TTLSettings",
            "default": {},
            "description": "Time-to-live settings for automatic execution deletion"
          }
        },
        "title": "FlowSettings",
        "type": "object"
      },
      "FlowTaskStatusAPI": {
        "description": "API model for FlowTaskStatus.",
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Created At"
          },
          "flow_execution_id": {
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "task_name": {
            "title": "Task Name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "flow_execution_id",
          "task_name",
          "status",
          "organization_id"
        ],
        "title": "FlowTaskStatusAPI",
        "type": "object"
      },
      "FlowTaskTagAPI": {
        "description": "API model representing a task execution tag.\n\nTask tags provide flexible categorization and workflow state tracking for\ntask executions. Tags enable custom workflows like review processes, quality\nassurance, priority management, and domain-specific categorization.\n\nTags are scoped to (flow_execution_id, task_name) pairs and support:\n- Workflow state: Track review/approval status\n- Quality assurance: Flag issues or verify quality\n- Categorization: Apply business-specific labels\n- Audit trails: Record who tagged what and when\n\nLifecycle: Tags are soft-deleted (status='deleted') rather than hard-deleted\nto preserve audit history. Only active tags appear in list queries.",
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp when tag was created (UTC). Represents when tag was first added to task execution. NULL for legacy tags created before timestamp tracking. Used for audit trails and chronological sorting.",
            "examples": [
              "2025-01-24T10:30:00Z"
            ],
            "title": "Created At"
          },
          "flow_execution_id": {
            "description": "ID of the flow execution containing the tagged task. Establishes execution context and organization scope. Tags are scoped to flow executions; same task in different executions has independent tag sets. Used for filtering tags by execution.",
            "examples": [
              "223e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this tag record. Auto-generated UUID assigned at tag creation. Used for direct tag access and references.",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Identifier of actor who last modified this tag. Tracks who made the last change for auditing purposes. \n\nValues:\n- 'system': System-automated changes (workers, background jobs)\n- User ID: UUID string of the user who made the change (e.g., '123e4567-e89b-12d3-a456-426614174000')\n- Integration type: For service accounts/integrations (e.g., 'integration', 'service-account')\n\nFor deleted tags, indicates who performed soft deletion. NULL for tags never modified since creation. Used for audit trails and accountability.",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000",
              "integration",
              "system",
              null
            ],
            "title": "Modified By"
          },
          "organization_id": {
            "description": "ID of organization owning this tag. Inherited from parent flow execution for multi-tenant isolation. Used for Row-Level Security (RLS) filtering and authorization. All tags scoped to single organization; cross-org access forbidden. Queries automatically filtered by user's organization_id.",
            "examples": [
              "323e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Tag lifecycle status indicating active or deleted state. Valid values: 'active', 'deleted'. \n\n'active': Tag is visible in queries and included in task tag lists. Default state for newly created tags. \n\n'deleted': Tag soft-deleted; excluded from list queries. Preserves audit trail (who deleted, when) without hard deletion. \n\nSoft-delete rationale: Audit compliance requires deletion history. \n\nNote: Only 'active' tags returned by GET /task-tags endpoint.",
            "examples": [
              "active",
              "deleted"
            ],
            "title": "Status"
          },
          "tag": {
            "description": "Tag value identifying the categorization or state. Free-form string for flexible workflow customization. Case-sensitive; same tag with different case creates separate records. Combined with tag_type for organized categorization. \n\nCommon patterns:\n- Workflow: 'reviewed', 'approved', 'rejected', 'pending'\n- Quality: 'quality_checked', 'flagged', 'verified'\n- Priority: 'high', 'medium', 'low'\n- Custom: Domain-specific values",
            "examples": [
              "reviewed",
              "approved",
              "priority_high",
              "requires_attention"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Tag",
            "type": "string"
          },
          "tag_metadata": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Optional structured metadata providing tag context. Can be object, array, or primitive. NULL if no additional context needed. \n\nCommon uses:\n- Reviewer info: Who tagged and when\n- Approval details: Approver and notes\n- Quality metrics: Confidence scores, reasons\n- Custom data: Domain-specific context\n\nNote: Part of composite unique key with flow_execution_id, task_name, tag, and tag_type. Different metadata creates separate tags.",
            "examples": [
              {
                "notes": "Looks good",
                "reviewer": "user@example.com"
              },
              {
                "confidence": 0.95,
                "model": "gpt-4"
              },
              null
            ],
            "title": "Tag Metadata"
          },
          "tag_type": {
            "description": "Category or classification for the tag value. Groups related tags for filtering and organization in UI/queries. Case-sensitive; use consistent values across organization. \n\nCommon types:\n- 'review_status': Workflow states\n- 'quality': Quality assurance flags\n- 'priority': Business priority levels\n- 'approval': Approval workflow states\n- 'custom': Domain-specific categories",
            "examples": [
              "review_status",
              "quality",
              "priority",
              "approval",
              "custom"
            ],
            "maxLength": 100,
            "minLength": 1,
            "title": "Tag Type",
            "type": "string"
          },
          "task_name": {
            "description": "Name of the tagged task as defined in flow definition YAML. Case-sensitive identifier matching flow configuration. Tags are attached to task_name within a flow_execution_id. Multiple tags can be attached to the same task.",
            "examples": [
              "send_email",
              "extract_data",
              "validate_document"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Task Name",
            "type": "string"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of last update to this tag (UTC). Changes when tag is modified or soft-deleted. For deleted tags, records deletion timestamp. NULL for tags never updated since creation. Used for change tracking and audit history.",
            "examples": [
              "2025-01-24T10:35:00Z"
            ],
            "title": "Updated At"
          }
        },
        "required": [
          "id",
          "flow_execution_id",
          "task_name",
          "tag",
          "tag_type",
          "organization_id"
        ],
        "title": "FlowTaskTagAPI",
        "type": "object"
      },
      "FlowViewCreateRequest": {
        "properties": {
          "flow_id": {
            "format": "uuid",
            "title": "Flow Id",
            "type": "string"
          },
          "flow_version": {
            "title": "Flow Version",
            "type": "integer"
          },
          "view_data": {
            "$ref": "#/components/schemas/FlowViewData"
          },
          "view_name": {
            "title": "View Name",
            "type": "string"
          }
        },
        "required": [
          "flow_id",
          "flow_version",
          "view_name",
          "view_data"
        ],
        "title": "FlowViewCreateRequest",
        "type": "object"
      },
      "FlowViewData": {
        "properties": {
          "hidden_tasks": {
            "items": {
              "type": "string"
            },
            "title": "Hidden Tasks",
            "type": "array"
          },
          "is_default": {
            "default": false,
            "title": "Is Default",
            "type": "boolean"
          },
          "ordered_tasks": {
            "items": {
              "type": "string"
            },
            "title": "Ordered Tasks",
            "type": "array"
          }
        },
        "required": [
          "ordered_tasks",
          "hidden_tasks"
        ],
        "title": "FlowViewData",
        "type": "object"
      },
      "FlowViewListResponse": {
        "properties": {
          "flow_views": {
            "items": {
              "$ref": "#/components/schemas/FlowViewResponse"
            },
            "title": "Flow Views",
            "type": "array"
          },
          "limit": {
            "title": "Limit",
            "type": "integer"
          },
          "page": {
            "title": "Page",
            "type": "integer"
          },
          "total": {
            "title": "Total",
            "type": "integer"
          }
        },
        "required": [
          "flow_views",
          "total",
          "page",
          "limit"
        ],
        "title": "FlowViewListResponse",
        "type": "object"
      },
      "FlowViewResponse": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "flow_id": {
            "format": "uuid",
            "title": "Flow Id",
            "type": "string"
          },
          "flow_version": {
            "title": "Flow Version",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "view_data": {
            "$ref": "#/components/schemas/FlowViewData"
          },
          "view_name": {
            "title": "View Name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "flow_id",
          "flow_version",
          "view_name",
          "view_data"
        ],
        "title": "FlowViewResponse",
        "type": "object"
      },
      "FlowViewUpdateRequest": {
        "properties": {
          "view_data": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FlowViewData"
              },
              {
                "type": "null"
              }
            ]
          },
          "view_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "View Name"
          }
        },
        "title": "FlowViewUpdateRequest",
        "type": "object"
      },
      "GeneratePresignedUrlForDownload": {
        "description": "Model for generating a pre-signed URL for downloading a file.",
        "properties": {
          "file_key": {
            "title": "File Key",
            "type": "string"
          }
        },
        "required": [
          "file_key"
        ],
        "title": "GeneratePresignedUrlForDownload",
        "type": "object"
      },
      "GetUiSchemaRequest": {
        "properties": {
          "parameters": {
            "additionalProperties": true,
            "title": "Parameters",
            "type": "object"
          }
        },
        "required": [
          "parameters"
        ],
        "title": "GetUiSchemaRequest",
        "type": "object"
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "title": "Detail",
            "type": "array"
          }
        },
        "title": "HTTPValidationError",
        "type": "object"
      },
      "HealthCheckDetail": {
        "description": "Details of an individual health check.",
        "properties": {
          "details": {
            "description": "Additional details about the check",
            "examples": [
              "Connected successfully"
            ],
            "title": "Details",
            "type": "string"
          },
          "duration_ms": {
            "description": "Time taken to perform this check in milliseconds",
            "examples": [
              45.23
            ],
            "minimum": 0.0,
            "title": "Duration Ms",
            "type": "number"
          },
          "healthy": {
            "description": "Whether this check passed",
            "examples": [
              true
            ],
            "title": "Healthy",
            "type": "boolean"
          },
          "name": {
            "description": "Name of the health check",
            "examples": [
              "database_connectivity"
            ],
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "name",
          "healthy",
          "details",
          "duration_ms"
        ],
        "title": "HealthCheckDetail",
        "type": "object"
      },
      "HealthLinks": {
        "description": "Links to health check endpoints.",
        "properties": {
          "detailed": {
            "description": "Detailed health status including dependencies",
            "examples": [
              "/health/detailed"
            ],
            "title": "Detailed",
            "type": "string"
          },
          "liveness": {
            "description": "Liveness probe - checks if service is alive",
            "examples": [
              "/health/liveness"
            ],
            "title": "Liveness",
            "type": "string"
          },
          "readiness": {
            "description": "Readiness probe - checks if service is ready to accept traffic",
            "examples": [
              "/health/readiness"
            ],
            "title": "Readiness",
            "type": "string"
          }
        },
        "required": [
          "liveness",
          "readiness",
          "detailed"
        ],
        "title": "HealthLinks",
        "type": "object"
      },
      "HumanReviewTaskAssignmentResponse": {
        "description": "Response model for human review task assignment operations.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "human_review_task_id": {
            "description": "UUID of the human review task this assignment belongs to.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Human Review Task Id",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "UUID of the organization this assignment belongs to.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "started_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Timestamp when the user started working on this task. Null for pending assignments.",
            "example": "2024-01-01T00:00:00Z",
            "title": "Started At"
          },
          "status": {
            "description": "Status of the assignment. Valid values: 'pending', 'in_progress', 'completed', 'cancelled'.",
            "example": "pending",
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "user": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/app__api__user__user_api_model__UserResponse"
              },
              {
                "type": "null"
              }
            ],
            "description": "Full user information. Only populated when include_user_info query parameter is set to true."
          },
          "user_id": {
            "description": "UUID of the user assigned to this task.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "User Id",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "human_review_task_id",
          "user_id",
          "organization_id",
          "status"
        ],
        "title": "HumanReviewTaskAssignmentResponse",
        "type": "object"
      },
      "HumanReviewTaskCompleteRequest": {
        "description": "Request payload for completing a human review task.",
        "properties": {
          "review_result": {
            "description": "Review result: True for correct, False for incorrect.",
            "example": true,
            "title": "Review Result",
            "type": "boolean"
          },
          "reviewed_output": {
            "additionalProperties": true,
            "description": "JSON output of the completed review.",
            "example": {
              "comments": "All dates are correct.",
              "verified": true
            },
            "title": "Reviewed Output",
            "type": "object"
          }
        },
        "required": [
          "review_result",
          "reviewed_output"
        ],
        "title": "HumanReviewTaskCompleteRequest",
        "type": "object"
      },
      "HumanReviewTaskCreateRequest": {
        "description": "Request payload for creating a new human review task.",
        "properties": {
          "assigned_users": {
            "description": "List of user UUIDs to assign to this task.",
            "example": [
              "550e8400-e29b-41d4-a716-446655440000",
              "660e8400-e29b-41d4-a716-446655440001"
            ],
            "items": {
              "format": "uuid",
              "type": "string"
            },
            "title": "Assigned Users",
            "type": "array"
          },
          "flow_execution_id": {
            "description": "UUID of the flow execution this task is associated with.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "instructions": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Instructions for the human reviewer on how to complete this task.",
            "example": "Please review the document and verify all dates are correct.",
            "title": "Instructions"
          },
          "source_task_execution_idx": {
            "description": "Index of the source task execution.",
            "example": 0,
            "title": "Source Task Execution Idx",
            "type": "integer"
          },
          "source_task_name": {
            "description": "Name of the source task that created this review.",
            "example": "process_document",
            "title": "Source Task Name",
            "type": "string"
          },
          "target_task_execution_idx": {
            "description": "Index of the target task execution.",
            "example": 0,
            "title": "Target Task Execution Idx",
            "type": "integer"
          },
          "target_task_name": {
            "description": "Name of the target task being reviewed.",
            "example": "receive_file",
            "title": "Target Task Name",
            "type": "string"
          }
        },
        "required": [
          "flow_execution_id",
          "target_task_name",
          "target_task_execution_idx",
          "source_task_name",
          "source_task_execution_idx",
          "assigned_users"
        ],
        "title": "HumanReviewTaskCreateRequest",
        "type": "object"
      },
      "HumanReviewTaskResponse": {
        "description": "Response model for human review task operations.",
        "properties": {
          "completed_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Timestamp when the task was completed. Null for not completed tasks.",
            "example": "2024-01-01T00:00:00Z",
            "title": "Completed At"
          },
          "completed_by": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "UUID of the user who completed this task. Null for not completed tasks.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "title": "Completed By"
          },
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "flow_execution_id": {
            "description": "UUID of the flow execution this task is associated with.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "instructions": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Instructions for the human reviewer on how to complete this task.",
            "example": "Please review the document and verify all dates are correct.",
            "title": "Instructions"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "UUID of the organization this task belongs to.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "review_result": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Review result: True for correct, False for incorrect, null for not yet finished.",
            "example": true,
            "title": "Review Result"
          },
          "reviewed_output": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "JSON output of the completed review. Null for not yet completed tasks.",
            "example": {
              "comments": "All dates are correct.",
              "verified": true
            },
            "title": "Reviewed Output"
          },
          "source_task_execution_idx": {
            "description": "Index of the source task execution that created this review.",
            "example": 0,
            "title": "Source Task Execution Idx",
            "type": "integer"
          },
          "source_task_name": {
            "description": "Name of the source task that created this review.",
            "example": "process_document",
            "title": "Source Task Name",
            "type": "string"
          },
          "status": {
            "description": "Status of the task. Valid values: 'pending', 'in_progress', 'completed'.",
            "example": "pending",
            "title": "Status",
            "type": "string"
          },
          "target_task_execution_idx": {
            "description": "Index of the target task execution.",
            "example": 0,
            "title": "Target Task Execution Idx",
            "type": "integer"
          },
          "target_task_name": {
            "description": "Name of the target task being reviewed.",
            "example": "receive_file",
            "title": "Target Task Name",
            "type": "string"
          },
          "task_metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Additional metadata associated with the human review task.",
            "example": {
              "priority": "high",
              "source": "api"
            },
            "title": "Task Metadata"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "organization_id",
          "flow_execution_id",
          "target_task_name",
          "target_task_execution_idx",
          "source_task_name",
          "source_task_execution_idx",
          "status"
        ],
        "title": "HumanReviewTaskResponse",
        "type": "object"
      },
      "InitiateErrorResolveAction": {
        "description": "Action to notify about missing task parameters.",
        "properties": {
          "action": {
            "const": "initiate_error_resolve",
            "default": "initiate_error_resolve",
            "title": "Action",
            "type": "string"
          },
          "message_type": {
            "const": "action",
            "default": "action",
            "title": "Message Type",
            "type": "string"
          }
        },
        "title": "InitiateErrorResolveAction",
        "type": "object"
      },
      "IntegrationCatalogResponse": {
        "description": "Response model for integration catalog",
        "properties": {
          "category": {
            "$ref": "#/components/schemas/IntegrationCategory"
          },
          "credential_providers": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/CredentialProvider"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Credential Providers"
          },
          "credential_types": {
            "items": {
              "$ref": "#/components/schemas/CredentialTypeEnum"
            },
            "title": "Credential Types",
            "type": "array"
          },
          "description": {
            "title": "Description",
            "type": "string"
          },
          "display_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Display Name"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "is_plugin": {
            "default": false,
            "title": "Is Plugin",
            "type": "boolean"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "provider": {
            "$ref": "#/components/schemas/ProviderApiEnum"
          }
        },
        "required": [
          "id",
          "category",
          "provider",
          "name",
          "description",
          "credential_types"
        ],
        "title": "IntegrationCatalogResponse",
        "type": "object"
      },
      "IntegrationCategory": {
        "description": "Integration category",
        "enum": [
          "automation",
          "human_in_the_loop",
          "database",
          "messaging",
          "agent_in_the_loop",
          "storage"
        ],
        "title": "IntegrationCategory",
        "type": "string"
      },
      "IntegrationCreateRequest": {
        "properties": {
          "credential_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Credential Id"
          },
          "description": {
            "title": "Description",
            "type": "string"
          },
          "flow_id": {
            "format": "uuid",
            "title": "Flow Id",
            "type": "string"
          },
          "task_name": {
            "title": "Task Name",
            "type": "string"
          }
        },
        "required": [
          "flow_id",
          "credential_id",
          "description",
          "task_name"
        ],
        "title": "IntegrationCreateRequest",
        "type": "object"
      },
      "ListTaskExecutionsResponse": {
        "description": "Response model for listing task executions with filtering.\n\nReturns an array of task executions with their associated tags,\nfiltered by the query parameters provided in the request.",
        "properties": {
          "task_executions": {
            "description": "Array of task execution objects matching the filter criteria. Each object includes full task execution details plus associated tags. Empty array if no executions match filters. Results are ordered by created_at descending (newest first).",
            "items": {
              "$ref": "#/components/schemas/TaskExecutionWithTagsAPI"
            },
            "title": "Task Executions",
            "type": "array"
          }
        },
        "required": [
          "task_executions"
        ],
        "title": "ListTaskExecutionsResponse",
        "type": "object"
      },
      "LivenessResponse": {
        "description": "Response from liveness probe endpoint.\n\nIndicates whether the application process is alive and responding.\nUsed by Kubernetes to determine if the pod needs to be restarted.",
        "examples": [
          {
            "message": "Application is running",
            "status": "alive",
            "timestamp": 1705324800
          },
          {
            "error": "Internal process failure",
            "message": "Application encountered an error",
            "status": "unhealthy",
            "timestamp": 1705324800
          }
        ],
        "properties": {
          "error": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Error details if status is unhealthy",
            "examples": [
              "Connection timeout"
            ],
            "title": "Error"
          },
          "message": {
            "description": "Human-readable status message",
            "examples": [
              "Application is running",
              "Application encountered an error"
            ],
            "title": "Message",
            "type": "string"
          },
          "status": {
            "description": "Application liveness status. 'alive' means responsive, 'unhealthy' means degraded.",
            "examples": [
              "alive",
              "unhealthy"
            ],
            "title": "Status",
            "type": "string"
          },
          "timestamp": {
            "description": "Unix timestamp when check was performed",
            "examples": [
              1705324800
            ],
            "title": "Timestamp",
            "type": "integer"
          }
        },
        "required": [
          "status",
          "timestamp",
          "message"
        ],
        "title": "LivenessResponse",
        "type": "object"
      },
      "MessageBody": {
        "description": "Body for standard text messages.",
        "properties": {
          "content": {
            "title": "Content",
            "type": "string"
          },
          "type": {
            "const": "message",
            "default": "message",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "content"
        ],
        "title": "MessageBody",
        "type": "object"
      },
      "MessageSender": {
        "description": "Enumeration for message sender roles.",
        "enum": [
          "user",
          "assistant",
          "Workflow Assistant",
          "Workflow Planner",
          "Error Resolver",
          "Supervisor"
        ],
        "title": "MessageSender",
        "type": "string"
      },
      "MetadataResponse": {
        "properties": {
          "metadata": {
            "title": "Metadata",
            "type": "string"
          }
        },
        "required": [
          "metadata"
        ],
        "title": "MetadataResponse",
        "type": "object"
      },
      "MissingTaskParamsData": {
        "description": "Data for missing task parameters actions.",
        "properties": {
          "tasks": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "title": "Tasks",
            "type": "array"
          }
        },
        "required": [
          "tasks"
        ],
        "title": "MissingTaskParamsData",
        "type": "object"
      },
      "ModelInfo": {
        "description": "Model information from LiteLLM.",
        "properties": {
          "endpoint_count": {
            "description": "Number of endpoints available for this model",
            "title": "Endpoint Count",
            "type": "integer"
          },
          "locations": {
            "description": "Specific locations where the model is available",
            "items": {
              "type": "string"
            },
            "title": "Locations",
            "type": "array"
          },
          "model_name": {
            "description": "Name of the model",
            "title": "Model Name",
            "type": "string"
          },
          "providers": {
            "description": "Model providers (e.g., 'openai', 'vertex_ai', 'fireworks')",
            "items": {
              "type": "string"
            },
            "title": "Providers",
            "type": "array"
          },
          "regions": {
            "description": "Regions where the model is deployed",
            "items": {
              "$ref": "#/components/schemas/Region"
            },
            "title": "Regions",
            "type": "array"
          }
        },
        "required": [
          "model_name",
          "regions",
          "locations",
          "providers",
          "endpoint_count"
        ],
        "title": "ModelInfo",
        "type": "object"
      },
      "ModelsResponse": {
        "description": "Response containing list of models.",
        "properties": {
          "count": {
            "description": "Total number of models",
            "title": "Count",
            "type": "integer"
          },
          "models": {
            "description": "List of available models",
            "items": {
              "$ref": "#/components/schemas/ModelInfo"
            },
            "title": "Models",
            "type": "array"
          }
        },
        "required": [
          "models",
          "count"
        ],
        "title": "ModelsResponse",
        "type": "object"
      },
      "OrganizationResponse": {
        "description": "API response model for Organization entity.\n\nRepresents a tenant organization with its own isolated set of users,\nflows, and executions. Organizations provide multi-tenancy and access\ncontrol boundaries.",
        "properties": {
          "created_at": {
            "description": "Timestamp when organization was created. Format: ISO 8601 UTC (e.g., '2025-01-23T15:30:00Z').",
            "examples": [
              "2025-01-23T15:30:00Z"
            ],
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for the organization. Format: UUID v4",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "is_active": {
            "default": true,
            "description": "Whether the organization is active. Active organizations allow user logins and flow executions. Inactive organizations are read-only; users cannot log in. Set via PUT /admin/organizations/{id} or PATCH /deactivate endpoint.",
            "title": "Is Active",
            "type": "boolean"
          },
          "modified_at": {
            "description": "Timestamp when organization was last modified. Updated automatically on any field change. Format: ISO 8601 UTC (e.g., '2025-01-24T10:45:00Z'). Used for change tracking and audit logs.",
            "examples": [
              "2025-01-24T10:45:00Z"
            ],
            "format": "date-time",
            "title": "Modified At",
            "type": "string"
          },
          "name": {
            "description": "Organization display name. Unique across the platform. Used in UI, reports, and organization selection. Can be updated via PUT /admin/organizations/{id}",
            "examples": [
              "Acme Corporation",
              "Engineering Team"
            ],
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "created_at",
          "modified_at"
        ],
        "title": "OrganizationResponse",
        "type": "object"
      },
      "PatchFlowRequest": {
        "description": "Request body for partially updating a flow.\n\nAll fields are optional - only provided fields will be updated.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New description",
            "title": "Description"
          },
          "display_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New display name for the flow",
            "title": "Display Name"
          },
          "settings": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FlowSettings"
              },
              {
                "type": "null"
              }
            ],
            "description": "New settings (replaces existing)."
          },
          "status": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New status. Valid values: 'draft' or 'published'. Currently all transitions are allowed.",
            "title": "Status"
          },
          "visibility": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "New visibility setting",
            "title": "Visibility"
          }
        },
        "title": "PatchFlowRequest",
        "type": "object"
      },
      "PatchFlowTaskTagsRequest": {
        "description": "Batch request to add or remove multiple task execution tags.\n\nSupports mixed operations (add and remove) in a single atomic transaction.\nAll operations succeed together or all fail. Efficient for bulk tagging.",
        "properties": {
          "tags": {
            "description": "Array of tag operations to perform in a single atomic transaction. Each item specifies an 'add' or 'remove' operation for a specific task. Operations processed sequentially; all succeed or all fail together. \n\nBatch benefits:\n- Single database transaction for consistency\n- Reduced network overhead (one request vs many)\n- Atomic operations (no partial failures)\n\nMixed operations supported:\n- Add tags to multiple tasks\n- Remove tags from multiple tasks\n- Add and remove different tags in same request\n\nPractical limit: 1-100 operations per request for performance. For bulk tagging beyond 100 operations, split into multiple requests.",
            "examples": [
              [
                {
                  "flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
                  "operation": "add",
                  "tag": "reviewed",
                  "tag_metadata": {
                    "reviewer": "user@example.com"
                  },
                  "tag_type": "review_status",
                  "task_name": "extract_data"
                },
                {
                  "flow_execution_id": "123e4567-e89b-12d3-a456-426614174000",
                  "operation": "remove",
                  "tag": "pending_review",
                  "tag_type": "review_status",
                  "task_name": "extract_data"
                }
              ]
            ],
            "items": {
              "$ref": "#/components/schemas/PatchFlowTaskTagsRequestItem"
            },
            "maxItems": 100,
            "minItems": 1,
            "title": "Tags",
            "type": "array"
          }
        },
        "required": [
          "tags"
        ],
        "title": "PatchFlowTaskTagsRequest",
        "type": "object"
      },
      "PatchFlowTaskTagsRequestItem": {
        "description": "Single tag operation in a batch request.\n\nRepresents one add or remove operation for a task execution tag.\nBatch multiple operations in a single PATCH request for efficiency.",
        "properties": {
          "flow_execution_id": {
            "description": "Unique identifier of the flow execution containing the target task. Used to locate task execution and determine organization scope. Must exist and belong to user's organization or request fails with 404. All tags are scoped to a specific flow execution.",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "operation": {
            "description": "Tag operation to perform on the specified task execution. \n\n'add': Create new tag (idempotent - no error if already exists). Server generates UUID, timestamps, and organization_id automatically. Returns status='added' on success or status='already_exists' if duplicate. \n\n'remove': Soft-delete existing tag by setting status='deleted'. Preserves tag record with deletion metadata (updated_at, modified_by). Returns status='removed' on success or status='not_found' if missing. \n\nNote: Tags are never hard-deleted for audit trail compliance.",
            "enum": [
              "add",
              "remove"
            ],
            "examples": [
              "add",
              "remove"
            ],
            "title": "Operation",
            "type": "string"
          },
          "tag": {
            "description": "Tag value to add or remove from the task execution. Free-form string identifier for categorization or workflow state. Case-sensitive; 'reviewed' and 'Reviewed' are different tags. Combine with tag_type and tag_metadata for rich categorization. \n\nCommon patterns:\n- Simple: 'reviewed', 'approved', 'rejected'\n- Namespaced: 'priority:high', 'customer:acme'\n- Descriptive: 'requires_human_review', 'quality_flagged'\n\nTag uniqueness: (flow_execution_id, task_name, tag, tag_type, tag_metadata) forms composite unique key. Same tag with different metadata creates separate records.",
            "examples": [
              "reviewed",
              "approved",
              "priority_high",
              "requires_attention"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Tag",
            "type": "string"
          },
          "tag_metadata": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Optional structured metadata providing context for the tag. Can be object, array, or primitive types. NULL if no additional context needed. \n\nCommon patterns:\n- Reviewer info: {'reviewer': 'user@example.com', 'reviewed_at': '2025-01-23T10:30:00Z'}\n- Approval details: {'approver': 'manager@example.com', 'notes': 'Approved with conditions'}\n- Quality metrics: {'confidence_score': 0.95, 'flagged_reason': 'Low confidence'}\n- Custom data: Any JSON-serializable structure relevant to your workflow\n\nNote: tag_metadata is part of the composite unique key. Same tag with different metadata creates multiple tag records.",
            "examples": [
              {
                "notes": "Looks good",
                "reviewer": "user@example.com"
              },
              {
                "approved_at": "2025-01-23T10:30:00Z",
                "approver": "manager@example.com"
              },
              {
                "confidence": 0.95,
                "model": "gpt-4"
              },
              null
            ],
            "title": "Tag Metadata"
          },
          "tag_type": {
            "description": "Category or namespace for the tag value. Groups related tags for filtering and organization. Case-sensitive; used for tag classification in UI and queries. \n\nCommon types:\n- 'review_status': Workflow states ('reviewed', 'approved', 'rejected')\n- 'quality': QA flags ('quality_checked', 'flagged', 'verified')\n- 'priority': Business priority ('high', 'medium', 'low')\n- 'approval': Approval workflow ('pending', 'approved', 'denied')\n- 'custom': Domain-specific categories\n\nBest practice: Use consistent tag_type values across your organization to enable filtering and reporting.",
            "examples": [
              "review_status",
              "quality",
              "priority",
              "approval",
              "custom"
            ],
            "maxLength": 100,
            "minLength": 1,
            "title": "Tag Type",
            "type": "string"
          },
          "task_name": {
            "description": "Name of the task to tag, as defined in flow definition YAML. Case-sensitive identifier matching task name in flow configuration. Task must exist within the specified flow_execution_id. Tags are attached to (flow_execution_id, task_name) pair. \n\nExamples: 'send_email', 'extract_data', 'validate_document'",
            "examples": [
              "send_email",
              "extract_data",
              "validate_document"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Task Name",
            "type": "string"
          }
        },
        "required": [
          "operation",
          "flow_execution_id",
          "task_name",
          "tag",
          "tag_type"
        ],
        "title": "PatchFlowTaskTagsRequestItem",
        "type": "object"
      },
      "PatchFlowTaskTagsResponse": {
        "description": "Response from batch tag operations.\n\nReturns status for each operation in request array order.\nArray length matches request array length (1:1 correspondence).",
        "properties": {
          "tags": {
            "description": "Array of operation results in request array order. Each element corresponds to the tag operation at the same index in the request. \n\nResponse structure:\n- Length: Always equals request.tags length\n- Order: Preserves request order (response[i] is result of request.tags[i])\n- Content: Each item contains 'status' field indicating operation outcome\n\nExample mapping:\nRequest: [add_tag1, remove_tag2, add_tag3]\nResponse: [status1, status2, status3]\n\nAll operations complete (no partial failures). Check each status to determine individual operation outcomes. Use array index to match operations with results.",
            "examples": [
              [
                {
                  "status": "added"
                },
                {
                  "status": "removed"
                },
                {
                  "status": "already_exists"
                }
              ]
            ],
            "items": {
              "$ref": "#/components/schemas/PatchFlowTaskTagsResponseItem"
            },
            "title": "Tags",
            "type": "array"
          }
        },
        "required": [
          "tags"
        ],
        "title": "PatchFlowTaskTagsResponse",
        "type": "object"
      },
      "PatchFlowTaskTagsResponseItem": {
        "description": "Result of a single tag operation in a batch request.\n\nIndicates success or idempotent outcome for each operation.\nResponse array matches request array order (1:1 correspondence).",
        "properties": {
          "status": {
            "description": "Outcome of the tag operation. Idempotent operations return success status even if no change occurred. \n\nStatus values:\n- 'added': Tag successfully created (operation='add'). New tag record inserted with status='active'. \n- 'removed': Tag successfully soft-deleted (operation='remove'). Tag record updated with status='deleted' and deletion metadata. \n- 'already_exists': Add operation found existing identical tag (operation='add'). No change made; existing tag remains active. Idempotent success. \n- 'not_found': Remove operation found no matching tag (operation='remove'). No change made; tag already absent or deleted. Idempotent success. \n\nNote: All statuses indicate successful processing. No 'error' status exists; errors raise HTTP 4xx/5xx responses instead. \n\nIdempotency guarantee: Same request produces same result when repeated. Safe to retry on network failures without duplicate tags or errors.",
            "enum": [
              "added",
              "removed",
              "already_exists",
              "not_found"
            ],
            "examples": [
              "added",
              "removed",
              "already_exists",
              "not_found"
            ],
            "title": "Status",
            "type": "string"
          }
        },
        "required": [
          "status"
        ],
        "title": "PatchFlowTaskTagsResponseItem",
        "type": "object"
      },
      "PostgresCreateRequest": {
        "description": "PostgreSQL integration creation request model.",
        "properties": {
          "connection_string": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Connection String"
          },
          "database": {
            "title": "Database",
            "type": "string"
          },
          "host": {
            "title": "Host",
            "type": "string"
          },
          "password": {
            "title": "Password",
            "type": "string"
          },
          "port": {
            "title": "Port",
            "type": "string"
          },
          "username": {
            "title": "Username",
            "type": "string"
          }
        },
        "required": [
          "host",
          "port",
          "username",
          "password",
          "database"
        ],
        "title": "PostgresCreateRequest",
        "type": "object"
      },
      "ProductResponse": {
        "description": "API response model for Product entity.\n\nRepresents a billable product or service consumed during flow execution,\nsuch as AI model tokens, compute resources, or external API calls.\nUsed for usage tracking and cost estimation.",
        "properties": {
          "created_at": {
            "description": "Timestamp when the product was created. ISO 8601 format with timezone.",
            "examples": [
              "2024-01-15T10:30:00Z"
            ],
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional detailed description of the product. Explains what the product represents and how it's consumed. Useful for billing reports and usage dashboards.",
            "examples": [
              "Input and output tokens consumed by GPT-4 model inference"
            ],
            "title": "Description"
          },
          "estimated_cost_per_unit": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Estimated cost per unit of consumption in USD. Used to calculate total estimated cost for usage records. May be null if cost data is unavailable or not applicable. Example: 0.00003 for $0.03 per 1000 tokens",
            "examples": [
              3e-05,
              0.001,
              0.1
            ],
            "title": "Estimated Cost Per Unit"
          },
          "id": {
            "description": "Unique identifier for the product. Referenced in usage records to track consumption. Format: UUID v4",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "metadata": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional additional product metadata. Flexible field for provider-specific details, pricing tiers, model versions, or other contextual information. Structure varies by product type.",
            "examples": [
              {
                "model": "gpt-4-turbo",
                "tier": "standard"
              }
            ],
            "title": "Metadata"
          },
          "modified_at": {
            "description": "Timestamp when the product was last modified. ISO 8601 format with timezone. Updates automatically when product details change.",
            "examples": [
              "2024-01-20T14:45:00Z"
            ],
            "format": "date-time",
            "title": "Modified At",
            "type": "string"
          },
          "name": {
            "description": "Product display name. Human-readable identifier for the billable resource. Examples: 'GPT-4 Tokens', 'Claude Sonnet API Calls', 'Compute Minutes'",
            "examples": [
              "GPT-4 Tokens",
              "Claude Sonnet API Calls",
              "Compute Minutes"
            ],
            "title": "Name",
            "type": "string"
          },
          "provider": {
            "description": "Service provider or vendor supplying the product. Used to group costs by provider for billing analysis. Examples: 'OpenAI', 'Anthropic', 'AWS', 'GCP'",
            "examples": [
              "OpenAI",
              "Anthropic",
              "AWS",
              "Google Cloud"
            ],
            "title": "Provider",
            "type": "string"
          },
          "unit": {
            "description": "Unit of measurement for product consumption. Used to quantify usage amounts in usage records. Examples: 'tokens', 'requests', 'seconds', 'GB'",
            "examples": [
              "tokens",
              "requests",
              "seconds",
              "GB"
            ],
            "title": "Unit",
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "unit",
          "provider",
          "created_at",
          "modified_at"
        ],
        "title": "ProductResponse",
        "type": "object"
      },
      "ProviderApiEnum": {
        "enum": [
          "microsoft",
          "sftp",
          "aws_ses",
          "google",
          "postgresql",
          "internal_postgresql",
          "file_storage",
          "sharepoint_client_secret"
        ],
        "title": "ProviderApiEnum",
        "type": "string"
      },
      "ReadinessResponse": {
        "description": "Response from readiness probe endpoint.\n\nIndicates whether the service is ready to accept traffic.\nUsed by Kubernetes to control traffic routing to the pod.",
        "example": {
          "checks": [
            {
              "details": "Database connection successful",
              "duration_ms": 45.23,
              "healthy": true,
              "name": "database_connectivity"
            }
          ],
          "duration_ms": 125.45,
          "healthy": true,
          "message": "Service is ready to receive traffic",
          "status": "ready",
          "timestamp": 1705324800
        },
        "properties": {
          "checks": {
            "description": "Results of individual health checks performed",
            "items": {
              "$ref": "#/components/schemas/HealthCheckDetail"
            },
            "title": "Checks",
            "type": "array"
          },
          "duration_ms": {
            "description": "Total time taken for all health checks in milliseconds",
            "examples": [
              125.45
            ],
            "minimum": 0.0,
            "title": "Duration Ms",
            "type": "number"
          },
          "healthy": {
            "description": "Overall health status across all checks",
            "examples": [
              true
            ],
            "title": "Healthy",
            "type": "boolean"
          },
          "message": {
            "description": "Human-readable readiness message",
            "examples": [
              "Service is ready to receive traffic",
              "Service is not ready to receive traffic"
            ],
            "title": "Message",
            "type": "string"
          },
          "status": {
            "description": "Service readiness status. 'ready' means can accept traffic, 'not_ready' means should not receive traffic.",
            "examples": [
              "ready",
              "not_ready"
            ],
            "title": "Status",
            "type": "string"
          },
          "timestamp": {
            "description": "Unix timestamp when checks were performed",
            "examples": [
              1705324800
            ],
            "title": "Timestamp",
            "type": "integer"
          }
        },
        "required": [
          "status",
          "message",
          "healthy",
          "timestamp",
          "duration_ms"
        ],
        "title": "ReadinessResponse",
        "type": "object"
      },
      "ReasoningBody": {
        "description": "Body for reasoning messages.",
        "properties": {
          "content": {
            "title": "Content",
            "type": "string"
          },
          "type": {
            "const": "reasoning",
            "default": "reasoning",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "content"
        ],
        "title": "ReasoningBody",
        "type": "object"
      },
      "Region": {
        "description": "Available regions for model deployment.",
        "enum": [
          "eu",
          "global"
        ],
        "title": "Region",
        "type": "string"
      },
      "RejectWorkflowAction": {
        "description": "Action to reject the proposed workflow.",
        "properties": {
          "action": {
            "const": "reject_workflow",
            "default": "reject_workflow",
            "title": "Action",
            "type": "string"
          },
          "flow_definition": {
            "additionalProperties": true,
            "description": "The workflow definition to reject",
            "title": "Flow Definition",
            "type": "object"
          },
          "message_type": {
            "const": "action",
            "default": "action",
            "title": "Message Type",
            "type": "string"
          }
        },
        "required": [
          "flow_definition"
        ],
        "title": "RejectWorkflowAction",
        "type": "object"
      },
      "ResendInviteRequest": {
        "description": "Request model for resending user invitation.\n\nUsed to trigger a new invitation email when the original invitation\nhas expired, was not received, or the user needs another copy.",
        "properties": {
          "email": {
            "description": "Email address of the user to re-invite. Must match an existing user account in pending or active status. A new invitation email will be sent to this address with a fresh authentication link and setup instructions.",
            "examples": [
              "user@example.com",
              "john.doe@company.com"
            ],
            "format": "email",
            "title": "Email",
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "title": "ResendInviteRequest",
        "type": "object"
      },
      "ResendInviteResponse": {
        "description": "Response model for resend invite operation.\n\nConfirms that the invitation email was successfully queued or sent.\nActual email delivery depends on external email service.",
        "properties": {
          "email": {
            "description": "Email address that received the invitation. Echoes back the requested email for confirmation. Useful for logging and audit purposes.",
            "examples": [
              "user@example.com",
              "john.doe@company.com"
            ],
            "title": "Email",
            "type": "string"
          },
          "message": {
            "description": "Human-readable message describing the result. Provides confirmation or additional context about the operation. Example: 'Invitation has been resent successfully'",
            "examples": [
              "Invitation has been resent successfully",
              "Invitation email queued for delivery"
            ],
            "title": "Message",
            "type": "string"
          },
          "success": {
            "description": "Indicates whether the invitation was successfully processed. True if invitation was queued/sent, False if operation failed. Note: This indicates the API succeeded, not that email was delivered.",
            "examples": [
              true
            ],
            "title": "Success",
            "type": "boolean"
          }
        },
        "required": [
          "success",
          "message",
          "email"
        ],
        "title": "ResendInviteResponse",
        "type": "object"
      },
      "ResolveErrorsAction": {
        "description": "Action to notify about missing task parameters.",
        "properties": {
          "action": {
            "const": "resolve_errors",
            "default": "resolve_errors",
            "title": "Action",
            "type": "string"
          },
          "message_type": {
            "const": "action",
            "default": "action",
            "title": "Message Type",
            "type": "string"
          }
        },
        "title": "ResolveErrorsAction",
        "type": "object"
      },
      "ResolveUriRequest": {
        "description": "Request body for resolving a storage URI to a download URL.\n\nPass the gs:// URI exactly as received from task outputs\u2014no parsing required.",
        "examples": [
          {
            "uri": "gs://superai-file-upload-prod-eu/flows/255a17d0-5c21-47d9-8e0b-a08b48436f0a/documents/f8230da2-4136-4ffb-acfe-db9318970ea2"
          }
        ],
        "properties": {
          "uri": {
            "description": "The gs:// storage URI to resolve. Pass the exact URI from your task output.",
            "title": "Uri",
            "type": "string"
          }
        },
        "required": [
          "uri"
        ],
        "title": "ResolveUriRequest",
        "type": "object"
      },
      "ResolveUriResponse": {
        "description": "Response containing a temporary pre-signed download URL.\n\nThe download_url can be used directly to download the file without\nadditional authentication. URLs expire after 1 hour.",
        "examples": [
          {
            "download_url": "https://storage.googleapis.com/superai-file-upload-prod-eu/flows/255a17d0-5c21-47d9-8e0b-a08b48436f0a/documents/f8230da2-4136-4ffb-acfe-db9318970ea2?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=...&X-Goog-Date=...&X-Goog-Expires=3600&X-Goog-Signature=...",
            "expires_at": "2025-01-15T15:00:00+00:00",
            "expires_in_seconds": 3600
          }
        ],
        "properties": {
          "download_url": {
            "description": "Pre-signed URL for downloading the file. Use this URL directly\u2014no authentication headers required. Valid for 1 hour.",
            "title": "Download Url",
            "type": "string"
          },
          "expires_at": {
            "description": "ISO 8601 timestamp when the download URL expires. Request a new URL after this time.",
            "title": "Expires At",
            "type": "string"
          },
          "expires_in_seconds": {
            "description": "Seconds remaining until the download URL expires. Always 3600 (1 hour) for new URLs.",
            "title": "Expires In Seconds",
            "type": "integer"
          }
        },
        "required": [
          "download_url",
          "expires_at",
          "expires_in_seconds"
        ],
        "title": "ResolveUriResponse",
        "type": "object"
      },
      "RootResponse": {
        "description": "Response model for the root endpoint.\n\nProvides comprehensive information about the API including version,\nstatus, and links to documentation and health check endpoints.",
        "properties": {
          "api": {
            "$ref": "#/components/schemas/ApiInfo",
            "description": "API configuration information"
          },
          "description": {
            "description": "Comprehensive description of the API and its capabilities",
            "title": "Description",
            "type": "string"
          },
          "documentation": {
            "$ref": "#/components/schemas/DocumentationLinks",
            "description": "Links to various documentation resources"
          },
          "health": {
            "$ref": "#/components/schemas/HealthLinks",
            "description": "Links to health check endpoints"
          },
          "message": {
            "description": "Welcome message with quick start guidance",
            "examples": [
              "Welcome to SuperAI Flow Platform API. Visit /api/docs for interactive documentation."
            ],
            "title": "Message",
            "type": "string"
          },
          "name": {
            "description": "Name of the API service",
            "examples": [
              "SuperAI Flow Platform"
            ],
            "title": "Name",
            "type": "string"
          },
          "status": {
            "description": "Operational status of the API",
            "examples": [
              "operational"
            ],
            "title": "Status",
            "type": "string"
          },
          "version": {
            "description": "Current API version",
            "examples": [
              "0.1.0"
            ],
            "title": "Version",
            "type": "string"
          }
        },
        "required": [
          "name",
          "version",
          "description",
          "status",
          "documentation",
          "health",
          "api",
          "message"
        ],
        "title": "RootResponse",
        "type": "object"
      },
      "RunWorkflowRequestData": {
        "description": "Data for run workflow request actions.",
        "properties": {
          "flow_id": {
            "title": "Flow Id",
            "type": "string"
          }
        },
        "required": [
          "flow_id"
        ],
        "title": "RunWorkflowRequestData",
        "type": "object"
      },
      "SSOOrganizationResponse": {
        "description": "API response model for SSO organization configuration.",
        "properties": {
          "attribute_mapping": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "SAML attribute mappings",
            "title": "Attribute Mapping"
          },
          "created_at": {
            "description": "Creation timestamp",
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "domains": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Email domains for this SSO provider",
            "title": "Domains"
          },
          "is_active": {
            "default": true,
            "description": "Whether the SSO provider is active",
            "title": "Is Active",
            "type": "boolean"
          },
          "metadata_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "SAML metadata URL",
            "title": "Metadata Url"
          },
          "metadata_xml_hash": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Hash of SAML metadata XML",
            "title": "Metadata Xml Hash"
          },
          "organization_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Associated organization ID",
            "title": "Organization Id"
          },
          "sso_provider_id": {
            "description": "Supabase SSO provider ID",
            "title": "Sso Provider Id",
            "type": "string"
          },
          "updated_at": {
            "description": "Last update timestamp",
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "sso_provider_id",
          "created_at",
          "updated_at"
        ],
        "title": "SSOOrganizationResponse",
        "type": "object"
      },
      "SSOProviderCreate": {
        "description": "Request model for creating an SSO provider via Supabase Management API.",
        "properties": {
          "attribute_mapping": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "SAML attribute mappings",
            "title": "Attribute Mapping"
          },
          "domains": {
            "description": "Email domains for this provider",
            "items": {
              "type": "string"
            },
            "title": "Domains",
            "type": "array"
          },
          "metadata_url": {
            "anyOf": [
              {
                "format": "uri",
                "maxLength": 2083,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "URL to fetch SAML metadata",
            "title": "Metadata Url"
          },
          "metadata_xml": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Raw SAML metadata XML",
            "title": "Metadata Xml"
          },
          "type": {
            "default": "saml",
            "description": "SSO provider type",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "domains"
        ],
        "title": "SSOProviderCreate",
        "type": "object"
      },
      "SSOProviderUpdate": {
        "description": "Request model for updating an SSO provider via Supabase Management API.",
        "properties": {
          "attribute_mapping": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "Updated attribute mappings",
            "title": "Attribute Mapping"
          },
          "domains": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Updated email domains",
            "title": "Domains"
          },
          "is_active": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "Whether provider is active",
            "title": "Is Active"
          },
          "metadata_url": {
            "anyOf": [
              {
                "format": "uri",
                "maxLength": 2083,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Updated SAML metadata URL",
            "title": "Metadata Url"
          },
          "metadata_xml": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Updated SAML metadata XML",
            "title": "Metadata Xml"
          }
        },
        "title": "SSOProviderUpdate",
        "type": "object"
      },
      "ServiceAccountCreateRequest": {
        "description": "Public API request payload for creating a new service account.\n\nNote: API can only create organization-scoped service accounts.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional description explaining the purpose and usage of this account.",
            "example": "Service account for API documentation generation",
            "title": "Description"
          },
          "name": {
            "description": "Human-readable name for this service account.",
            "example": "API Documentation",
            "maxLength": 255,
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "title": "ServiceAccountCreateRequest",
        "type": "object"
      },
      "ServiceAccountCreateResponse": {
        "description": "Response model for service account creation including the full token.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Description"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "organization_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Organization Id"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "name",
          "status"
        ],
        "title": "ServiceAccountCreateResponse",
        "type": "object"
      },
      "ServiceAccountResponse": {
        "description": "Response model for service account operations.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional description explaining the purpose and usage of this account.",
            "example": "Service account for API documentation generation",
            "title": "Description"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "name": {
            "description": "Human-readable name for this service account. Examples: 'API Documentation', 'Temporal Worker'.",
            "example": "API Documentation",
            "maxLength": 255,
            "title": "Name",
            "type": "string"
          },
          "organization_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "UUID of the organization this account belongs to. NULL for system accounts.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "title": "Organization Id"
          },
          "status": {
            "description": "Current status of the service account. Valid values: 'active', 'inactive'. Only active accounts can authenticate.",
            "example": "active",
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "name",
          "status"
        ],
        "title": "ServiceAccountResponse",
        "type": "object"
      },
      "ServiceAccountUpdateRequest": {
        "description": "Request payload for updating a service account.",
        "properties": {
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Updated description for this service account.",
            "example": "Updated service account description",
            "title": "Description"
          },
          "name": {
            "anyOf": [
              {
                "maxLength": 255,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Updated name for this service account.",
            "example": "Updated API Documentation",
            "title": "Name"
          }
        },
        "title": "ServiceAccountUpdateRequest",
        "type": "object"
      },
      "SftpTestConnectionRequest": {
        "description": "Request model for testing SFTP connection.",
        "properties": {
          "auth_type": {
            "$ref": "#/components/schemas/CredentialTypeEnum",
            "description": "Authentication type: password or key_file"
          },
          "host": {
            "description": "SFTP server hostname or IP address",
            "title": "Host",
            "type": "string"
          },
          "password": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Password for SFTP authentication (required for password auth)",
            "title": "Password"
          },
          "port": {
            "default": 22,
            "description": "SFTP server port",
            "title": "Port",
            "type": "integer"
          },
          "private_key_data": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Private key content for SFTP authentication (required for key_file auth)",
            "title": "Private Key Data"
          },
          "private_key_passphrase": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Passphrase for encrypted private key (optional)",
            "title": "Private Key Passphrase"
          },
          "test_path": {
            "default": "/",
            "description": "Directory path to test write access",
            "title": "Test Path",
            "type": "string"
          },
          "username": {
            "description": "Username for SFTP authentication",
            "title": "Username",
            "type": "string"
          }
        },
        "required": [
          "host",
          "username",
          "auth_type"
        ],
        "title": "SftpTestConnectionRequest",
        "type": "object"
      },
      "StatusBody": {
        "description": "Body for status update messages.",
        "properties": {
          "content": {
            "title": "Content",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "type": {
            "const": "status",
            "default": "status",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "status",
          "content"
        ],
        "title": "StatusBody",
        "type": "object"
      },
      "TTLSettings": {
        "description": "TTL configuration for flow executions.",
        "properties": {
          "seconds": {
            "anyOf": [
              {
                "maximum": 5097600.0,
                "minimum": 60.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "TTL in seconds after completion (1 minute to 30 days). Required when enabled=True.",
            "title": "Seconds"
          }
        },
        "title": "TTLSettings",
        "type": "object"
      },
      "Task": {
        "description": "Represents a task in a workflow.\n\nAttributes:\n    id: Unique identifier for the task, or None if not yet assigned.\n    type: The type of task.\n    config: Configuration parameters for the task.",
        "properties": {
          "config": {
            "additionalProperties": true,
            "title": "Config",
            "type": "object"
          },
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Id"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "id",
          "type"
        ],
        "title": "Task",
        "type": "object"
      },
      "TaskDynamicDataRequest": {
        "description": "Request model for task data analysis endpoint.\n\nAccepts a flow definition in the SuperAI Flows DSL format for validation\nand schema extraction. The flow definition should include all tasks,\nconnections, and configurations needed to execute the flow.",
        "properties": {
          "flow_definition": {
            "additionalProperties": true,
            "description": "Complete flow definition in SuperAI Flows DSL format. Must include: - 'name': Flow name (string, required). - 'tasks': List of task definitions with task_executor_name, parameters, etc. - 'connections': Optional list of task dependencies and data flows. - 'config': Optional flow-level configuration. The definition will be validated and analyzed to extract task output schemas and dynamic configuration data. Validation errors will be returned in the response if the definition is invalid.",
            "examples": [
              {
                "name": "my-workflow",
                "tasks": [
                  {
                    "name": "fetch_data",
                    "parameters": {
                      "method": "GET",
                      "url": "https://api.example.com/data"
                    },
                    "task_executor_name": "http_request"
                  },
                  {
                    "name": "process_data",
                    "parameters": {
                      "code": "result = input_data['value'] * 2"
                    },
                    "task_executor_name": "python_code"
                  }
                ]
              }
            ],
            "title": "Flow Definition",
            "type": "object"
          }
        },
        "required": [
          "flow_definition"
        ],
        "title": "TaskDynamicDataRequest",
        "type": "object"
      },
      "TaskDynamicDataResponse": {
        "description": "Response model containing task output schemas, dynamic data, and validation results.\n\nThis response provides all metadata needed to build UIs for flow configuration,\nvalidate task connections, and understand what data each task will produce.\nEach field serves a specific purpose in the flow building and validation process.",
        "properties": {
          "dynamic_data": {
            "additionalProperties": true,
            "description": "Runtime-dependent configuration options for tasks, keyed by task name. Contains dynamic values that depend on user credentials, external services, or other runtime state. Format: {task_name: {field_name: options}}. Common use cases: - Dropdown options (e.g., available Google Sheets, database tables). - Conditional field visibility based on other parameters. - Resource lists requiring authentication (e.g., Slack channels). - Default values computed from external state. The structure varies by task executor - check task executor documentation for specific formats. Empty dict if no tasks provide dynamic data or if fetching dynamic data failed (check validation_errors).",
            "examples": [
              {
                "read_sheet": {
                  "spreadsheet_id": {
                    "options": [
                      {
                        "label": "Sales Data 2024",
                        "value": "abc123"
                      },
                      {
                        "label": "Customer List",
                        "value": "def456"
                      }
                    ]
                  }
                }
              }
            ],
            "title": "Dynamic Data",
            "type": "object"
          },
          "input_schemas": {
            "additionalProperties": true,
            "description": "JSON schemas for input task executors' inputs, keyed by task name. Each schema describes the structure and types of data the task expects as input. Only included when include_input_schema=true is specified. Format: {task_name: json_schema_object}. JSON schemas follow JSON Schema Draft 7 specification and include: - 'type': Root type (usually 'object'). - 'properties': Object properties with types and descriptions. - 'required': List of required property names. - 'title': Human-readable schema name. Use these schemas to generate input forms for flow execution. Empty dict if include_input_schema=false or no input tasks found.",
            "examples": [
              {
                "custom_form_input": {
                  "properties": {
                    "document_url": {
                      "description": "URL to uploaded document",
                      "type": "string"
                    },
                    "filename": {
                      "description": "Name of uploaded file",
                      "type": "string"
                    },
                    "metadata": {
                      "description": "File metadata",
                      "type": "object"
                    },
                    "mime_type": {
                      "description": "MIME type of uploaded file",
                      "type": "string"
                    }
                  },
                  "required": [
                    "filename",
                    "mime_type",
                    "document_url"
                  ],
                  "title": "CustomFormInput",
                  "type": "object"
                }
              }
            ],
            "title": "Input Schemas",
            "type": "object"
          },
          "output_schemas": {
            "additionalProperties": true,
            "description": "JSON schemas for task outputs, keyed by task name. Each schema describes the structure and types of data the task will produce. Format: {task_name: json_schema_object}. JSON schemas follow JSON Schema Draft 7 specification and include: - 'type': Root type (usually 'object'). - 'properties': Object properties with types and descriptions. - 'required': List of required property names. - 'title': Human-readable schema name. Use these schemas to validate downstream task inputs and generate UI forms. Empty dict if no tasks have output schemas or if all tasks failed to load.",
            "examples": [
              {
                "fetch_data": {
                  "properties": {
                    "body": {
                      "description": "Response body as JSON",
                      "type": "object"
                    },
                    "status_code": {
                      "description": "HTTP response status",
                      "type": "integer"
                    }
                  },
                  "required": [
                    "status_code",
                    "body"
                  ],
                  "title": "HttpRequestOutput",
                  "type": "object"
                }
              }
            ],
            "title": "Output Schemas",
            "type": "object"
          },
          "validation_errors": {
            "description": "Human-readable validation error messages describing problems with the flow definition. Errors are returned even if the request succeeds (HTTP 200) - check this field to determine if the flow definition is valid. Empty list indicates a valid flow. Error categories: - Structural errors: Missing required fields, invalid task references. - Semantic errors (full_validation=true only): Invalid parameter values,   unreachable tasks, circular dependencies. - Task executor errors: Unknown task executor, failed to load executor. - Schema extraction errors: Failed to determine output schema for task. Each error is a descriptive string suitable for display to users. Example: 'Task \"process_data\" references unknown task \"fetch_data\" in input mapping'.",
            "examples": [
              [
                "Task 'invalid_task' uses unknown task executor 'nonexistent_executor'"
              ],
              []
            ],
            "items": {
              "type": "string"
            },
            "title": "Validation Errors",
            "type": "array"
          }
        },
        "title": "TaskDynamicDataResponse",
        "type": "object"
      },
      "TaskErrorData": {
        "description": "Error summary data for a single task.",
        "properties": {
          "errors": {
            "items": {
              "$ref": "#/components/schemas/ErrorSummary"
            },
            "title": "Errors",
            "type": "array"
          },
          "id": {
            "title": "Id",
            "type": "string"
          },
          "type": {
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "errors"
        ],
        "title": "TaskErrorData",
        "type": "object"
      },
      "TaskExecutionAPI": {
        "description": "API model representing a task execution within a flow.\n\nTask executions track individual task invocations during flow execution.\nEach task can execute multiple times (retries, loops), identified by\ntask_execution_idx. Contains full execution context including inputs,\noutputs, errors, and lifecycle metadata.\n\nResource Hierarchy:\n    Organization \u2192 Flow \u2192 Flow Execution \u2192 Task Execution",
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp when task execution was created (UTC). Represents when the task was queued or first recorded in the system. NULL for legacy records created before timestamp tracking.",
            "examples": [
              "2025-01-23T10:30:00Z"
            ],
            "title": "Created At"
          },
          "error": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Error information when task execution fails. Only populated when status is 'failed'; NULL for other states. Contains error message, exception type, and stack trace for debugging. \n\nTypical structure:\n{\n  \"message\": \"Human-readable error description\",\n  \"type\": \"Exception class name\",\n  \"traceback\": \"Full Python stack trace\"\n}\n\nUsed for debugging, monitoring, and error reporting workflows.",
            "examples": [
              {
                "message": "Connection timeout after 30 seconds",
                "traceback": "Traceback (most recent call last):\n  ...",
                "type": "ConnectionError"
              }
            ],
            "title": "Error"
          },
          "flow_execution_id": {
            "description": "ID of the parent flow execution containing this task. Establishes the execution hierarchy and determines organization scope. All tasks in a flow execution share the same flow_execution_id.",
            "examples": [
              "223e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this task execution. Auto-generated UUID assigned at creation time. Used for direct resource access via GET /task-executions/{id}.",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "input": {
            "description": "Input parameters provided to the task executor. Schema varies by task type; can be object, array, or primitive. NULL if task accepts no input parameters. Resolved from flow definition and upstream task outputs.",
            "examples": [
              {
                "recipient": "user@example.com",
                "subject": "Hello"
              },
              [
                1,
                2,
                3,
                4,
                5
              ],
              "simple string input"
            ],
            "title": "Input"
          },
          "modified_by": {
            "default": "system",
            "description": "Identifier of the actor who last modified this task execution. Tracks manual interventions vs automated updates for auditing. Defaults to 'system' for worker-initiated changes. \n\nValues:\n- 'system': System-automated changes (workers, background jobs)\n- User ID: UUID string of the user who made the change (e.g., '123e4567-e89b-12d3-a456-426614174000')\n- Integration type: For service accounts/integrations (e.g., 'integration', 'service-account')",
            "examples": [
              "system",
              "123e4567-e89b-12d3-a456-426614174000",
              "integration"
            ],
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "ID of the organization owning this task execution. Inherited from parent flow execution for tenant isolation. Used for Row-Level Security (RLS) filtering and authorization. All task executions are scoped to a single organization.",
            "examples": [
              "323e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "output": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Output data produced by the task executor upon successful completion. Only populated when status is 'completed'; NULL for other states. Available to downstream tasks via {{task_name.output}} syntax. Structure defined by task executor implementation. Used for task chaining and flow data propagation.",
            "examples": [
              {
                "email_id": "msg_123",
                "sent_at": "2025-01-23T10:30:00Z"
              },
              {
                "duration_ms": 1234,
                "errors": 0,
                "processed_rows": 150
              }
            ],
            "title": "Output"
          },
          "status": {
            "description": "Current execution state of the task. Valid values: 'queued', 'running', 'completed', 'failed', 'deleted', 'stale'. \n\nStatus transitions:\n- queued \u2192 running: Task execution started\n- running \u2192 completed: Task succeeded with output\n- running \u2192 failed: Task encountered error\n- any \u2192 deleted: Task soft-deleted (hidden from list operations)\n- completed/failed \u2192 stale: Task data is outdated\n\nQueued: Task scheduled but not started\nRunning: Task actively executing\nCompleted: Task finished successfully (output field set)\nFailed: Task encountered error (error field set)\nDeleted: Soft-deleted, excluded from queries (preserves audit trail)\nStale: Previously completed but data is now outdated",
            "examples": [
              "queued",
              "running",
              "completed",
              "failed",
              "deleted",
              "stale"
            ],
            "title": "Status",
            "type": "string"
          },
          "task_execution_idx": {
            "description": "Zero-based execution index tracking task attempts. 0 = first execution, 1 = first retry, 2 = second retry, etc. Increments for each retry or loop iteration of the same task. Combines with flow_execution_id and task_name to form unique composite key.",
            "examples": [
              0,
              1,
              2
            ],
            "minimum": 0.0,
            "title": "Task Execution Idx",
            "type": "integer"
          },
          "task_name": {
            "description": "Name of the task as defined in the flow definition YAML. Case-sensitive identifier matching flow configuration. Used to reference task in flow logic and dependency graphs.",
            "examples": [
              "send_email",
              "process_data",
              "validate_input"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Task Name",
            "type": "string"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of last update to this task execution (UTC). Changes whenever status, output, or error fields are modified. Used for change tracking and optimistic locking. NULL for records never updated since creation.",
            "examples": [
              "2025-01-23T10:35:00Z"
            ],
            "title": "Updated At"
          }
        },
        "required": [
          "id",
          "flow_execution_id",
          "task_execution_idx",
          "task_name",
          "status",
          "organization_id"
        ],
        "title": "TaskExecutionAPI",
        "type": "object"
      },
      "TaskExecutionWithTagsAPI": {
        "description": "API model for TaskExecution including associated tags.\n\nExtended version of TaskExecutionAPI that includes tags for categorization\nand workflow state tracking. Used by list endpoints to provide rich context\nwithout requiring separate tag queries.\n\nTags enable workflows like:\n- Review/approval processes ('reviewed', 'approved', 'rejected')\n- Quality assurance ('quality_checked', 'flagged')\n- Custom business logic ('priority_high', 'requires_attention')",
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp when task execution was created (UTC). Represents when the task was queued or first recorded in the system. NULL for legacy records created before timestamp tracking.",
            "examples": [
              "2025-01-23T10:30:00Z"
            ],
            "title": "Created At"
          },
          "error": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Error information when task execution fails. Only populated when status is 'failed'; NULL for other states. Contains error message, exception type, and stack trace for debugging. \n\nTypical structure:\n{\n  \"message\": \"Human-readable error description\",\n  \"type\": \"Exception class name\",\n  \"traceback\": \"Full Python stack trace\"\n}\n\nUsed for debugging, monitoring, and error reporting workflows.",
            "examples": [
              {
                "message": "Connection timeout after 30 seconds",
                "traceback": "Traceback (most recent call last):\n  ...",
                "type": "ConnectionError"
              }
            ],
            "title": "Error"
          },
          "flow_execution_id": {
            "description": "ID of the parent flow execution containing this task. Establishes the execution hierarchy and determines organization scope. All tasks in a flow execution share the same flow_execution_id.",
            "examples": [
              "223e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for this task execution. Auto-generated UUID assigned at creation time. Used for direct resource access via GET /task-executions/{id}.",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "input": {
            "description": "Input parameters provided to the task executor. Schema varies by task type; can be object, array, or primitive. NULL if task accepts no input parameters. Resolved from flow definition and upstream task outputs.",
            "examples": [
              {
                "recipient": "user@example.com",
                "subject": "Hello"
              },
              [
                1,
                2,
                3,
                4,
                5
              ],
              "simple string input"
            ],
            "title": "Input"
          },
          "modified_by": {
            "default": "system",
            "description": "Identifier of the actor who last modified this task execution. Tracks manual interventions vs automated updates for auditing. Defaults to 'system' for worker-initiated changes. \n\nValues:\n- 'system': System-automated changes (workers, background jobs)\n- User ID: UUID string of the user who made the change (e.g., '123e4567-e89b-12d3-a456-426614174000')\n- Integration type: For service accounts/integrations (e.g., 'integration', 'service-account')",
            "examples": [
              "system",
              "123e4567-e89b-12d3-a456-426614174000",
              "integration"
            ],
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "ID of the organization owning this task execution. Inherited from parent flow execution for tenant isolation. Used for Row-Level Security (RLS) filtering and authorization. All task executions are scoped to a single organization.",
            "examples": [
              "323e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "output": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Output data produced by the task executor upon successful completion. Only populated when status is 'completed'; NULL for other states. Available to downstream tasks via {{task_name.output}} syntax. Structure defined by task executor implementation. Used for task chaining and flow data propagation.",
            "examples": [
              {
                "email_id": "msg_123",
                "sent_at": "2025-01-23T10:30:00Z"
              },
              {
                "duration_ms": 1234,
                "errors": 0,
                "processed_rows": 150
              }
            ],
            "title": "Output"
          },
          "status": {
            "description": "Current execution state of the task. Valid values: 'queued', 'running', 'completed', 'failed', 'deleted', 'stale'. \n\nStatus transitions:\n- queued \u2192 running: Task execution started\n- running \u2192 completed: Task succeeded with output\n- running \u2192 failed: Task encountered error\n- any \u2192 deleted: Task soft-deleted (hidden from list operations)\n- completed/failed \u2192 stale: Task data is outdated\n\nQueued: Task scheduled but not started\nRunning: Task actively executing\nCompleted: Task finished successfully (output field set)\nFailed: Task encountered error (error field set)\nDeleted: Soft-deleted, excluded from queries (preserves audit trail)\nStale: Previously completed but data is now outdated",
            "examples": [
              "queued",
              "running",
              "completed",
              "failed",
              "deleted",
              "stale"
            ],
            "title": "Status",
            "type": "string"
          },
          "tags": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/FlowTaskTagAPI"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Array of tags associated with this task execution. Tags provide categorization, workflow state, and custom metadata. Each tag includes: tag name, type, optional metadata, and status. Soft-deleted tags (status='deleted') are excluded from results. NULL or empty array if no tags are associated with this task execution. \n\nCommon tag types:\n- review_status: 'reviewed', 'approved', 'rejected'\n- quality: 'flagged', 'quality_checked', 'verified'\n- custom: User-defined business tags",
            "examples": [
              [
                {
                  "tag": "reviewed",
                  "tag_metadata": {
                    "notes": "Looks good",
                    "reviewer": "user@example.com"
                  },
                  "tag_type": "review_status"
                },
                {
                  "tag": "priority_high",
                  "tag_type": "custom"
                }
              ]
            ],
            "title": "Tags"
          },
          "task_execution_idx": {
            "description": "Zero-based execution index tracking task attempts. 0 = first execution, 1 = first retry, 2 = second retry, etc. Increments for each retry or loop iteration of the same task. Combines with flow_execution_id and task_name to form unique composite key.",
            "examples": [
              0,
              1,
              2
            ],
            "minimum": 0.0,
            "title": "Task Execution Idx",
            "type": "integer"
          },
          "task_name": {
            "description": "Name of the task as defined in the flow definition YAML. Case-sensitive identifier matching flow configuration. Used to reference task in flow logic and dependency graphs.",
            "examples": [
              "send_email",
              "process_data",
              "validate_input"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Task Name",
            "type": "string"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of last update to this task execution (UTC). Changes whenever status, output, or error fields are modified. Used for change tracking and optimistic locking. NULL for records never updated since creation.",
            "examples": [
              "2025-01-23T10:35:00Z"
            ],
            "title": "Updated At"
          }
        },
        "required": [
          "id",
          "flow_execution_id",
          "task_execution_idx",
          "task_name",
          "status",
          "organization_id"
        ],
        "title": "TaskExecutionWithTagsAPI",
        "type": "object"
      },
      "TaskExecutorResponse": {
        "description": "Response model for a task executor definition.\n\nTask executors are reusable workflow components that perform specific operations\nwithin a flow. Each executor defines its input schema, execution behavior, and\ncapabilities. This model provides all metadata needed to programmatically\ndiscover and configure task executors in flow definitions.",
        "example": {
          "is_input_task_executor": false,
          "is_schedulable_executor": false,
          "parameters_schema": {
            "properties": {
              "model": {
                "default": "gpt-4-vision",
                "description": "AI model to use for extraction",
                "enum": [
                  "gpt-4-vision",
                  "claude-3-opus"
                ],
                "type": "string"
              },
              "schema": {
                "description": "Field definitions to extract from documents",
                "type": "object"
              }
            },
            "required": [
              "schema"
            ],
            "type": "object"
          },
          "task_executor_agent_prompt": "Use this executor to extract specific fields from documents. Define a schema with field names, types, and descriptions. The executor will use AI to locate and extract those fields from uploaded documents.",
          "task_executor_description": "Extracts structured data from documents using vision-language models and OCR",
          "task_executor_name": "doc_to_structured"
        },
        "properties": {
          "flow_input_schema": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "description": "JSON Schema defining runtime input data for input task executors. Only present for executors that can trigger/receive flow executions (is_input_task_executor=true). \n\nDefines the shape of data received from external sources: webhooks, email attachments, file uploads, scheduled triggers, etc. \n\nDifference from parameters_schema:\n- parameters_schema: Static configuration set during flow design\n- flow_input_schema: Dynamic data received at runtime\n\nExample: An 'receive_email' executor has:\n- parameters_schema: {email_address, filters, ...} (configuration)\n- flow_input_schema: {from, subject, body, attachments, ...} (runtime data)\n\nNull for non-input executors (standard task executors).",
            "examples": [
              {
                "properties": {
                  "attachments": {
                    "description": "File URLs for attachments",
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "body": {
                    "description": "Email body content",
                    "type": "string"
                  },
                  "from": {
                    "description": "Sender email address",
                    "format": "email",
                    "type": "string"
                  },
                  "subject": {
                    "description": "Email subject line",
                    "type": "string"
                  }
                },
                "type": "object"
              },
              null
            ],
            "title": "Flow Input Schema"
          },
          "is_input_task_executor": {
            "description": "Whether this executor can trigger flow execution from external sources. \n\nInput executors (true):\n- Receive data from external systems (webhooks, emails, files, schedules)\n- Can be first task in a flow\n- Have flow_input_schema defining received data structure\n- Examples: receive_email, receive_file, webhook_receive\n\nNon-input executors (false):\n- Process data within flow execution\n- Cannot trigger flows (must be downstream of input executor)\n- No flow_input_schema\n- Examples: send_email, doc_to_structured, classify_text, external_db\n\nUsed by flow validators to ensure flows have at least one input executor.",
            "examples": [
              true,
              false
            ],
            "title": "Is Input Task Executor",
            "type": "boolean"
          },
          "is_schedulable_executor": {
            "description": "Whether this executor supports scheduled/recurring execution. \n\nSchedulable executors (true):\n- Can run on cron schedules (hourly, daily, weekly, custom)\n- Support time-based triggers\n- Often paired with input executors\n- Examples: scheduled_db_query\n\nNon-schedulable executors (false):\n- Event-driven only (triggered by upstream tasks or external events)\n- Cannot run on schedule\n- Examples: send_email, classify_document, receive_email (event-driven)\n\nNote: Scheduling is configured at the flow execution level, not per task. This flag indicates executor compatibility with scheduling.",
            "examples": [
              true,
              false
            ],
            "title": "Is Schedulable Executor",
            "type": "boolean"
          },
          "parameters_schema": {
            "additionalProperties": true,
            "description": "JSON Schema defining configuration parameters for this task executor. Describes required and optional parameters, their types, and validation rules. Clients use this schema to generate configuration UIs and validate inputs. \n\nSchema Format: JSON Schema Draft 2020-12 specification \n\nCommon properties: type, required, properties, additionalProperties, description, examples, enum, default, minimum, maximum, pattern \n\nUsed for: UI form generation, parameter validation, API documentation \n\nNote: This is the CONFIGURATION schema (static parameters), not the runtime input schema (see flow_input_schema).",
            "examples": [
              {
                "properties": {
                  "body": {
                    "description": "Email body content (supports templates)",
                    "type": "string"
                  },
                  "recipient": {
                    "description": "Email recipient address",
                    "format": "email",
                    "type": "string"
                  },
                  "subject": {
                    "description": "Email subject line",
                    "maxLength": 200,
                    "type": "string"
                  }
                },
                "required": [
                  "recipient",
                  "subject"
                ],
                "type": "object"
              }
            ],
            "title": "Parameters Schema",
            "type": "object"
          },
          "task_executor_agent_prompt": {
            "description": "Prompt template used by AI agents when configuring this task executor. Provides context to LLM agents about executor capabilities and parameters. Guides automated flow generation and task configuration. \n\nFormat: Natural language instructions for AI agents describing when and how to use this executor. \n\nUsed by: Flow Builder AI Assistant, Auto-configuration agents",
            "examples": [
              "Use this executor to send email notifications. Configure recipient, subject, and body. Supports templates and attachments.",
              "Use this executor to extract structured fields from documents. Specify field names and types in the schema parameter."
            ],
            "title": "Task Executor Agent Prompt",
            "type": "string"
          },
          "task_executor_description": {
            "description": "Human-readable description of what this task executor does. Explains the executor's purpose, behavior, and typical use cases. Displayed in UI flow builders and documentation. \n\nShould be 1-3 sentences focusing on capabilities and outcomes. Written in present tense, active voice.",
            "examples": [
              "Sends email notifications via SMTP or email service provider",
              "Extracts structured data from documents using vision-language models",
              "Receives incoming emails and triggers workflow execution"
            ],
            "minLength": 10,
            "title": "Task Executor Description",
            "type": "string"
          },
          "task_executor_name": {
            "description": "Unique identifier for this task executor type. Used in flow definition YAML to reference this executor. Case-sensitive and immutable. \n\nNaming convention: snake_case with descriptive action verbs. \n\nExamples: 'send_email', 'doc_to_structured', 'classify_document', 'receive_file', 'webhook_notification', 'external_db'",
            "examples": [
              "send_email",
              "doc_to_structured",
              "receive_email",
              "notify_webhook"
            ],
            "minLength": 1,
            "title": "Task Executor Name",
            "type": "string"
          }
        },
        "required": [
          "task_executor_name",
          "task_executor_description",
          "task_executor_agent_prompt",
          "parameters_schema",
          "is_input_task_executor",
          "is_schedulable_executor"
        ],
        "title": "TaskExecutorResponse",
        "type": "object"
      },
      "TaskOutput": {
        "description": "Database model for node output.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "flow_execution_id": {
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "output": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "title": "Output"
          },
          "status": {
            "$ref": "#/components/schemas/ExecutionStatus",
            "default": "queued"
          },
          "summary": {
            "title": "Summary"
          },
          "tags": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "title": "Tags"
          },
          "task_name": {
            "title": "Task Name",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "flow_execution_id",
          "task_name",
          "summary",
          "organization_id"
        ],
        "title": "TaskOutput",
        "type": "object"
      },
      "TaskOutputAPI": {
        "description": "API model representing a task's output data.\n\nTask outputs store the summarized, structured results of task executions.\nUnlike task executions which track the full lifecycle (input, output, error),\ntask outputs focus on the final output data formatted for display, downstream\nconsumption, and workflow decision logic.\n\nKey Differences from Task Execution:\n    - Task Execution: Full execution record with input, output, error, retries\n    - Task Output: Summarized result optimized for querying and display\n    - One task execution typically produces one task output upon completion\n\nResource Hierarchy:\n    Organization \u2192 Flow \u2192 Flow Execution \u2192 Task Output",
        "properties": {
          "created_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp when task output was created (UTC). Represents when the output was recorded in the system. NULL for legacy records created before timestamp tracking.",
            "examples": [
              "2025-01-24T10:30:00Z"
            ],
            "title": "Created At"
          },
          "flow_execution_id": {
            "description": "ID of the parent flow execution containing this task. Establishes the execution hierarchy and organization scope.",
            "examples": [
              "223e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "flow_version": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Version number of the flow definition used for execution. Matches flow_version from parent flow execution. NULL for outputs created before version tracking. Useful for tracking output changes across flow versions.",
            "examples": [
              1,
              2,
              3
            ],
            "title": "Flow Version"
          },
          "id": {
            "description": "Unique identifier for this task output. Auto-generated UUID assigned at creation time. Used for direct resource access via GET /task-outputs/{id}.",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "default": "system",
            "description": "Identifier of the actor who last modified this task output. Tracks who made the last change for auditing purposes. Defaults to 'system' for worker-initiated changes. \n\nValues:\n- 'system': System-automated changes (workers, background jobs)\n- User ID: UUID string of the user who made the change (e.g., '123e4567-e89b-12d3-a456-426614174000')\n- Integration type: For service accounts/integrations (e.g., 'integration', 'service-account')",
            "examples": [
              "system",
              "123e4567-e89b-12d3-a456-426614174000",
              "integration"
            ],
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "ID of the organization owning this task output. Inherited from parent flow execution. Used for Row-Level Security (RLS) and multi-tenant isolation.",
            "examples": [
              "323e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "output": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Full output data produced by the task. May be large or complex; use summary field for UI display. Can be dict, list, or primitive types. NULL if task produces no output data. Available for downstream task consumption in workflows.",
            "examples": [
              {
                "extracted_text": "Long document content...",
                "metadata": {
                  "author": "John"
                }
              },
              [
                {
                  "name": "Item 1",
                  "value": 100
                },
                {
                  "name": "Item 2",
                  "value": 200
                }
              ]
            ],
            "title": "Output"
          },
          "status": {
            "description": "Execution status when output was created. Valid values: 'queued', 'running', 'completed', 'failed', 'deleted', 'stale'. Typically 'completed' for successful task outputs. \n\nStatus meanings:\n- queued: Task scheduled but not started\n- running: Task actively executing\n- completed: Task finished successfully\n- failed: Task encountered error (may have partial output)\n- deleted: Soft-deleted, excluded from queries (preserves audit trail)\n- stale: Output data is outdated (needs refresh)",
            "examples": [
              "queued",
              "running",
              "completed",
              "failed",
              "deleted",
              "stale"
            ],
            "title": "Status",
            "type": "string"
          },
          "summary": {
            "description": "Structured summary of task output for UI display and querying. Typically a dictionary with standardized keys for rendering. \n\nCommon patterns:\n- Document processing: {'pages': 10, 'word_count': 5000}\n- API calls: {'status_code': 200, 'response_time_ms': 450}\n- Data validation: {'valid_rows': 950, 'invalid_rows': 50}",
            "examples": [
              {
                "duration_seconds": 12.5,
                "records_processed": 150,
                "status": "success"
              },
              {
                "email_sent": true,
                "recipient": "user@example.com"
              }
            ],
            "title": "Summary"
          },
          "tags": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ],
            "description": "Task-level tags for categorization and filtering. Typically list of strings or dict with tag metadata. NULL if no tags associated with this output. \n\nCommon patterns:\n- Simple: ['priority:high', 'reviewed']\n- Structured: {'status': 'approved', 'reviewer': 'user@example.com'}",
            "examples": [
              [
                "priority:high",
                "customer:acme",
                "reviewed"
              ],
              {
                "reviewer": "user@example.com",
                "status": "approved"
              }
            ],
            "title": "Tags"
          },
          "task_name": {
            "description": "Name of the task that produced this output. Case-sensitive identifier matching flow definition YAML. Used to associate output with specific workflow task.",
            "examples": [
              "extract_data",
              "send_email",
              "validate_document"
            ],
            "maxLength": 200,
            "minLength": 1,
            "title": "Task Name",
            "type": "string"
          },
          "updated_at": {
            "anyOf": [
              {
                "format": "date-time",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "ISO 8601 timestamp of last update to this output (UTC). Changes when summary, output, tags, or status are modified. NULL for records never updated since creation.",
            "examples": [
              "2025-01-24T10:35:00Z"
            ],
            "title": "Updated At"
          }
        },
        "required": [
          "id",
          "flow_execution_id",
          "task_name",
          "summary",
          "status",
          "organization_id"
        ],
        "title": "TaskOutputAPI",
        "type": "object"
      },
      "TaskSummaryResponse": {
        "description": "Summary of a task execution within a flow execution.\n\nRepresents aggregated task information with status and metadata.\nUsed for displaying task-level details in execution views.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "flow_execution_id": {
            "description": "UUID of the parent flow execution containing this task",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "format": "uuid",
            "title": "Flow Execution Id",
            "type": "string"
          },
          "flow_version": {
            "anyOf": [
              {
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "description": "Version of the flow definition when this task executed. May differ from current flow version if flow was updated.",
            "example": 3,
            "title": "Flow Version"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "status": {
            "description": "Current status of the task execution. Common values: 'running', 'completed', 'failed', 'skipped'",
            "example": "completed",
            "title": "Status",
            "type": "string"
          },
          "summary": {
            "description": "Task execution summary data. Structure varies by task type. May contain results, metrics, or status information.",
            "example": {
              "duration_seconds": 12.5,
              "processed_items": 42
            },
            "title": "Summary"
          },
          "tags": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional list of tags associated with this task. Tags use key:value format for categorization. Example: ['priority:high', 'department:finance']",
            "example": [
              "priority:high",
              "type:extraction"
            ],
            "title": "Tags"
          },
          "task_name": {
            "description": "Name of the task as defined in the flow definition. Case-sensitive.",
            "example": "process_document",
            "maxLength": 255,
            "minLength": 1,
            "title": "Task Name",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "flow_execution_id",
          "task_name",
          "summary",
          "status"
        ],
        "title": "TaskSummaryResponse",
        "type": "object"
      },
      "TranscriptionResponse": {
        "description": "Response model for audio file transcription.\n\nReturns transcribed text from speech-to-text processing, or null if transcription failed.",
        "properties": {
          "transcription": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Transcribed text from audio file. Null if transcription failed or audio unintelligible.",
            "examples": [
              "Create a workflow that processes customer orders and sends email notifications"
            ],
            "title": "Transcription"
          }
        },
        "title": "TranscriptionResponse",
        "type": "object"
      },
      "TransitionToBuildBody": {
        "description": "Body for planning to build transition messages.",
        "properties": {
          "flow_id": {
            "title": "Flow Id",
            "type": "string"
          },
          "type": {
            "const": "planning_to_build_transition",
            "default": "planning_to_build_transition",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "flow_id"
        ],
        "title": "TransitionToBuildBody",
        "type": "object"
      },
      "UpdateConversationPhase": {
        "description": "Request to update conversation phase and metadata.\n\nManually transitions conversation phase. Typically phases transition automatically\nthrough agent interactions, but this enables manual control for error recovery.",
        "properties": {
          "payload": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional phase-specific metadata or context",
            "title": "Payload"
          },
          "phase": {
            "$ref": "#/components/schemas/ConversationPhase",
            "description": "New conversation phase. Valid values: planning (define structure), building (construct workflow), execution (run workflow), error_resolution (debug and fix errors)."
          }
        },
        "required": [
          "phase"
        ],
        "title": "UpdateConversationPhase",
        "type": "object"
      },
      "UpdateOrganizationRequest": {
        "description": "API request model for updating an existing organization.\n\nSupports partial updates where only provided fields are modified.\nAll fields are optional to enable targeted updates without affecting\nother organization properties.",
        "properties": {
          "is_active": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "description": "New active status. Optional. Set to False to prevent user logins without full deactivation. Set to True to reactivate organization. Note: Does not cascade to users (use PATCH /deactivate for that). If None, active status remains unchanged.",
            "title": "Is Active"
          },
          "name": {
            "anyOf": [
              {
                "maxLength": 200,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New organization display name. Optional. If provided, must be unique across the platform. Constraints: 1-200 characters when provided. If None, name remains unchanged.",
            "examples": [
              "Acme Corp (Renamed)",
              "New Engineering Division"
            ],
            "title": "Name"
          }
        },
        "title": "UpdateOrganizationRequest",
        "type": "object"
      },
      "UpdateUserPartialRequest": {
        "description": "API request model for partial user updates (admin UI).\n\nRestricted update model that only allows modification of first_name,\nlast_name, and role. Email and status cannot be changed through this\nendpoint to maintain data integrity and security.",
        "properties": {
          "first_name": {
            "anyOf": [
              {
                "maxLength": 100,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New first name for the user. Optional. Constraints: 1-100 characters when provided. If None, first name remains unchanged.",
            "examples": [
              "John",
              "Jane"
            ],
            "title": "First Name"
          },
          "last_name": {
            "anyOf": [
              {
                "maxLength": 100,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New last name for the user. Optional. Constraints: 1-100 characters when provided. If None, last name remains unchanged.",
            "examples": [
              "Doe",
              "Smith"
            ],
            "title": "Last Name"
          },
          "role": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New role for the user. Optional. Valid values: 'org_admin', 'backoffice', 'app_user', 'integration'. If None, role remains unchanged.",
            "examples": [
              "org_admin",
              "app_user"
            ],
            "title": "Role"
          }
        },
        "title": "UpdateUserPartialRequest",
        "type": "object"
      },
      "UploadUrlResponse": {
        "description": "Response containing pre-signed upload URL for file uploads.\n\nGenerated by POST /database/{db_id}/upload-url endpoint.\nUse this URL to upload files directly to cloud storage.",
        "example": {
          "expires_at": "2024-01-15T11:30:00Z",
          "file_key": "databases/123e4567-e89b-12d3-a456-426614174000/documents/uuid.csv",
          "upload_url": "https://storage.googleapis.com/bucket/databases/db-id/documents/uuid.csv?signature=abc"
        },
        "properties": {
          "expires_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "UTC timestamp when the upload URL expires. Complete the upload before this time. Typically 1 hour from generation.",
            "examples": [
              "2024-01-15T11:30:00Z"
            ],
            "title": "Expires At"
          },
          "file_key": {
            "description": "Unique key identifying the file location in storage. Use this key to reference the file in subsequent operations.",
            "examples": [
              "databases/123e4567-e89b-12d3-a456-426614174000/documents/file-uuid.csv"
            ],
            "title": "File Key",
            "type": "string"
          },
          "upload_url": {
            "description": "Pre-signed URL for uploading file to cloud storage. Upload your file to this URL using PUT or POST request.",
            "examples": [
              "https://storage.googleapis.com/bucket/path/file.csv?signature=abc123&expires=1640000000"
            ],
            "title": "Upload Url",
            "type": "string"
          }
        },
        "required": [
          "upload_url",
          "file_key"
        ],
        "title": "UploadUrlResponse",
        "type": "object"
      },
      "UsageRequest": {
        "description": "Simplified usage request for batch creation by flow execution.\n\nUsed in bulk usage recording where product is identified by\nunit and provider rather than product_id. System will look up\nor create the appropriate product automatically.",
        "properties": {
          "amount": {
            "description": "Quantity of units consumed. Must be a positive integer. Example: 1500 for 1500 tokens, 10 for 10 API requests",
            "examples": [
              1500,
              10,
              3600
            ],
            "exclusiveMinimum": 0.0,
            "title": "Amount",
            "type": "integer"
          },
          "estimated_cost_per_unit": {
            "anyOf": [
              {
                "minimum": 0.0,
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional estimated cost per unit in USD. Used to calculate total cost if product doesn't have pricing data. Example: 0.00003 for $0.03 per 1000 tokens",
            "examples": [
              3e-05,
              0.001,
              0.1
            ],
            "title": "Estimated Cost Per Unit"
          },
          "provider": {
            "description": "Service provider supplying the product. Combined with unit to identify the product. Examples: 'OpenAI', 'Anthropic', 'AWS'",
            "examples": [
              "OpenAI",
              "Anthropic",
              "AWS"
            ],
            "maxLength": 100,
            "minLength": 1,
            "title": "Provider",
            "type": "string"
          },
          "unit": {
            "description": "Unit of measurement for this usage. Combined with provider to identify the product. Examples: 'tokens', 'requests', 'seconds'",
            "examples": [
              "tokens",
              "requests",
              "seconds"
            ],
            "maxLength": 50,
            "minLength": 1,
            "title": "Unit",
            "type": "string"
          }
        },
        "required": [
          "amount",
          "unit",
          "provider"
        ],
        "title": "UsageRequest",
        "type": "object"
      },
      "UsageResponse": {
        "description": "API response model for Usage entity.\n\nRepresents a single instance of product consumption during system operation.\nTracks who used what resource, how much, when, and estimated cost.\nUsed for billing, analytics, and usage dashboards.",
        "properties": {
          "amount": {
            "description": "Quantity of units consumed in this usage event. Must be a positive integer. Multiplied by estimated_cost_per_unit to calculate total cost.",
            "examples": [
              1500,
              10,
              3600
            ],
            "exclusiveMinimum": 0.0,
            "title": "Amount",
            "type": "integer"
          },
          "created_at": {
            "description": "Timestamp when the usage was recorded in the system. ISO 8601 format with timezone. Represents when the consumption occurred.",
            "examples": [
              "2024-01-15T10:30:00Z"
            ],
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for the usage record. Used to reference specific consumption events. Format: UUID v4",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "description": "Optional metadata about the usage context. May include flow_execution_id, task_name, model parameters, or other details relevant to understanding the consumption. Structure varies by product type.",
            "examples": [
              {
                "flow_execution_id": "abc123",
                "model": "gpt-4",
                "task_name": "generate_summary"
              }
            ],
            "title": "Metadata",
            "type": "object"
          },
          "modified_by": {
            "description": "Identifier of the system or user that last modified this record. Typically a service name or user ID for audit purposes. Examples: 'flow-worker', 'admin-user', 'billing-service'",
            "examples": [
              "flow-worker",
              "admin-user",
              "system"
            ],
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "Identifier of the organization that incurred this usage. Used for multi-tenant cost tracking and billing. All usage is attributed to an organization for invoicing.",
            "examples": [
              "123e4567-e89b-12d3-a456-426614174000"
            ],
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "product_id": {
            "description": "Identifier of the product that was consumed. Links usage to specific billable resource. Use GET /internal/products/{id} to fetch product details.",
            "examples": [
              "7c9e6679-7425-40de-944b-e07fc1f90ae7"
            ],
            "format": "uuid",
            "title": "Product Id",
            "type": "string"
          },
          "unit": {
            "description": "Unit of measurement for this usage record. Should match the unit defined in the associated Product. Examples: 'tokens', 'requests', 'seconds', 'GB'",
            "examples": [
              "tokens",
              "requests",
              "seconds"
            ],
            "title": "Unit",
            "type": "string"
          },
          "updated_at": {
            "description": "Timestamp when the usage record was last modified. ISO 8601 format with timezone. Updates automatically on any field changes.",
            "examples": [
              "2024-01-15T10:30:00Z"
            ],
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "user_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "Optional identifier of the user who triggered this usage. May be null for system-level or automated usage. Useful for per-user usage analytics and cost allocation.",
            "examples": [
              "a1b2c3d4-e5f6-4789-0abc-def123456789"
            ],
            "title": "User Id"
          }
        },
        "required": [
          "id",
          "product_id",
          "organization_id",
          "unit",
          "amount",
          "created_at",
          "updated_at",
          "modified_by"
        ],
        "title": "UsageResponse",
        "type": "object"
      },
      "User": {
        "description": "User model",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "email": {
            "title": "Email",
            "type": "string"
          },
          "first_name": {
            "title": "First Name",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "last_name": {
            "title": "Last Name",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "role": {
            "$ref": "#/components/schemas/UserRole",
            "default": "app_user"
          },
          "status": {
            "$ref": "#/components/schemas/UserStatus",
            "default": "pending"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "user_auth_id": {
            "anyOf": [
              {
                "format": "uuid",
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "User Auth Id"
          }
        },
        "required": [
          "first_name",
          "last_name",
          "email",
          "organization_id"
        ],
        "title": "User",
        "type": "object"
      },
      "UserActionMessage": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/ConfirmPlanAction"
          },
          {
            "$ref": "#/components/schemas/CancelAction"
          },
          {
            "$ref": "#/components/schemas/AcceptWorkflowAction"
          },
          {
            "$ref": "#/components/schemas/RejectWorkflowAction"
          },
          {
            "$ref": "#/components/schemas/InitiateErrorResolveAction"
          },
          {
            "$ref": "#/components/schemas/ResolveErrorsAction"
          }
        ]
      },
      "UserIntegrationCredentialsCreate": {
        "description": "Request model for creating user integration credentials",
        "properties": {
          "credential_type": {
            "$ref": "#/components/schemas/CredentialTypeEnum"
          },
          "credentials": {
            "additionalProperties": true,
            "title": "Credentials",
            "type": "object"
          },
          "name": {
            "title": "Name",
            "type": "string"
          },
          "provider": {
            "$ref": "#/components/schemas/ProviderApiEnum"
          }
        },
        "required": [
          "name",
          "provider",
          "credential_type",
          "credentials"
        ],
        "title": "UserIntegrationCredentialsCreate",
        "type": "object"
      },
      "UserIntegrationCredentialsUpdate": {
        "description": "Request model for updating user integration credentials",
        "properties": {
          "credential_type": {
            "$ref": "#/components/schemas/CredentialTypeEnum"
          },
          "credentials": {
            "additionalProperties": true,
            "title": "Credentials",
            "type": "object"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name"
          }
        },
        "required": [
          "credential_type",
          "credentials"
        ],
        "title": "UserIntegrationCredentialsUpdate",
        "type": "object"
      },
      "UserMessage": {
        "anyOf": [
          {
            "$ref": "#/components/schemas/UserTextMessage"
          },
          {
            "$ref": "#/components/schemas/UserActionMessage"
          }
        ]
      },
      "UserProfileResponse": {
        "description": "User profile response with organization name included.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "email": {
            "title": "Email",
            "type": "string"
          },
          "first_name": {
            "title": "First Name",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "last_name": {
            "title": "Last Name",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "organization_name": {
            "title": "Organization Name",
            "type": "string"
          },
          "role": {
            "title": "Role",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "first_name",
          "last_name",
          "email",
          "role",
          "status",
          "organization_id",
          "organization_name"
        ],
        "title": "UserProfileResponse",
        "type": "object"
      },
      "UserRole": {
        "enum": [
          "org_admin",
          "backoffice",
          "app_user",
          "reviewer",
          "publisher",
          "integration"
        ],
        "title": "UserRole",
        "type": "string"
      },
      "UserStatus": {
        "enum": [
          "pending",
          "active",
          "inactive"
        ],
        "title": "UserStatus",
        "type": "string"
      },
      "UserTextMessage": {
        "description": "Text message from user to agent for natural language processing.\n\nUse this message type for regular conversational interactions where the user\ndescribes requirements, asks questions, or provides feedback in natural language.\nThe agent interprets the text and responds appropriately based on conversation\nphase and context.",
        "properties": {
          "message": {
            "description": "Natural language text message to agent. Agent interprets based on conversation phase and context. \n\nExamples:\n- 'Create a workflow that processes customer orders'\n- 'Add a task to send an email notification'\n- 'Change the schedule to run every hour'\n- 'Why did task X fail?'\n\nAgent behavior varies by conversation phase:\n- planning: Interprets as requirements or clarifications\n- building: Treats as modifications or additions to workflow\n- execution: Responds with status or monitoring information\n- error_resolution: Analyzes in context of debugging",
            "examples": [
              "Create a workflow that sends daily reports",
              "Add a task to validate customer data",
              "Schedule this to run at 9 AM every weekday"
            ],
            "minLength": 1,
            "title": "Message",
            "type": "string"
          },
          "message_type": {
            "const": "user_message",
            "default": "user_message",
            "description": "Message type discriminator. Always 'user_message' for text messages.",
            "title": "Message Type",
            "type": "string"
          }
        },
        "required": [
          "message"
        ],
        "title": "UserTextMessage",
        "type": "object"
      },
      "UserUpdateRequest": {
        "description": "Request model for updating the authenticated user's profile information.\n\nAll fields are optional. Only provided fields will be updated,\nallowing partial updates without affecting other user attributes.\nOmitted fields remain unchanged in the database.",
        "properties": {
          "first_name": {
            "anyOf": [
              {
                "maxLength": 100,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "User's first name. Used for display in the UI and in email communications. Must be at least 1 character if provided. Set to null or omit to leave unchanged.",
            "examples": [
              "John",
              "Maria",
              "\u674e"
            ],
            "title": "First Name"
          },
          "last_name": {
            "anyOf": [
              {
                "maxLength": 100,
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "User's last name or family name. Combined with first_name for full name display. Must be at least 1 character if provided. Set to null or omit to leave unchanged.",
            "examples": [
              "Doe",
              "Garc\u00eda",
              "Chen"
            ],
            "title": "Last Name"
          },
          "password": {
            "anyOf": [
              {
                "maxLength": 128,
                "minLength": 8,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "description": "New password for the user account. Note: Password updates are currently not implemented in the API. This field is reserved for future functionality. Password changes should be handled through the authentication service.",
            "examples": [
              "MySecureP@ssw0rd123"
            ],
            "title": "Password"
          }
        },
        "title": "UserUpdateRequest",
        "type": "object"
      },
      "UserWithOrganizationResponse": {
        "description": "API response model for User with organization details included.\n\nExtended user response that includes the organization name for convenience.\nUse this when displaying users in lists or dashboards where organization\ncontext is needed without making additional API calls.",
        "properties": {
          "created_at": {
            "description": "Timestamp when user was created (ISO 8601 UTC).",
            "examples": [
              "2025-01-23T15:30:00Z"
            ],
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "email": {
            "description": "User's email address. Unique within organization. Used for login and notifications.",
            "examples": [
              "john.doe@example.com"
            ],
            "format": "email",
            "title": "Email",
            "type": "string"
          },
          "first_name": {
            "description": "User's first name. Used in UI displays and emails.",
            "examples": [
              "John"
            ],
            "title": "First Name",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for the user. Format: UUID v4",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "last_name": {
            "description": "User's last name. Used in UI displays and emails.",
            "examples": [
              "Doe"
            ],
            "title": "Last Name",
            "type": "string"
          },
          "modified_by": {
            "description": "Identifier of the user or system that last modified this user. Used for audit trail.",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "UUID of the organization this user belongs to.",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "organization_name": {
            "description": "Display name of the user's organization. Included for convenience to avoid additional API calls. Useful in user lists and dashboards showing cross-organization data.",
            "examples": [
              "Acme Corporation",
              "Engineering Team"
            ],
            "title": "Organization Name",
            "type": "string"
          },
          "role": {
            "description": "User's role within the organization. Values: 'org_admin', 'backoffice', 'app_user', 'integration'",
            "examples": [
              "org_admin"
            ],
            "title": "Role",
            "type": "string"
          },
          "status": {
            "description": "User's account status. Values: 'active', 'inactive'. 'active' users can log in; 'inactive' users cannot.",
            "examples": [
              "active"
            ],
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "description": "Timestamp when user was last modified (ISO 8601 UTC).",
            "examples": [
              "2025-01-24T10:45:00Z"
            ],
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          },
          "workflows": {
            "anyOf": [
              {
                "items": {
                  "additionalProperties": true,
                  "type": "object"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "description": "List of workflows the user is invited to. Only included when include_workflows=true query parameter is provided. Each workflow contains basic information like ID and display name.",
            "title": "Workflows"
          }
        },
        "required": [
          "id",
          "first_name",
          "last_name",
          "email",
          "organization_id",
          "organization_name",
          "role",
          "status",
          "created_at",
          "updated_at",
          "modified_by"
        ],
        "title": "UserWithOrganizationResponse",
        "type": "object"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "title": "Location",
            "type": "array"
          },
          "msg": {
            "title": "Message",
            "type": "string"
          },
          "type": {
            "title": "Error Type",
            "type": "string"
          }
        },
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "ValidationError",
        "type": "object"
      },
      "WorkflowUpdateBody": {
        "description": "Body for workflow update messages.",
        "properties": {
          "data": {
            "$ref": "#/components/schemas/WorkflowUpdateEventData"
          },
          "type": {
            "const": "workflow_update",
            "default": "workflow_update",
            "title": "Type",
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "title": "WorkflowUpdateBody",
        "type": "object"
      },
      "WorkflowUpdateEventData": {
        "description": "Data payload for workflow update events.",
        "properties": {
          "action": {
            "enum": [
              "add",
              "remove",
              "update"
            ],
            "title": "Action",
            "type": "string"
          },
          "data": {
            "$ref": "#/components/schemas/Task"
          },
          "sub_type": {
            "enum": [
              "node",
              "connection",
              "parameter"
            ],
            "title": "Sub Type",
            "type": "string"
          }
        },
        "required": [
          "sub_type",
          "action",
          "data"
        ],
        "title": "WorkflowUpdateEventData",
        "type": "object"
      },
      "app__api__admin__models__UserResponse": {
        "description": "API response model for User entity.\n\nRepresents a user account with profile information, organization membership,\nrole-based permissions, and authentication status. Users are scoped to a\nsingle organization.",
        "properties": {
          "created_at": {
            "description": "Timestamp when user was created. Format: ISO 8601 UTC (e.g., '2025-01-23T15:30:00Z').",
            "examples": [
              "2025-01-23T15:30:00Z"
            ],
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "email": {
            "description": "User's email address. Must be unique within organization. Used for login, authentication, and notifications. Synchronized with authentication system. Can be updated after user creation.",
            "examples": [
              "john.doe@example.com"
            ],
            "format": "email",
            "title": "Email",
            "type": "string"
          },
          "first_name": {
            "description": "User's first name. Used in UI displays, emails, and user identification. Can be updated after user creation.",
            "examples": [
              "John",
              "Jane"
            ],
            "title": "First Name",
            "type": "string"
          },
          "id": {
            "description": "Unique identifier for the user. Format: UUID v4. Synchronized with authentication system user ID.",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "last_name": {
            "description": "User's last name. Used in UI displays, emails, and user identification. Can be updated after user creation.",
            "examples": [
              "Doe",
              "Smith"
            ],
            "title": "Last Name",
            "type": "string"
          },
          "modified_by": {
            "description": "Identifier of the user or system that last modified this user. Can be user UUID or system identifier (e.g., 'system', 'admin'). Used for audit trail and change attribution.",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000",
              "system"
            ],
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "description": "UUID of the organization this user belongs to. Users are scoped to a single organization (no cross-org access). Organization must exist and determines user's data access scope.",
            "examples": [
              "550e8400-e29b-41d4-a716-446655440000"
            ],
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "role": {
            "description": "User's role within the organization. Determines permission level. Valid values: 'org_admin', 'backoffice', 'app_user', 'integration'. \n\nRole permissions:\n- 'org_admin': Full organization access and user management\n- 'backoffice': Super admin with platform-level access\n- 'app_user': Regular user who can create and manage own flows and executions\n- 'integration': Service account for integrations and automated workflows",
            "examples": [
              "org_admin",
              "app_user",
              "backoffice"
            ],
            "title": "Role",
            "type": "string"
          },
          "status": {
            "description": "User's current account status. Valid values: 'active', 'inactive'. \n\n'active': User can log in and access the system. \n'inactive': User cannot log in; account is disabled. Note: Even active users must accept email invitation to log in initially.",
            "examples": [
              "active",
              "inactive"
            ],
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "description": "Timestamp when user was last modified. Updated automatically on any field change. Format: ISO 8601 UTC (e.g., '2025-01-24T10:45:00Z'). Used for change tracking and audit logs.",
            "examples": [
              "2025-01-24T10:45:00Z"
            ],
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "first_name",
          "last_name",
          "email",
          "organization_id",
          "role",
          "status",
          "created_at",
          "updated_at",
          "modified_by"
        ],
        "title": "UserResponse",
        "type": "object"
      },
      "app__api__integrations__plugins__plugins_router__OauthAuthorizeRequest": {
        "properties": {
          "integration_name": {
            "title": "Integration Name",
            "type": "string"
          },
          "redirect_to": {
            "title": "Redirect To",
            "type": "string"
          }
        },
        "required": [
          "redirect_to",
          "integration_name"
        ],
        "title": "OauthAuthorizeRequest",
        "type": "object"
      },
      "app__api__integrations_new__integration_api_model__OauthAuthorizeRequest": {
        "properties": {
          "integration_name": {
            "title": "Integration Name",
            "type": "string"
          },
          "provider_name": {
            "title": "Provider Name",
            "type": "string"
          },
          "redirect_to": {
            "title": "Redirect To",
            "type": "string"
          }
        },
        "required": [
          "redirect_to",
          "integration_name",
          "provider_name"
        ],
        "title": "OauthAuthorizeRequest",
        "type": "object"
      },
      "app__api__user__user_api_model__UserResponse": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "title": "Created At",
            "type": "string"
          },
          "email": {
            "title": "Email",
            "type": "string"
          },
          "first_name": {
            "title": "First Name",
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "title": "Id",
            "type": "string"
          },
          "last_name": {
            "title": "Last Name",
            "type": "string"
          },
          "modified_by": {
            "title": "Modified By",
            "type": "string"
          },
          "organization_id": {
            "format": "uuid",
            "title": "Organization Id",
            "type": "string"
          },
          "role": {
            "title": "Role",
            "type": "string"
          },
          "status": {
            "title": "Status",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "title": "Updated At",
            "type": "string"
          }
        },
        "required": [
          "id",
          "created_at",
          "updated_at",
          "modified_by",
          "first_name",
          "last_name",
          "email",
          "role",
          "status",
          "organization_id"
        ],
        "title": "UserResponse",
        "type": "object"
      }
    },
    "securitySchemes": {
      "APIKeyAuth": {
        "description": "API key authentication. Include your API key in the X-API-Key header as: `X-API-Key YOUR_API_KEY`\n\nExample:\n```\nX-API-Key: saf_1234567890\n```",
        "in": "header",
        "name": "X-API-Key",
        "type": "apiKey"
      },
      "BearerAuth": {
        "bearerFormat": "JWT",
        "description": "JWT Bearer token authentication. Include your access token in the Authorization header as: `Bearer YOUR_ACCESS_TOKEN`\n\nExample:\n```\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\n```",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "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.",
    "title": "SuperAI Flow Platform",
    "version": "0.1.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/auth/anon-key": {
      "get": {
        "description": "Retrieve the anonymous authentication key required for client authentication.\n\nReturns the authentication key that client applications need to authenticate\nwith the authentication API at core.flows.super.ai. This key enables clients\nto perform password-based authentication and obtain JWT access tokens.\n\nContext:\n    - This key is required to make authentication requests to core.flows.super.ai\n    - The key is safe for use in client-side applications (browsers, mobile apps)\n    - Does not grant admin privileges or direct API access\n    - Only enables authentication operations (login, token refresh)\n    - Same key is used across all clients and organizations\n    - Key is long-lived and rarely rotated\n\nAuthentication Flow:\n    1. Client retrieves anonymous key from this endpoint\n    2. Client sends authentication request to core.flows.super.ai\n    3. Include anonymous key in 'apikey' header\n    4. Authentication service validates credentials and returns JWT tokens\n    5. Client uses JWT access token for subsequent API requests\n\nUse Cases:\n    - Web application initialization requiring user authentication\n    - Mobile app setup for authentication integration\n    - Testing authentication flow in development\n    - Building custom authentication UI\n    - Integrating third-party applications with authentication service\n\nSecurity Considerations:\n    - This key is public and safe for client-side applications\n    - Does not provide access to user data or administrative functions\n    - Only enables authentication API operations\n    - Users must still provide valid credentials (email/password)\n    - Rate limiting applied at authentication service level\n    - Key rotation handled by platform administrators\n\nIntegration Example:\n    After retrieving this key, use it to authenticate users:\n\n    Step 1: Get the anonymous key (this endpoint)\n    Step 2: Use the key to authenticate users at core.flows.super.ai\n    Step 3: Receive JWT tokens for API access\n\nRelated Endpoints:\n    - POST /auth/resend-invite - Resend invitation to existing users\n    - GET /profile/me - Retrieve authenticated user profile\n    - See authentication tag description for complete authentication guide\n\nError Handling:\n    - Returns 500 if key is not configured on server\n    - Indicates server misconfiguration requiring administrator attention\n    - Contact platform support if persistent errors occur",
        "operationId": "get_anon_key_api_auth_anon_key_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnonKeyResponse"
                }
              }
            },
            "description": "Authentication key successfully retrieved"
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "type_error": {
                    "summary": "Type validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "input": "not-a-uuid",
                            "loc": [
                              "path",
                              "flow_id"
                            ],
                            "msg": "Input should be a valid UUID",
                            "type": "uuid_parsing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "validation_error": {
                    "summary": "Validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "loc": [
                              "body",
                              "name"
                            ],
                            "msg": "Field required",
                            "type": "missing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Request validation failed"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Authentication key not configured on server"
          }
        },
        "summary": "Retrieve authentication API key",
        "tags": [
          "auth"
        ]
      }
    },
    "/api/auth/resend-invite": {
      "post": {
        "description": "Resend invitation email to an existing user account.\n\nTriggers a new invitation email when the original invitation has expired,\nwas not received, or the user needs another copy. The new invitation\nincludes a fresh authentication link and account setup instructions.\n\nContext:\n    - User must already exist in the system with pending or active status\n    - Email service managed by Supabase authentication backend\n    - Invitation link expires after configured timeout (typically 24-72 hours)\n    - Multiple invitations can be sent to the same user\n    - Each invitation invalidates previous invitation tokens\n    - Does not modify user account status or profile data\n\nBehavior:\n    1. Validates email format in request body\n    2. Logs invitation request for audit purposes\n    3. Calls Supabase admin service to generate and send invitation\n    4. Queues invitation email for delivery via external email service\n    5. Returns success response immediately (email delivery is async)\n    6. Raises 500 error if authentication service is unavailable\n\nUse Cases:\n    - User reports not receiving original invitation email\n    - Invitation link has expired (typically after 24-72 hours)\n    - User accidentally deleted invitation email\n    - Organization admin needs to re-invite inactive user\n    - Testing user onboarding flow in development\n\nEmail Delivery:\n    - Invitation sent asynchronously by Supabase auth service\n    - success=true indicates request was accepted, not that email was delivered\n    - Check email service logs for actual delivery confirmation\n    - Email may be delayed due to rate limiting or provider issues\n    - User should check spam/junk folder if email not received\n\nSecurity Considerations:\n    - Each invitation generates unique time-limited authentication token\n    - Previous invitation tokens are invalidated when new one is sent\n    - Email address must match existing user account (no arbitrary emails)\n    - Rate limiting recommended to prevent invitation spam\n\nRelated Endpoints:\n    - POST /admin/organizations/{org_id}/users - Create new user with initial invite\n    - GET /profile/me - User profile after successful authentication",
        "operationId": "resend_invite_api_auth_resend_invite_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResendInviteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResendInviteResponse"
                }
              }
            },
            "description": "Invitation email successfully queued for delivery"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "User with specified email address does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "type_error": {
                    "summary": "Type validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "input": "not-a-uuid",
                            "loc": [
                              "path",
                              "flow_id"
                            ],
                            "msg": "Input should be a valid UUID",
                            "type": "uuid_parsing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "validation_error": {
                    "summary": "Validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "loc": [
                              "body",
                              "name"
                            ],
                            "msg": "Field required",
                            "type": "missing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Request validation failed"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Authentication service unavailable or email delivery failed"
          }
        },
        "summary": "Resend user invitation email",
        "tags": [
          "auth"
        ]
      }
    },
    "/api/files/download": {
      "get": {
        "description": "Download a file by resolving its gs:// storage URI.\n\nThis endpoint provides a convenient way to download files directly using curl\nor wget. By default, it returns a 302 redirect to a pre-signed download URL.\n\n**Quick download with curl:**\n```\ncurl -L -H \"X-API-Key: $KEY\" \"https://flows.super.ai/api/files/download?uri=gs://...\" -o file.pdf\n```\n\nThe `-L` flag tells curl to follow the redirect automatically.\n\n**Note:** The URI will appear in server access logs. For sensitive files,\nuse the POST `/api/files/resolve` endpoint instead.",
        "operationId": "download_file_api_files_download_get",
        "parameters": [
          {
            "description": "The gs:// storage URI to download. Pass the exact URI from your task output (URL-encoded for special characters).",
            "examples": {
              "document": {
                "summary": "Document file",
                "value": "gs://superai-file-upload-prod-eu/flows/255a17d0-5c21-47d9-8e0b-a08b48436f0a/documents/f8230da2-4136-4ffb-acfe-db9318970ea2"
              }
            },
            "in": "query",
            "name": "uri",
            "required": true,
            "schema": {
              "description": "The gs:// storage URI to download. Pass the exact URI from your task output (URL-encoded for special characters).",
              "title": "Uri",
              "type": "string"
            }
          },
          {
            "description": "If true (default), returns 302 redirect to download URL. If false, returns JSON with the download URL for programmatic use.",
            "in": "query",
            "name": "redirect",
            "required": false,
            "schema": {
              "default": true,
              "description": "If true (default), returns 302 redirect to download URL. If false, returns JSON with the download URL for programmatic use.",
              "title": "Redirect",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResolveUriResponse"
                }
              }
            },
            "description": "JSON response with download URL (when redirect=false)"
          },
          "302": {
            "description": "Redirect to pre-signed download URL. Follow this redirect to download the file.",
            "headers": {
              "Location": {
                "description": "Pre-signed download URL (valid for 1 hour)",
                "schema": {
                  "format": "uri",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_format": {
                    "summary": "Malformed URI",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Invalid URI format: missing bucket or path"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "invalid_scheme": {
                    "summary": "Invalid URI scheme",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Invalid URI scheme. Must start with 'gs://'"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "path_traversal": {
                    "summary": "Path traversal attempt (contains ../ or similar)",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Invalid path"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid URI format, unsupported scheme, or path traversal attempt"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_bucket": {
                    "summary": "Invalid storage location",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "Access denied: invalid storage location"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "wrong_organization": {
                    "summary": "File belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "Access denied: you do not have access to this file"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Access denied - user does not have permission to access this file"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "file_not_found": {
                    "summary": "File deleted or moved from storage",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "File not found in storage. The file may have been deleted or moved."
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "flow_not_found": {
                    "summary": "Flow does not exist or user lacks access",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The flow or file does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Download file by URI (with redirect)",
        "tags": [
          "files"
        ]
      }
    },
    "/api/files/resolve": {
      "post": {
        "description": "Resolve a gs:// storage URI to a temporary pre-signed download URL.\n\nThis is the **recommended endpoint** for downloading files from task outputs.\nSimply pass the `gs://` URI exactly as you received it\u2014no parsing required.\n\nThe returned `download_url` is a pre-signed URL valid for **1 hour** that can\nbe used to download the file directly without additional authentication.\n\n**Why use POST instead of GET?**\n\nUsing POST keeps the URI out of server access logs and browser history,\nwhich is better for security when dealing with sensitive files.",
        "operationId": "resolve_uri_api_files_resolve_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResolveUriRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ResolveUriResponse"
                }
              }
            },
            "description": "URI resolved successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_format": {
                    "summary": "Malformed URI",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Invalid URI format: missing bucket or path"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "invalid_scheme": {
                    "summary": "Invalid URI scheme",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Invalid URI scheme. Must start with 'gs://'"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "path_traversal": {
                    "summary": "Path traversal attempt (contains ../ or similar)",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Invalid path"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid URI format, unsupported scheme, or path traversal attempt"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_bucket": {
                    "summary": "Invalid storage location",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "Access denied: invalid storage location"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "wrong_organization": {
                    "summary": "File belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "Access denied: you do not have access to this file"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Access denied - user does not have permission to access this file"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "file_not_found": {
                    "summary": "File deleted or moved from storage",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "File not found in storage. The file may have been deleted or moved."
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "flow_not_found": {
                    "summary": "Flow does not exist or user lacks access",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "The flow or file does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Resolve storage URI to download URL",
        "tags": [
          "files"
        ]
      }
    },
    "/api/flow-executions": {
      "get": {
        "description": "List flow executions with filtering, sorting, and pagination.\n\nRetrieve a paginated list of flow executions for a specific flow with support\nfor filtering by status, tags, and date ranges. Results can be sorted by\ncreation or update time and include optional run number calculation.\n\nContext:\n    - Returns executions for a single flow (specified by flow_id)\n    - Excludes soft-deleted executions from results\n    - Supports multiple filtering dimensions for flexible queries\n    - Pagination uses offset-based approach (page/page_size)\n    - Run numbers calculated on-demand (performance impact)\n\nFiltering Logic:\n    - Status filter: Returns executions containing tasks with ANY of specified statuses\n    - Tag filter: Returns executions containing tasks with ANY of specified tags\n    - Multiple filters combined with AND logic\n    - Empty filters return all executions\n\nPagination:\n    - Offset-based: page=1, page_size=10 returns first 10 results\n    - Default: page=1, page_size=10\n    - Maximum page_size: 1000 results\n    - Maximum page: 10,000 (to prevent excessive database load)\n    - Use start_from_execution_id for cursor-like pagination\n\nRun Numbers:\n    - include_run_number=true: Calculates sequential number (1, 2, 3...)\n    - Based on creation time for the flow\n    - Includes deleted executions in count (may have gaps)\n    - Performance impact: Additional database query per execution\n    - Recommended: Use only when displaying in UI\n\nSorting:\n    - sort_field: 'created_at' (when execution was created) or\n                  'updated_at' (when execution was last modified)\n    - sort_direction: 'asc' (oldest first) or 'desc' (newest first)\n    - Default: sort by created_at desc (most recently created first)\n\nPerformance Considerations:\n    - Without run_number: ~50ms for 100 results\n    - With run_number: ~200ms for 100 results (N+1 query issue)\n    - Consider caching for frequently accessed pages\n    - Large page_size values increase response time linearly\n\nUse Cases:\n    - Display execution history in UI dashboard\n    - Monitor recent execution failures (filter by status='failed')\n    - Find executions by business context (filter by tags)\n    - Export execution audit trail\n    - Identify oldest pending executions (sort by created_at asc)\n\nExample Queries:\n    - Recent failures: ?flow_id=xxx&status=failed&sort_field=created_at&sort_direction=desc&page_size=20\n    - Tagged executions: ?flow_id=xxx&tags=priority:high&tags=customer:acme\n    - Paginated view: ?flow_id=xxx&page=2&page_size=50\n    - With run numbers: ?flow_id=xxx&include_run_number=true\n\nRelated Endpoints:\n    - GET /flow-executions/{id} - Get single execution details\n    - POST /flow-executions - Create new execution\n    - GET /flows/{id} - Get flow definition details",
        "operationId": "list_flow_executions_api_flow_executions_get",
        "parameters": [
          {
            "description": "UUID of the flow to list executions for. Required parameter.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "query",
            "name": "flow_id",
            "required": true,
            "schema": {
              "description": "UUID of the flow to list executions for. Required parameter.",
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "description": "Field to sort results by. Valid values: 'created_at', 'updated_at'. Defaults to 'created_at' for most recently modified first.",
            "example": "created_at",
            "in": "query",
            "name": "sort_field",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "pattern": "^(created_at|updated_at)$",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Field to sort results by. Valid values: 'created_at', 'updated_at'. Defaults to 'created_at' for most recently modified first.",
              "title": "Sort Field"
            }
          },
          {
            "description": "Sort order direction. Valid values: 'asc' (ascending), 'desc' (descending). Defaults to 'desc' for newest first.",
            "example": "desc",
            "in": "query",
            "name": "sort_direction",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "pattern": "^(asc|desc)$",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Sort order direction. Valid values: 'asc' (ascending), 'desc' (descending). Defaults to 'desc' for newest first.",
              "title": "Sort Direction"
            }
          },
          {
            "description": "Filter by execution status. Can specify multiple values. Valid values: 'queued', 'running', 'in_progress', 'completed', 'failed', 'stale'. Returns executions containing tasks with ANY of the specified statuses. Example: ?status=failed&status=running",
            "example": [
              "running",
              "completed"
            ],
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by execution status. Can specify multiple values. Valid values: 'queued', 'running', 'in_progress', 'completed', 'failed', 'stale'. Returns executions containing tasks with ANY of the specified statuses. Example: ?status=failed&status=running",
              "title": "Status"
            }
          },
          {
            "description": "Filter by task tags. Can specify multiple values. Returns executions containing tasks with ANY of the specified tags. Tags use key:value format. Example: ?tags=priority:high&tags=env:prod",
            "example": [
              "priority:high",
              "department:finance"
            ],
            "in": "query",
            "name": "tags",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter by task tags. Can specify multiple values. Returns executions containing tasks with ANY of the specified tags. Tags use key:value format. Example: ?tags=priority:high&tags=env:prod",
              "title": "Tags"
            }
          },
          {
            "description": "Calculate sequential run number for each execution. Run numbers start at 1 and increment based on creation time. Warning: Adds performance overhead (~150ms per 100 executions). Recommended only for UI display purposes.",
            "example": false,
            "in": "query",
            "name": "include_run_number",
            "required": false,
            "schema": {
              "default": false,
              "description": "Calculate sequential run number for each execution. Run numbers start at 1 and increment based on creation time. Warning: Adds performance overhead (~150ms per 100 executions). Recommended only for UI display purposes.",
              "title": "Include Run Number",
              "type": "boolean"
            }
          },
          {
            "description": "Page number for pagination (1-indexed). Minimum: 1, Maximum: 10,000. Works with page_size to implement offset-based pagination.",
            "example": 1,
            "in": "query",
            "name": "page",
            "required": false,
            "schema": {
              "default": 1,
              "description": "Page number for pagination (1-indexed). Minimum: 1, Maximum: 10,000. Works with page_size to implement offset-based pagination.",
              "maximum": 10000,
              "minimum": 1,
              "title": "Page",
              "type": "integer"
            }
          },
          {
            "description": "Number of results to return per page. Minimum: 1, Maximum: 1000. Larger values increase response time. Recommended: 10-100.",
            "example": 10,
            "in": "query",
            "name": "page_size",
            "required": false,
            "schema": {
              "default": 10,
              "description": "Number of results to return per page. Minimum: 1, Maximum: 1000. Larger values increase response time. Recommended: 10-100.",
              "maximum": 1000,
              "minimum": 1,
              "title": "Page Size",
              "type": "integer"
            }
          },
          {
            "description": "Start listing after this execution ID. Provides cursor-like pagination. When combined with sort parameters, returns results after the specified execution. Useful for infinite scroll or keyset pagination patterns.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "query",
            "name": "start_from_execution_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Start listing after this execution ID. Provides cursor-like pagination. When combined with sort parameters, returns results after the specified execution. Useful for infinite scroll or keyset pagination patterns.",
              "title": "Start From Execution Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/FlowExecutionResponseWithRunNumber"
                  },
                  "title": "Response List Flow Executions Api Flow Executions Get",
                  "type": "array"
                }
              }
            },
            "description": "List of flow executions successfully retrieved"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid query parameters"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks permission to view this flow's executions"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "type_error": {
                    "summary": "Type validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "input": "not-a-uuid",
                            "loc": [
                              "path",
                              "flow_id"
                            ],
                            "msg": "Input should be a valid UUID",
                            "type": "uuid_parsing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "validation_error": {
                    "summary": "Validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "loc": [
                              "body",
                              "name"
                            ],
                            "msg": "Field required",
                            "type": "missing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Request validation failed"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List flow executions with filtering and pagination",
        "tags": [
          "flow-executions"
        ]
      },
      "post": {
        "description": "Create a new flow execution and start workflow processing.\n\nThis endpoint creates a flow execution record and immediately starts the associated\nworkflow processing. The execution is created with status 'running' and will be\nprocessed asynchronously by the execution engine.\n\nContext:\n    - Flow executions represent runtime instances of flow definitions\n    - Each execution is isolated and maintains its own state\n    - Input data must conform to the flow's input schema\n    - Executions are scoped to the user's organization\n    - WebSocket notifications are sent on creation for real-time updates\n\nExecution Flow:\n    1. Validates flow exists and user has access\n    2. Creates execution record in database\n    3. Starts workflow processing asynchronously\n    4. Sends WebSocket notification to connected clients\n    5. Returns immediately (does not wait for completion)\n\nPerformance Notes:\n    - Response time: < 200ms (workflow starts asynchronously)\n    - Does not block on workflow completion\n    - WebSocket notifications sent in background task\n\nUse Cases:\n    - Trigger flow execution from UI dashboard\n    - Automated flow execution via API integration\n    - Batch processing of multiple documents\n    - Event-driven workflow automation\n\nRelated Endpoints:\n    - GET /flow-executions/{id} - Check execution status\n    - GET /flow-executions - List all executions for a flow\n    - POST /flow-executions/{id}/execute - Re-execute failed execution",
        "operationId": "create_flow_execution_api_flow_executions_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FlowExecutionCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowExecutionResponse"
                }
              }
            },
            "description": "Flow execution created and started successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid input data or missing required fields"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks permission to execute this flow"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create and start a flow execution",
        "tags": [
          "flow-executions"
        ]
      }
    },
    "/api/flow-executions/{flow_execution_id}": {
      "delete": {
        "description": "Soft delete a flow execution by marking it as deleted.\n\nThis endpoint performs a soft delete by setting the execution status to 'deleted'.\nThe execution record remains in the database but is excluded from list operations\nand cannot be retrieved through standard endpoints.\n\nContext:\n    - Soft delete preserves audit trail and historical data\n    - Does NOT stop running workflows (use cancel endpoint for that)\n    - Deleted executions do not appear in GET /flow-executions list\n    - Operation is idempotent - deleting already deleted execution succeeds\n    - Deletion is permanent - no undelete functionality exists\n\nBehavior:\n    - Updates execution status to 'deleted' in database\n    - Maintains all execution data for audit purposes\n    - Removes from user-facing list queries\n    - Does not affect related task executions or outputs\n    - Triggers WebSocket notification for status change\n\nUse Cases:\n    - Remove test executions from production environment\n    - Clean up failed executions no longer needed\n    - Archive old executions while preserving data\n\nImportant Notes:\n    - To stop a RUNNING workflow, use cancel endpoint (not yet implemented)\n    - Soft delete does not free up workflow resources\n    - Consider hard delete for GDPR compliance (requires database migration)\n\nRelated Endpoints:\n    - GET /flow-executions - List excludes deleted executions\n    - POST /flow-executions - Create new execution",
        "operationId": "delete_flow_execution_api_flow_executions__flow_execution_id__delete",
        "parameters": [
          {
            "description": "UUID of the flow execution to soft delete. Must be owned by your organization.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "flow_execution_id",
            "required": true,
            "schema": {
              "description": "UUID of the flow execution to soft delete. Must be owned by your organization.",
              "format": "uuid",
              "title": "Flow Execution Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Flow execution successfully soft deleted"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks permission to delete this execution"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Soft delete a flow execution",
        "tags": [
          "flow-executions"
        ]
      },
      "get": {
        "description": "Retrieve detailed information for a specific flow execution.\n\nFetch a single flow execution by its unique identifier. Returns execution\nmetadata including status, input data, timestamps, and optionally the\nsequential run number within its flow.\n\nContext:\n    - Retrieves single execution regardless of status (except deleted)\n    - Soft-deleted executions return 404 Not Found\n    - Includes full input data as provided at creation\n    - Run number calculated on-demand if requested\n    - Useful for monitoring execution progress\n\nRun Number Calculation:\n    - When include_run_number=true, calculates sequential position\n    - Based on creation timestamp among all executions for this flow\n    - Includes deleted executions (may have gaps in visible numbers)\n    - Performance: Adds ~10-20ms per request\n    - Useful for displaying \"Run #42\" in UI\n\nUse Cases:\n    - Check status of long-running execution\n    - Retrieve input data for debugging\n    - Display execution details in UI\n    - Audit execution history with run numbers\n    - Poll for execution completion\n\nPerformance Notes:\n    - Without run_number: ~10ms average response time\n    - With run_number: ~25ms average response time\n    - Highly cacheable (status changes infrequently)\n\nRelated Endpoints:\n    - GET /flow-executions - List all executions for a flow\n    - POST /flow-executions/{id}/execute - Re-execute this execution\n    - GET /task-executions?flow_execution_id={id} - Get task details\n    - DELETE /flow-executions/{id} - Delete this execution",
        "operationId": "get_flow_execution_api_flow_executions__flow_execution_id__get",
        "parameters": [
          {
            "description": "UUID of the flow execution to retrieve. Must exist and not be soft-deleted.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "flow_execution_id",
            "required": true,
            "schema": {
              "description": "UUID of the flow execution to retrieve. Must exist and not be soft-deleted.",
              "format": "uuid",
              "title": "Flow Execution Id",
              "type": "string"
            }
          },
          {
            "description": "Calculate and include sequential run number. Adds ~10-20ms overhead. Recommended for UI display only.",
            "example": false,
            "in": "query",
            "name": "include_run_number",
            "required": false,
            "schema": {
              "default": false,
              "description": "Calculate and include sequential run number. Adds ~10-20ms overhead. Recommended for UI display only.",
              "title": "Include Run Number",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowExecutionResponseWithRunNumber"
                }
              }
            },
            "description": "Flow execution successfully retrieved"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid execution ID format"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks permission to view this execution"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Retrieve a specific flow execution",
        "tags": [
          "flow-executions"
        ]
      }
    },
    "/api/flow-executions/{flow_execution_id}/execute": {
      "post": {
        "description": "Re-execute a flow execution, optionally skipping cached results.\n\nThis endpoint triggers re-execution of an existing flow execution. It can\nselectively re-run failed tasks or re-run the entire flow from scratch.\nUseful for retrying failed executions or refreshing stale data.\n\nContext:\n    - Re-executes workflows that have completed or failed\n    - Can reuse successful task results (cached execution)\n    - Useful for handling transient failures\n    - Updates flow to latest version if changed since original execution\n    - Creates new workflow instance with same execution ID\n\nExecution Modes:\n    1. Full Re-execution (only_stale=false, default):\n       - Starts workflow from beginning\n       - All tasks execute regardless of previous state\n       - Previous results are discarded\n       - Use for: Complete retry after fixing flow definition\n\n    2. Stale-Only Re-execution (only_stale=true):\n       - Only re-runs tasks marked as 'stale'\n       - Reuses results from successful tasks\n       - Faster for partial failures\n       - Use for: Refreshing outdated data without full re-run\n\nBehavior:\n    - Terminates existing workflow if still running\n    - Updates flow_version to latest version\n    - Maintains same execution ID for traceability\n    - Status transitions: any \u2192 running\n    - Does not create new execution record\n\nPerformance Notes:\n    - Response time: < 200ms (workflow starts asynchronously)\n    - Stale-only mode significantly faster for large flows\n    - Full re-execution recalculates all task outputs\n\nUse Cases:\n    - Retry failed execution after fixing flow definition\n    - Refresh data after external system updates\n    - Resume execution after transient service outage\n    - Update execution to use latest flow version\n\nRelated Endpoints:\n    - GET /flow-executions/{id} - Check re-execution status\n    - POST /flow-executions - Create new execution instead of re-running",
        "operationId": "execute_flow_api_flow_executions__flow_execution_id__execute_post",
        "parameters": [
          {
            "description": "UUID of the flow execution to re-execute. Must be an existing execution owned by your organization.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "flow_execution_id",
            "required": true,
            "schema": {
              "description": "UUID of the flow execution to re-execute. Must be an existing execution owned by your organization.",
              "format": "uuid",
              "title": "Flow Execution Id",
              "type": "string"
            }
          },
          {
            "description": "If true, only re-executes tasks marked as 'stale'. If false (default), re-executes entire flow from beginning. Stale-only mode is faster for flows with many successful tasks.",
            "example": false,
            "in": "query",
            "name": "only_stale",
            "required": false,
            "schema": {
              "default": false,
              "description": "If true, only re-executes tasks marked as 'stale'. If false (default), re-executes entire flow from beginning. Stale-only mode is faster for flows with many successful tasks.",
              "title": "Only Stale",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Flow execution re-started successfully"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks permission to execute this flow"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Conflict - Workflow is currently running and cannot be terminated"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Re-execute a flow execution",
        "tags": [
          "flow-executions"
        ]
      }
    },
    "/api/flow-executions/{flow_execution_id}/status": {
      "patch": {
        "description": "Patch the status of a flow execution.",
        "operationId": "patch_flow_execution_status_api_flow_executions__flow_execution_id__status_patch",
        "parameters": [
          {
            "in": "path",
            "name": "flow_execution_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Execution Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "status",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ExecutionStatus"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowExecutionResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Patch Flow Execution Status",
        "tags": [
          "flow-executions"
        ]
      }
    },
    "/api/flow-executions/{flow_execution_id}/task-status": {
      "post": {
        "description": "Add task status updates to a flow execution (Internal API).\n\nThis endpoint is used by system workers to report task execution status changes.\nMultiple task statuses can be added in a single request for batch efficiency.\nStatus updates trigger state transitions and WebSocket notifications.\n\n\u26a0\ufe0f  Internal API: This endpoint is designed for internal system communication.\n   Direct customer usage is not recommended. Use GET /task-executions instead.\n\nContext:\n    - Called by system workers during task execution\n    - Updates task status records in bulk for performance\n    - Triggers task output state calculations\n    - Sends WebSocket notifications asynchronously\n    - Worker receives immediate response without blocking on notifications\n\nBehavior:\n    1. Validates flow execution exists and is accessible\n    2. Creates status records for each task in batch\n    3. Updates related task output states in parallel\n    4. Sends WebSocket notifications in background task\n    5. Returns immediately to worker for low latency\n\nPerformance Optimizations:\n    - Batch inserts for multiple status updates (~50ms for 10 tasks)\n    - WebSocket notifications processed asynchronously\n    - Task output state updates use batch operations\n    - Response returns before notification delivery completes\n\nUse Cases:\n    - System workers reporting task start/completion\n    - Bulk status updates during execution\n    - Real-time execution monitoring via WebSocket\n\nImportant Notes:\n    - This endpoint does NOT retrieve task status (use GET /task-executions)\n    - Requires service-level authentication token\n    - Not intended for direct customer API integration\n    - WebSocket notifications may arrive after HTTP response\n\nBusiness Logic:\n    - Task output states recalculated based on new statuses\n    - Multiple status updates for same task create history\n    - Execution-level status not automatically updated\n    - Status transitions not validated (allows any status value)\n\nRelated Internal Endpoints:\n    - POST /flow-executions - Creates parent execution\n    - GET /task-executions - Retrieves task execution details\n    - WebSocket /ws/flows/{flow_id} - Receives status notifications",
        "operationId": "add_flow_task_statuses_api_flow_executions__flow_execution_id__task_status_post",
        "parameters": [
          {
            "description": "UUID of the flow execution receiving task status updates. Must be an active (non-deleted) execution.",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "flow_execution_id",
            "required": true,
            "schema": {
              "description": "UUID of the flow execution receiving task status updates. Must be an active (non-deleted) execution.",
              "format": "uuid",
              "title": "Flow Execution Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddTaskStatusRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/FlowTaskStatusAPI"
                  },
                  "title": "Response Add Flow Task Statuses Api Flow Executions  Flow Execution Id  Task Status Post",
                  "type": "array"
                }
              }
            },
            "description": "Task status updates successfully recorded"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid request body or task names"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Requires service-level authentication token"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Add task status updates (Internal API)",
        "tags": [
          "flow-executions"
        ]
      }
    },
    "/api/flows": {
      "get": {
        "description": "List all flows accessible to the authenticated user.\n\nReturns all flows within the user's organization, ordered by creation date (newest first).\nEach flow includes its latest version by default.\n\n## Expansion Parameters\nUse query parameters to include additional computed fields. See FlowResponse model\ndocumentation for details on available expansion parameters and their performance impact.\n\n## Common Use Cases\n- Display flows in dashboard/listing page\n- Populate flow selector dropdown\n- Validate flow definitions in batch",
        "operationId": "list_flows_api_flows_get",
        "parameters": [
          {
            "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
            "in": "query",
            "name": "include_ordered_task_names",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
              "title": "Include Ordered Task Names",
              "type": "boolean"
            }
          },
          {
            "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
            "in": "query",
            "name": "include_validation_errors",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
              "title": "Include Validation Errors",
              "type": "boolean"
            }
          },
          {
            "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
            "in": "query",
            "name": "include_dynamic_data",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
              "title": "Include Dynamic Data",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
            "in": "query",
            "name": "include_output_schemas",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
              "title": "Include Output Schemas",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/FlowResponse"
                  },
                  "title": "Response List Flows Api Flows Get",
                  "type": "array"
                }
              }
            },
            "description": "List of flows successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List all flows",
        "tags": [
          "flows"
        ]
      },
      "post": {
        "description": "Create a new flow in draft status.\n\nCreates a flow definition that can be executed via the flow executions API.\nNew flows are assigned version 1 and status 'draft', allowing iterative development\nbefore marking as 'published' for production use.\n\n## Flow Lifecycle\n1. **Draft**: Newly created flows start here. Editable and testable.\n2. **Published**: Ready for production. Can be executed by end users.\n\n## DSL Validation\nThe flow definition is validated against the DSL schema during creation.\nIf validation fails, a 400 error is returned with detailed error messages\nin the `details` array.\n\n## Common Validation Errors\n- Missing required fields (tasks, edges)\n- Invalid task executor names\n- Circular dependencies in task graph\n- Invalid parameter types for task executors",
        "operationId": "create_flow_api_flows_post",
        "parameters": [
          {
            "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
            "in": "query",
            "name": "include_ordered_task_names",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
              "title": "Include Ordered Task Names",
              "type": "boolean"
            }
          },
          {
            "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
            "in": "query",
            "name": "include_validation_errors",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
              "title": "Include Validation Errors",
              "type": "boolean"
            }
          },
          {
            "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
            "in": "query",
            "name": "include_dynamic_data",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
              "title": "Include Dynamic Data",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
            "in": "query",
            "name": "include_output_schemas",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
              "title": "Include Output Schemas",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FlowCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowResponse"
                }
              }
            },
            "description": "Flow created successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_dsl": {
                    "summary": "Invalid DSL input",
                    "value": {
                      "error": {
                        "code": "invalid_dsl_input",
                        "details": [
                          "tasks.1.task_executor_name: Invalid task executor 'invalid_executor'",
                          "edges.0.target: Target task 'unknown_task' does not exist"
                        ],
                        "message": "Invalid DSL input"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "missing_org": {
                    "summary": "Missing organization ID",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Organization ID is required"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid flow definition or validation errors"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "409": {
            "content": {
              "application/json": {
                "examples": {
                  "duplicate_name": {
                    "summary": "Name already in use",
                    "value": {
                      "error": {
                        "code": "conflict",
                        "message": "A flow with this name already exists"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "duplicate_resource": {
                    "summary": "Resource already exists",
                    "value": {
                      "error": {
                        "code": "conflict",
                        "message": "A resource with this identifier already exists"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Conflict - The resource already exists or conflicts with existing state"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create a new flow",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/download-url": {
      "post": {
        "description": "Generate pre-signed URL for downloading a flow file.\n\nCreates a temporary download URL for a previously uploaded file.\nURLs are valid for 1 hour and can be shared safely without exposing\nstorage credentials.\n\n## Download Process\n1. Get file_key from file listing or upload response\n2. Call this endpoint with the file_key\n3. Use returned URL in browser or GET request to download file",
        "operationId": "generate_download_url_api_flows_download_url_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GeneratePresignedUrlForDownload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Generate Download Url Api Flows Download Url Post",
                  "type": "object"
                }
              }
            },
            "description": "Pre-signed download URL successfully generated"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Generate file download URL",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}": {
      "delete": {
        "description": "Soft delete a flow.\n\nMarks a flow as deleted without permanently removing it from the database.\nDeleted flows are hidden from listings but can be recovered if needed.\n\n## Behavior\n- Flow is marked with `deleted=true` flag\n- Flow no longer appears in list/get operations\n- All versions of the flow are marked as deleted\n- Can be recovered by support team if needed\n\n## Important Notes\n- This is a soft delete, not a permanent deletion\n- Associated executions and files are NOT deleted\n- Deleted flows cannot be undeleted via API (contact support)",
        "operationId": "delete_flow_api_flows__flow_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Flow successfully deleted (soft delete)"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User doesn't have permission to delete this flow"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Delete a flow",
        "tags": [
          "flows"
        ]
      },
      "get": {
        "description": "Retrieve a specific flow by ID.\n\nReturns the latest version of a flow with its complete definition, metadata, and\noptional computed fields. This endpoint is typically used when displaying flow\ndetails or preparing to execute a flow.\n\n## Behavior\n- Always returns the latest version unless a specific version is requested via\n  `/flows/{flow_id}/versions/{version}`\n- Use expansion parameters to include computed fields (see FlowResponse model docs)\n\n## Use Cases\n- Display flow details in your application UI\n- Retrieve flow definition before execution\n- Check flow validation status and errors",
        "operationId": "get_flow_api_flows__flow_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
            "in": "query",
            "name": "include_ordered_task_names",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
              "title": "Include Ordered Task Names",
              "type": "boolean"
            }
          },
          {
            "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
            "in": "query",
            "name": "include_validation_errors",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
              "title": "Include Validation Errors",
              "type": "boolean"
            }
          },
          {
            "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
            "in": "query",
            "name": "include_dynamic_data",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
              "title": "Include Dynamic Data",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
            "in": "query",
            "name": "include_output_schemas",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
              "title": "Include Output Schemas",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowResponse"
                }
              }
            },
            "description": "Flow successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "User doesn't have access to this flow"
                  },
                  "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User doesn't have access to this flow (wrong organization)"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Retrieve a flow by ID",
        "tags": [
          "flows"
        ]
      },
      "patch": {
        "description": "Partially update flow properties.\n\nUpdate specific fields of a flow without replacing the entire object.\nOnly provided fields will be modified; others remain unchanged.\n\n## Updateable Fields\n- `display_name`: Human-readable flow name\n- `description`: Flow description\n- `visibility`: Access control setting\n- `settings`: Flow-level configuration\n- `status`: Lifecycle status (draft or published)\n\n## Status Transitions\nCurrently the API allows any status transition. The valid status values are:\n- `draft`: Flow is in development and can be edited\n- `published`: Flow is ready for production use",
        "operationId": "patch_flow_api_flows__flow_id__patch",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
            "in": "query",
            "name": "include_ordered_task_names",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
              "title": "Include Ordered Task Names",
              "type": "boolean"
            }
          },
          {
            "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
            "in": "query",
            "name": "include_validation_errors",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
              "title": "Include Validation Errors",
              "type": "boolean"
            }
          },
          {
            "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
            "in": "query",
            "name": "include_dynamic_data",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
              "title": "Include Dynamic Data",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
            "in": "query",
            "name": "include_output_schemas",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
              "title": "Include Output Schemas",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchFlowRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowResponse"
                }
              }
            },
            "description": "Flow successfully updated"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid field values or illegal status transition"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Partially update a flow",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}/definition": {
      "put": {
        "description": "Update the complete definition of a flow.\n\nReplaces the entire flow definition with a new one. This operation is only\nallowed for flows in 'draft' status. Creates a new version of the flow.\n\n## Restrictions\n- Only flows with status 'draft' can be updated\n- Published flows cannot be modified\n- A new version is created with each update\n\n## Validation\n- New definition is validated before applying\n- If validation fails, the original definition remains unchanged\n- Use `include_validation_errors=true` to see validation details",
        "operationId": "update_flow_definition_api_flows__flow_id__definition_put",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
            "in": "query",
            "name": "include_ordered_task_names",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
              "title": "Include Ordered Task Names",
              "type": "boolean"
            }
          },
          {
            "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
            "in": "query",
            "name": "include_validation_errors",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
              "title": "Include Validation Errors",
              "type": "boolean"
            }
          },
          {
            "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
            "in": "query",
            "name": "include_dynamic_data",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
              "title": "Include Dynamic Data",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
            "in": "query",
            "name": "include_output_schemas",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
              "title": "Include Output Schemas",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FlowDefinitionUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowResponse"
                }
              }
            },
            "description": "Flow definition successfully updated"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid definition or flow not in draft status"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User doesn't have permission to update this flow"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Update flow definition",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}/files": {
      "get": {
        "description": "List all files associated with a flow.\n\nReturns metadata for all files that have been uploaded to this flow,\nincluding original filenames, sizes, and custom metadata.\n\n## Use Cases\n- Display uploaded files in UI\n- Verify file uploads completed successfully\n- Retrieve file keys for download URL generation",
        "operationId": "list_flow_files_api_flows__flow_id__files_get",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "title": "Response List Flow Files Api Flows  Flow Id  Files Get",
                  "type": "array"
                }
              }
            },
            "description": "List of files with metadata"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List flow files",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}/invitations": {
      "delete": {
        "description": "Remove invitations for specific users from a flow.\n\nThis endpoint allows admins to revoke access for reviewer users to specific flows.\nOnce removed, users will no longer be able to access the flow and its executions\nthrough the RLS policies enforced at the database level.\n\n## Permissions\n- Only org_admin role can remove invitations\n- Users must belong to the same organization as the flow\n\n## Behavior\n- Removes invitations for all specified user IDs\n- Non-existent invitations are silently ignored\n- All deletions are performed in a single transaction\n\n## Use Cases\n- Revoke reviewer access from specific flows\n- Manage flow-level permissions for review workflows\n- Remove team members who no longer need access",
        "operationId": "delete_flow_invitations_api_flows__flow_id__invitations_delete",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FlowInvitationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Invitations successfully removed"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid user IDs or empty list"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User doesn't have permission to remove invitations"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Remove user invitations from a flow",
        "tags": [
          "flows"
        ]
      },
      "get": {
        "description": "List all invitations for a specific flow.\n\nReturns all users who have been invited to access this flow.\n\n## Permissions\n- Only org_admin role can view invitations\n- User must belong to the same organization as the flow",
        "operationId": "list_flow_invitations_api_flows__flow_id__invitations_get",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/FlowInvitationResponse"
                  },
                  "title": "Response List Flow Invitations Api Flows  Flow Id  Invitations Get",
                  "type": "array"
                }
              }
            },
            "description": "List of invitations successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User doesn't have permission to view invitations"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List flow invitations",
        "tags": [
          "flows"
        ]
      },
      "put": {
        "description": "Upsert invitations for multiple users to access a flow.\n\nThis endpoint allows admins to invite reviewer users to specific flows.\nOnly users with the **reviewer role** will be invited - other users are automatically filtered out.\nInvited users will be able to access the flow and its executions through\nthe RLS policies enforced at the database level.\n\n## Permissions\n- Only org_admin role can create/update invitations\n- Users must belong to the same organization as the flow\n\n## Behavior\n- **Upsert semantics**: Creates new invitations or updates existing ones\n- **Role filtering**: Only users with reviewer role are invited (others are skipped)\n- If a user_id doesn't have reviewer role, it's silently skipped\n- Returns both invited user IDs and skipped user IDs\n- All operations are performed in a single transaction\n\n## Use Cases\n- Grant reviewer access to specific flows\n- Update existing invitations (refresh updated_at timestamp)\n- Manage flow-level permissions for review workflows\n- Enable selective flow visibility for team members\n\n## Example\nIf you send user_ids: [user1, user2, user3, user4] and only user1, user2, user3 have reviewer role:\n- Response will show invited_user_ids: [user1, user2, user3]\n- Response will show skipped_user_ids: [user4]",
        "operationId": "upsert_flow_invitations_api_flows__flow_id__invitations_put",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FlowInvitationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowInvitationBulkResponse"
                }
              }
            },
            "description": "Users successfully invited/updated for the flow"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid user IDs"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User doesn't have permission to manage invitations"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Upsert user invitations to a flow",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}/task": {
      "put": {
        "description": "Update a single task within a flow definition.\n\nUpdates one task while preserving the rest of the flow definition.\nMore efficient than replacing the entire definition when modifying a single task.\n\n## Behavior\n- Task is identified by the `name` field in the task definition\n- If task doesn't exist, it will be added\n- If task exists, it will be replaced\n- Only available for flows in 'draft' status",
        "operationId": "update_flow_task_api_flows__flow_id__task_put",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
            "in": "query",
            "name": "include_ordered_task_names",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
              "title": "Include Ordered Task Names",
              "type": "boolean"
            }
          },
          {
            "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
            "in": "query",
            "name": "include_validation_errors",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
              "title": "Include Validation Errors",
              "type": "boolean"
            }
          },
          {
            "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
            "in": "query",
            "name": "include_dynamic_data",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
              "title": "Include Dynamic Data",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
            "in": "query",
            "name": "include_output_schemas",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
              "title": "Include Output Schemas",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "title": "Task Definition",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowResponse"
                }
              }
            },
            "description": "Task successfully updated"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid task definition or flow not in draft status"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Update a single task in flow",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}/upload-url": {
      "post": {
        "description": "Generate pre-signed URL for uploading files to a flow.\n\nCreates a temporary upload URL that allows direct file upload to cloud storage\nwithout exposing storage credentials. Each URL is valid for 1 hour.\n\n## Upload Process\n1. Call this endpoint to receive an upload URL\n2. Use PUT request to upload your file to the returned `upload_url`\n3. Save the returned `file_key` to reference the file later\n4. File becomes accessible via the flow immediately after upload\n\n## Supported File Types\n- Documents: PDF, DOCX, TXT, CSV\n- Images: PNG, JPG, GIF\n- Archives: ZIP, TAR\n- Maximum file size: 100MB",
        "operationId": "generate_upload_url_api_flows__flow_id__upload_url_post",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "description": "MIME type of file to upload (e.g., 'application/pdf', 'image/png')",
            "in": "query",
            "name": "content_type",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "MIME type of file to upload (e.g., 'application/pdf', 'image/png')",
              "title": "Content Type"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Generate Upload Url Api Flows  Flow Id  Upload Url Post",
                  "type": "object"
                }
              }
            },
            "description": "Pre-signed upload URL successfully generated"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Generate file upload URL",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}/versions": {
      "get": {
        "description": "List all versions of a specific flow.\n\nReturns complete version history for a flow, ordered by version number (newest first).\nEach version represents a snapshot of the flow definition at the time it was saved.\n\n## Versioning Behavior\n- Version numbers start at 1 and increment sequentially\n- Versions are immutable once created\n- Latest version is marked with `is_latest: true`\n\n## Use Cases\n- View flow evolution and change history\n- Compare different versions\n- Rollback to previous versions",
        "operationId": "list_flow_versions_api_flows__flow_id__versions_get",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
            "in": "query",
            "name": "include_ordered_task_names",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
              "title": "Include Ordered Task Names",
              "type": "boolean"
            }
          },
          {
            "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
            "in": "query",
            "name": "include_validation_errors",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
              "title": "Include Validation Errors",
              "type": "boolean"
            }
          },
          {
            "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
            "in": "query",
            "name": "include_dynamic_data",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
              "title": "Include Dynamic Data",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
            "in": "query",
            "name": "include_output_schemas",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
              "title": "Include Output Schemas",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/FlowResponse"
                  },
                  "title": "Response List Flow Versions Api Flows  Flow Id  Versions Get",
                  "type": "array"
                }
              }
            },
            "description": "List of flow versions successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User doesn't have access to this flow"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List all versions of a flow",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}/versions/{version}": {
      "get": {
        "description": "Retrieve a specific version of a flow.\n\nAccess historical versions of a flow to view previous definitions,\ncompare changes, or rollback to a previous state.\n\n## Use Cases\n- View flow definition at a specific point in time\n- Compare versions to understand what changed\n- Reference the exact version used in a flow execution",
        "operationId": "get_flow_version_api_flows__flow_id__versions__version__get",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "title": "Version",
              "type": "integer"
            }
          },
          {
            "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
            "in": "query",
            "name": "include_ordered_task_names",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include topologically sorted list of task names in execution order. Useful for visualizing task dependencies. Adds ~50ms latency for complex flows with 20+ tasks.",
              "title": "Include Ordered Task Names",
              "type": "boolean"
            }
          },
          {
            "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
            "in": "query",
            "name": "include_validation_errors",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include DSL validation errors if the flow definition is malformed. Essential for debugging invalid flows during development. No performance impact as validation runs regardless.",
              "title": "Include Validation Errors",
              "type": "boolean"
            }
          },
          {
            "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
            "in": "query",
            "name": "include_dynamic_data",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include runtime configuration options for each task (e.g., dropdown values, available resources). Requires authentication to external services. May add 100-500ms latency depending on integration APIs.",
              "title": "Include Dynamic Data",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
            "in": "query",
            "name": "include_output_schemas",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for each task's output structure. Required for building dynamic UIs or validating task connections. ",
              "title": "Include Output Schemas",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. ",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FlowResponse"
                }
              }
            },
            "description": "Flow version successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get specific flow version",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/flows/{flow_id}/versions/{version}/summary": {
      "get": {
        "description": "List task execution summaries for a specific flow version.\n\nReturns lightweight task summaries without full output data, reducing\nnetwork overhead when you only need execution metadata.\n\n## Performance Benefits\n- Excludes potentially large task output fields\n- Significantly faster response times for flows with large outputs\n- Ideal for listing/summary views\n\n## Use Cases\n- Display execution history in a table/list\n- Check task statuses without downloading full outputs\n- Build dashboards showing execution statistics",
        "operationId": "list_flow_summaries_api_flows__flow_id__versions__version__summary_get",
        "parameters": [
          {
            "in": "path",
            "name": "flow_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Flow Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "title": "Version",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/TaskSummaryResponse"
                  },
                  "title": "Response List Flow Summaries Api Flows  Flow Id  Versions  Version  Summary Get",
                  "type": "array"
                }
              }
            },
            "description": "List of task summaries successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List task summaries for flow version",
        "tags": [
          "flows"
        ]
      }
    },
    "/api/human-review-tasks": {
      "get": {
        "description": "List all human review tasks assigned to the current user.\n\nReturns a paginated list of human review tasks that have been assigned to the\ncurrently authenticated user. Tasks are joined with assignments to filter by user.\n\nContext:\n    - Returns only tasks assigned to the current user\n    - Excludes soft-deleted tasks\n    - Results are paginated using offset and limit\n    - Tasks can be filtered by one or more statuses (optional, comma-separated)\n    - Tasks can be filtered by target task name (optional)\n    - Tasks can be filtered by source task name (optional)\n    - Tasks can be filtered by flow execution ID (optional)\n    - Tasks are returned in the order they appear in the database\n\nUse Cases:\n    - Display user's assigned review tasks in a dashboard\n    - Show pending reviews for the current user\n    - Filter tasks by status (e.g., only show pending tasks)\n    - Filter tasks by multiple statuses (e.g., 'pending,in_progress')\n    - Filter tasks by specific target task name, source task name, or flow execution\n    - Track review task assignments\n\nRelated Endpoints:\n    - POST /human-review-tasks - Create a new review task\n    - GET /human-review-tasks/{id} - Get specific task details",
        "operationId": "list_human_review_tasks_api_human_review_tasks_get",
        "parameters": [
          {
            "description": "Number of records to skip for pagination",
            "example": 0,
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Number of records to skip for pagination",
              "minimum": 0,
              "title": "Offset",
              "type": "integer"
            }
          },
          {
            "description": "Maximum number of records to return",
            "example": 100,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "description": "Maximum number of records to return",
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          },
          {
            "description": "Filter tasks by status(es). Valid values: 'pending', 'in_progress', 'completed'. Multiple statuses can be provided as comma-separated values (e.g., 'pending,in_progress').",
            "example": "pending",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter tasks by status(es). Valid values: 'pending', 'in_progress', 'completed'. Multiple statuses can be provided as comma-separated values (e.g., 'pending,in_progress').",
              "title": "Status"
            }
          },
          {
            "description": "Filter tasks by target task name",
            "example": "my_task",
            "in": "query",
            "name": "target_task_name",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter tasks by target task name",
              "title": "Target Task Name"
            }
          },
          {
            "description": "Filter tasks by source task name",
            "example": "my_source_task",
            "in": "query",
            "name": "source_task_name",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter tasks by source task name",
              "title": "Source Task Name"
            }
          },
          {
            "description": "Filter tasks by flow execution ID",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "in": "query",
            "name": "flow_execution_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter tasks by flow execution ID",
              "title": "Flow Execution Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/HumanReviewTaskResponse"
                  },
                  "title": "Response List Human Review Tasks Api Human Review Tasks Get",
                  "type": "array"
                }
              }
            },
            "description": "List of human review tasks retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List human review tasks assigned to the current user",
        "tags": [
          "human-review-tasks"
        ]
      },
      "post": {
        "description": "Create a new human review task with assigned users.\n\nCreates a new human review task and assigns it to the specified users.\nBoth the task and assignments are created in a single transaction.\n\nContext:\n    - The task is created with the provided flow and execution information\n    - All assigned users are linked to the task via assignments\n    - Organization ID is automatically set from the current user's context\n\nUse Cases:\n    - Create a review task for a flow execution\n    - Assign multiple reviewers to a task\n    - Track human review workflow state\n\nRelated Endpoints:\n    - GET /human-review-tasks - List all tasks\n    - GET /human-review-tasks/{id} - Get task details",
        "operationId": "create_human_review_task_api_human_review_tasks_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanReviewTaskCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanReviewTaskResponse"
                }
              }
            },
            "description": "Human review task created successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid input data"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create a new human review task",
        "tags": [
          "human-review-tasks"
        ]
      }
    },
    "/api/human-review-tasks/{task_id}": {
      "get": {
        "description": "Get a human review task by its ID.\n\nReturns the details of a specific human review task, including its status,\ninstructions, review results, and completion information.\n\nContext:\n    - Returns the full task details for the specified task ID\n    - Excludes soft-deleted tasks\n    - Authorization is handled by RLS policies (user must have access to the organization)\n    - Returns 404 if the task does not exist\n\nUse Cases:\n    - View detailed information about a specific review task\n    - Display task details in a task management UI\n    - Check task status and review results\n    - Access task instructions and completion information\n\nRelated Endpoints:\n    - GET /human-review-tasks - List all tasks assigned to current user\n    - GET /human-review-tasks/{task_id}/assignments - List all assignments for a task\n    - POST /human-review-tasks/{task_id}/start - Start working on a task\n    - POST /human-review-tasks/{task_id}/complete - Complete a task",
        "operationId": "get_human_review_task_api_human_review_tasks__task_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "title": "Task Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanReviewTaskResponse"
                }
              }
            },
            "description": "Human review task retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Human review task not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get a human review task by ID",
        "tags": [
          "human-review-tasks"
        ]
      }
    },
    "/api/human-review-tasks/{task_id}/assignments": {
      "get": {
        "description": "List all assignments for a human review task.\n\nReturns a list of all assignments (user assignments) for the specified human review task.\nThis includes all users who have been assigned to review the task, along with their\nassignment status and when they started working on it.\n\nContext:\n    - Returns all assignments for the specified task\n    - Includes assignment status (pending, in_progress, completed, cancelled)\n    - Includes started_at timestamp for assignments that have been started\n    - Only accessible if the task exists and user has access to the organization\n\nUse Cases:\n    - View all reviewers assigned to a task\n    - Track which reviewers have started or completed their review\n    - Monitor assignment status across all reviewers\n    - Display assignment information in task management UI\n\nRelated Endpoints:\n    - GET /human-review-tasks - List all tasks assigned to current user\n    - POST /human-review-tasks/{task_id}/start - Start working on a task\n    - POST /human-review-tasks/{task_id}/complete - Complete a task",
        "operationId": "list_human_review_task_assignments_api_human_review_tasks__task_id__assignments_get",
        "parameters": [
          {
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "title": "Task Id",
              "type": "string"
            }
          },
          {
            "description": "Whether to include full user information in the response. When true, the 'user' field will be populated with user details.",
            "example": false,
            "in": "query",
            "name": "include_user_info",
            "required": false,
            "schema": {
              "default": false,
              "description": "Whether to include full user information in the response. When true, the 'user' field will be populated with user details.",
              "title": "Include User Info",
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/HumanReviewTaskAssignmentResponse"
                  },
                  "title": "Response List Human Review Task Assignments Api Human Review Tasks  Task Id  Assignments Get",
                  "type": "array"
                }
              }
            },
            "description": "List of assignments retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Human review task not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List all assignments for a human review task",
        "tags": [
          "human-review-tasks"
        ]
      }
    },
    "/api/human-review-tasks/{task_id}/complete": {
      "post": {
        "description": "Complete a human review task.\n\nMarks the task as completed and records the review results. This endpoint:\n- Updates task status to 'completed'\n- Records the review result (correct/incorrect) and reviewed output\n- Sets completed_by and completed_at fields\n- Removes the in-progress record for the user\n- Returns 404 if task not found\n- Returns 400 if task status is not 'in_progress'\n\nContext:\n    - Only authenticated users can complete tasks\n    - Task must be in 'in_progress' status\n    - Records who completed the task and when\n    - Automatically removes in-progress tracking\n\nUse Cases:\n    - User finishes reviewing a task and submits their results\n    - Record validation outcomes for data quality tracking\n    - Complete workflow steps requiring human judgment\n\nRelated Endpoints:\n    - POST /human-review-tasks/{task_id}/start - Start working on a task\n    - GET /human-review-tasks - List all assigned tasks",
        "operationId": "complete_human_review_task_api_human_review_tasks__task_id__complete_post",
        "parameters": [
          {
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "title": "Task Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/HumanReviewTaskCompleteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanReviewTaskResponse"
                }
              }
            },
            "description": "Human review task completed successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Task status is not 'in_progress'"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Human review task not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Complete a human review task",
        "tags": [
          "human-review-tasks"
        ]
      }
    },
    "/api/human-review-tasks/{task_id}/start": {
      "post": {
        "description": "Start a human review task.\n\nMarks the task as in progress for the current user. This endpoint:\n- Creates an in-progress record linking the user to the task\n- Changes task status from 'pending' to 'in_progress' (if it's pending)\n- Returns 409 if the task is already completed\n- Can be called multiple times for the same user (idempotent)\n- Creates a timeout schedule to automatically unstart the task if it remains IN_PROGRESS beyond the configured timeout\n\nContext:\n    - Only authenticated users can start tasks\n    - Updates assignment status to 'in_progress' and sets started_at timestamp\n    - Updates task status if currently pending\n    - Organization ID is automatically set from the current user's context\n\nUse Cases:\n    - User begins working on an assigned review task\n    - Track which users are currently working on which tasks\n    - Prevent starting already completed tasks\n\nRelated Endpoints:\n    - GET /human-review-tasks - List all assigned tasks\n    - POST /human-review-tasks - Create a new review task",
        "operationId": "start_human_review_task_api_human_review_tasks__task_id__start_post",
        "parameters": [
          {
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "title": "Task Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanReviewTaskResponse"
                }
              }
            },
            "description": "Human review task started successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Human review task not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Conflict - Task is already completed"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Start a human review task",
        "tags": [
          "human-review-tasks"
        ]
      }
    },
    "/api/human-review-tasks/{task_id}/unstart": {
      "post": {
        "description": "Unstart a human review task assignment.\n\nResets an in_progress assignment back to pending status. This allows users\nto temporarily leave the review page and potentially return later to continue\ntheir review.\n\nOnly valid for assignments with status 'in_progress'. Attempting to unstart\nan assignment with any other status will result in a 409 Conflict error.\n\nContext:\n    - Only authenticated users can unstart their assignments\n    - Only affects assignments with status 'in_progress'\n    - Resets assignment status back to 'pending' (opposite of /start)\n    - Task status remains unchanged\n    - Organization ID is automatically set from the current user's context\n\nUse Cases:\n    - User needs to temporarily leave the review page\n    - User wants to pause their review and continue later\n    - Browser/page navigation that should save progress but not complete\n\nRelated Endpoints:\n    - POST /human-review-tasks/{task_id}/start - Start working on a task\n    - POST /human-review-tasks/{task_id}/complete - Complete a task\n    - GET /human-review-tasks - List all assigned tasks",
        "operationId": "unstart_human_review_task_assignment_api_human_review_tasks__task_id__unstart_post",
        "parameters": [
          {
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "title": "Task Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HumanReviewTaskResponse"
                }
              }
            },
            "description": "Human review task assignment unstarted successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Human review task or assignment not found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Conflict - Assignment status is not 'in_progress'"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Unstart a human review task assignment",
        "tags": [
          "human-review-tasks"
        ]
      }
    },
    "/api/integrations/catalog": {
      "get": {
        "description": "Retrieve the catalog of available third-party integrations.\n\nReturns a comprehensive list of all integration providers supported by SuperAI Flows.\nEach integration includes metadata about authentication requirements, capabilities,\nand categorization to help users discover and connect external services to their workflows.\n\nContext:\n    - The integration catalog is the primary discovery mechanism for available services\n    - Dynamically generated from the plugin registry (no database storage overhead)\n    - All authenticated users can access the catalog\n    - Automatically excludes credentialless integrations and integrations in migration\n\nIntegration Categories:\n    - **database**: PostgreSQL, internal PostgreSQL database connectors\n    - **storage**: SharePoint document libraries, SFTP file servers\n    - **messaging**: AWS SES email integration\n    - **automation**: Various task executors and workflow automation tools\n\nAuthentication Methods:\n    - **oauth2**: OAuth 2.0 authorization flow (Google, SharePoint, Microsoft)\n    - **user_password**: Username/password authentication (SFTP, PostgreSQL)\n    - **api_key**: API key-based authentication\n    - **key_file**: SSH key-based authentication (SFTP)\n\nUse Cases:\n    - Display available integrations in UI marketplace\n    - Show available connectors during flow task configuration\n    - Validate provider support before connection attempts\n    - Determine authentication requirements before OAuth flows\n    - Populate provider selection dropdowns\n\nRelated Endpoints:\n    - GET /integrations/plugins - List detailed plugin metadata\n    - GET /integrations/plugins/{plugin_name}/capabilities - Get plugin capabilities\n    - POST /integrations/credentials - Create credentials for integration\n    - GET /integrations/credentials - List user's configured credentials\n\nNotes:\n    - OAuth integrations require additional authorize/callback flow\n    - Integration availability \u2260 user has configured credentials\n    - Plugin system allows custom integrations without code changes\n    - Use GET /integrations/credentials to check user's connections",
        "operationId": "get_integration_catalog_api_integrations_catalog_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/IntegrationCatalogResponse"
                  },
                  "title": "Response Get Integration Catalog Api Integrations Catalog Get",
                  "type": "array"
                }
              }
            },
            "description": "Integration catalog retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List integration catalog",
        "tags": [
          "integrations"
        ]
      }
    },
    "/api/integrations/credentials": {
      "get": {
        "description": "Retrieve all integration credentials for the authenticated user.\n\nReturns stored credentials for various integration providers including Google Drive,\nSharePoint, SFTP servers, PostgreSQL databases, and other external services. Each\ncredential contains metadata about the integration but excludes sensitive authentication\ndata (passwords, tokens, API keys) by default.\n\nContext:\n    - Credentials are scoped to the authenticated user and their organization\n    - Returns only active (non-deleted) credentials\n    - Ordered by creation date (newest first)\n    - OAuth credentials with expired tokens are still returned\n    - Maximum 100 credentials per user\n    - Credentials are encrypted at rest using AES-256-GCM\n\nUse Cases:\n    - Display available integrations in the UI integration dashboard\n    - Check which external services the user has already connected\n    - Retrieve credential IDs for making integration-specific API calls\n    - Audit credential creation dates and verify active connections\n    - Support integration selection workflows in flow configuration\n\nRelated Endpoints:\n    - POST /integrations/credentials - Create new integration credential\n    - GET /integrations/credentials/{credential_id} - Get specific credential details\n    - GET /integrations/credentials/provider/{provider} - Filter credentials by provider\n    - GET /integrations/credentials/{credential_id}/credentials - Get credential secrets\n    - DELETE /integrations/credentials/{credential_id} - Delete credential\n\nSecurity Notes:\n    - Sensitive data (passwords, tokens, keys) excluded from response\n    - Use GET /integrations/credentials/{id}/credentials to retrieve sensitive data\n    - Cross-organization access not permitted",
        "operationId": "get_user_credentials_api_integrations_credentials_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CredentialsResponse"
                  },
                  "title": "Response Get User Credentials Api Integrations Credentials Get",
                  "type": "array"
                }
              }
            },
            "description": "List of user credentials retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List user credentials",
        "tags": [
          "integrations",
          "integrations"
        ]
      },
      "post": {
        "description": "Create new integration credentials for connecting to external services.\n\nStores encrypted credentials for connecting to third-party services like Google Drive,\nSharePoint, SFTP servers, or PostgreSQL databases. Credentials are encrypted at rest\nusing AES-256-GCM and scoped to the user's organization for security isolation.\n\nContext:\n    This endpoint is the primary mechanism for establishing connections to external integrations.\n    After credentials are created, they can be used in:\n    - Flow tasks that require external data sources (file inputs, database queries)\n    - Webhook subscriptions for real-time data synchronization\n    - Batch data imports from cloud storage providers\n    - Database query operations within workflow executions\n    - OAuth-based integrations (after completing OAuth flow first)\n\n    Credentials are never stored in plaintext and cannot be retrieved after creation.\n    For OAuth providers (Google, SharePoint), complete the authorization flow first,\n    then the callback handler automatically creates credentials.\n\nUse Cases:\n    Create SFTP credentials for connecting to a file server to download CSV files in a workflow.\n\n    Store PostgreSQL database credentials to enable SQL query tasks in flows.\n\n    After testing connection with POST /integrations/sftp/test-connection, create permanent credentials.\nRelated Endpoints:\n    - POST /integrations/sftp/test-connection - Test SFTP credentials before saving\n    - POST /integrations/postgres/test-connection - Test PostgreSQL credentials before saving\n    - GET /integrations/google/authorize - Initiate Google OAuth flow\n    - GET /integrations/sharepoint/authorize - Initiate SharePoint OAuth flow\n    - GET /integrations/credentials - List all user credentials\n    - GET /integrations/credentials/{credential_id} - Get specific credential metadata\n    - DELETE /integrations/credentials/{credential_id} - Delete credential\n    - PATCH /integrations/credentials/{credential_id} - Update credential\n\nSecurity:\n    - Credentials are encrypted using Fernet (AES-256-GCM) before database storage\n    - Encryption keys are managed via environment variables and never exposed via API\n    - Passwords, private keys, and tokens are never logged or included in API responses\n    - Credentials are scoped to organization with strict isolation enforced at query level\n    - OAuth tokens are automatically refreshed when expired (no user action required)\n    - Audit trail: Created timestamps and user associations tracked for compliance\n\nNotes:\n    - Always test credentials before creating them (use test-connection endpoints)\n    - OAuth credentials require completing the OAuth authorization flow first\n    - Maximum 50 credentials per provider per organization (contact support for higher limits)\n    - Credentials cannot be retrieved in plaintext after creation (security by design)\n    - For SFTP key_file authentication, ensure private key is in valid PEM format\n    - PostgreSQL connection_string takes precedence over individual connection fields",
        "operationId": "create_user_credentials_api_integrations_credentials_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserIntegrationCredentialsCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CredentialsResponse"
                }
              }
            },
            "description": "Credentials created successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request data"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "User account required"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create integration credentials",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/credentials/provider/{provider}": {
      "get": {
        "description": "Retrieve user credentials filtered by integration provider.\n\nReturns credentials for a specific integration provider. This is useful when you need to\nfind credentials for a particular service without fetching all credentials.\n\nContext:\n    This endpoint provides filtered access to credentials, commonly used when:\n    - Checking if a user has connected to a specific provider (e.g., SharePoint)\n    - Populating provider-specific integration configuration UI\n    - Validating credential availability before initiating provider-specific workflows\n    - Building provider selection dropdowns with availability indicators\n\nUse Cases:\n    Check if user has SharePoint credentials before showing SharePoint site picker.\n\n    Filter credentials for Google provider to display connected Google accounts in UI.\n\n    Validate SFTP credential availability before configuring file upload task.\nRelated Endpoints:\n    - GET /integrations/credentials - Get all credentials (unfiltered)\n    - POST /integrations/credentials - Create new credential for a provider\n    - GET /integrations/catalog - List all available providers\n\nNotes:\n    - Provider names are case-insensitive but lowercase is recommended\n    - Multiple credentials per provider are supported (e.g., multiple SFTP servers)\n    - Soft-deleted credentials are excluded from results",
        "operationId": "get_user_credentials_by_provider_api_integrations_credentials_provider__provider__get",
        "parameters": [
          {
            "description": "Integration provider to filter credentials by. Valid providers: microsoft, sharepoint, sftp, aws_ses, google, postgresql, internal_postgresql. Returns only credentials matching the specified provider.",
            "example": "sharepoint",
            "in": "path",
            "name": "provider",
            "required": true,
            "schema": {
              "$ref": "#/components/schemas/ProviderApiEnum",
              "description": "Integration provider to filter credentials by. Valid providers: microsoft, sharepoint, sftp, aws_ses, google, postgresql, internal_postgresql. Returns only credentials matching the specified provider."
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/CredentialsResponse"
                  },
                  "title": "Response Get User Credentials By Provider Api Integrations Credentials Provider  Provider  Get",
                  "type": "array"
                }
              }
            },
            "description": "List of credentials for the specified provider retrieved successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid provider"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List credentials by provider",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/credentials/{credential_id}": {
      "delete": {
        "description": "Soft-delete an integration credential.\n\nMarks the credential as deleted without physically removing it from the database.\nDeleted credentials are excluded from list queries and cannot be used in workflows.\n\nContext:\n    This endpoint safely removes credentials while preserving audit trail. Common scenarios:\n    - User disconnects an integration from settings UI\n    - Credential compromise detected (delete and recreate)\n    - Integration no longer needed for workflows\n    - OAuth token revoked by provider\n\n    Soft deletion allows recovery if needed and maintains historical records for compliance.\n\nUse Cases:\n    User clicks \"Disconnect\" button for SharePoint integration in settings UI.\n\n    Remove compromised SFTP credentials before creating new ones with rotated password.\n\n    Clean up unused credentials to reduce organization's attack surface.\nRelated Endpoints:\n    - GET /integrations/credentials - List active credentials (excludes deleted)\n    - GET /integrations/credentials/{credential_id} - Verify credential before deletion\n    - POST /integrations/credentials - Create new credential to replace deleted one\n\nSecurity:\n    - Soft deletion preserves audit trail for compliance\n    - Encrypted credential data remains in database but inaccessible\n    - Consider automatic credential rotation policies for sensitive environments\n    - Deleted credentials cannot be restored via API (database admin required)\n\nNotes:\n    - Deletion is immediate and cannot be undone via API\n    - Workflows using this credential will fail after deletion\n    - Check for dependent workflows before deleting credentials\n    - OAuth tokens are not revoked at provider (user must revoke separately)",
        "operationId": "delete_user_credential_api_integrations_credentials__credential_id__delete",
        "parameters": [
          {
            "description": "UUID of the credential to delete. Must belong to the authenticated user's organization.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "in": "path",
            "name": "credential_id",
            "required": true,
            "schema": {
              "description": "UUID of the credential to delete. Must belong to the authenticated user's organization.",
              "format": "uuid",
              "title": "Credential Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Credential deleted successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid credential ID"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Credential not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Delete credential",
        "tags": [
          "integrations",
          "integrations"
        ]
      },
      "get": {
        "description": "Retrieve metadata for a specific integration credential.\n\nReturns credential metadata without sensitive data. Use this endpoint to check credential\nstatus, provider type, and creation date without exposing passwords or tokens.\n\nContext:\n    This endpoint provides safe access to credential information for UI display and\n    validation purposes. Common use cases include:\n    - Displaying credential details in integration settings pages\n    - Verifying credential ownership before performing operations\n    - Checking credential type before initiating provider-specific workflows\n    - Validating credential exists before attempting to use it in tasks\n\nUse Cases:\n    Verify credential exists and belongs to current user before displaying integration UI.\n\n    Check credential type to determine which configuration UI to show (password vs OAuth).\n\n    Display credential creation date in integration settings for audit purposes.\nRelated Endpoints:\n    - GET /integrations/credentials - List all user credentials\n    - GET /integrations/credentials/{credential_id}/credentials - Get credential secrets (service accounts only)\n    - PATCH /integrations/credentials/{credential_id} - Update credential\n    - DELETE /integrations/credentials/{credential_id} - Delete credential\n\nNotes:\n    - This endpoint is safe for UI use (no sensitive data exposure)\n    - Soft-deleted credentials return 404\n    - OAuth credentials include token expiration metadata",
        "operationId": "get_user_credential_api_integrations_credentials__credential_id__get",
        "parameters": [
          {
            "description": "UUID of the credential to retrieve. Must belong to the authenticated user's organization.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "in": "path",
            "name": "credential_id",
            "required": true,
            "schema": {
              "description": "UUID of the credential to retrieve. Must belong to the authenticated user's organization.",
              "format": "uuid",
              "title": "Credential Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CredentialsResponse"
                }
              }
            },
            "description": "Credential metadata retrieved successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid credential ID"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Credential not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get credential by ID",
        "tags": [
          "integrations",
          "integrations"
        ]
      },
      "patch": {
        "description": "Update existing integration credentials with new values.\n\nReplaces credential data (passwords, tokens, connection details) for an existing credential.\nUse this endpoint to rotate passwords, update connection strings, or refresh OAuth tokens.\n\nContext:\n    Credential updates are necessary for several operational scenarios:\n    - Password rotation policies require periodic credential updates\n    - SFTP server configuration changes (hostname, port)\n    - Database connection string modifications\n    - SSH key rotation for key-based authentication\n    - OAuth token refresh (though typically handled automatically)\n\n    Updates preserve credential_id, allowing workflows to continue using the same reference.\n\nUse Cases:\n    Rotate SFTP password after security audit requires credential changes.\n\n    Update PostgreSQL connection string after database server migration.\n\n    Replace SSH private key after key compromise detected.\nRelated Endpoints:\n    - GET /integrations/credentials/{credential_id} - Get credential metadata before updating\n    - POST /integrations/sftp/test-connection - Test new SFTP credentials before updating\n    - POST /integrations/postgres/test-connection - Test new PostgreSQL credentials before updating\n    - DELETE /integrations/credentials/{credential_id} - Delete credential instead of updating\n\nSecurity:\n    - New credentials are encrypted before storage (same as creation)\n    - Old credential data is overwritten (not preserved in database)\n    - Audit trail tracks who performed the update via modified_by field\n    - Test new credentials before updating to prevent workflow disruption\n\nNotes:\n    - Always test new credentials before updating to avoid breaking workflows\n    - Workflows using this credential will use new values immediately\n    - OAuth credentials are typically auto-refreshed (manual update rarely needed)\n    - Consider creating new credential instead of updating if provider changes",
        "operationId": "update_user_credential_api_integrations_credentials__credential_id__patch",
        "parameters": [
          {
            "description": "UUID of the credential to update. Must belong to the authenticated user's organization.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "in": "path",
            "name": "credential_id",
            "required": true,
            "schema": {
              "description": "UUID of the credential to update. Must belong to the authenticated user's organization.",
              "format": "uuid",
              "title": "Credential Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserIntegrationCredentialsUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CredentialsResponse"
                }
              }
            },
            "description": "Credential updated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request data or credential ID"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Credential not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Update credential",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/credentials/{credential_id}/credentials": {
      "get": {
        "description": "Retrieve decrypted credential secrets for integration use.\n\nReturns the actual credential data (passwords, tokens, keys) in decrypted form. This endpoint\nis restricted to service accounts only for security. Regular users cannot retrieve plaintext\ncredentials after creation.\n\nContext:\n    This endpoint provides access to sensitive credential data for system-level operations.\n    It is primarily used by:\n    - Service accounts executing workflows that need integration credentials\n    - Internal services performing integration health checks\n    - System processes that need to establish external connections\n    - Automated credential rotation and renewal workflows\n\n    Regular user accounts cannot access this endpoint to prevent credential exposure.\n\nUse Cases:\n    Service account retrieves SFTP credentials to execute file download task in workflow.\n\n    Internal health check service validates PostgreSQL credential by attempting connection.\n\n    Automated token refresh service retrieves OAuth refresh_token for renewal.\nRelated Endpoints:\n    - GET /integrations/credentials - List credentials (metadata only, no secrets)\n    - POST /integrations/credentials - Create new credential\n    - PATCH /integrations/credentials/{credential_id} - Update credential\n\nSecurity:\n    - Service accounts only - regular users cannot retrieve plaintext credentials\n    - Credentials are decrypted in-memory only (never logged or persisted unencrypted)\n    - Organization isolation enforced at query level\n    - Audit logging recommended for production use\n    - Consider rotating credentials if this endpoint is compromised\n\nNotes:\n    - This endpoint is intended for internal system use, not direct customer API calls\n    - Sensitive data should be handled securely and never exposed in logs or responses\n    - OAuth tokens are automatically refreshed if expired before returning",
        "operationId": "get_credential_secrets_api_integrations_credentials__credential_id__credentials_get",
        "parameters": [
          {
            "description": "UUID of the credential to retrieve sensitive data from. User must own this credential or have service account permissions.",
            "example": "123e4567-e89b-12d3-a456-426614174000",
            "in": "path",
            "name": "credential_id",
            "required": true,
            "schema": {
              "description": "UUID of the credential to retrieve sensitive data from. User must own this credential or have service account permissions.",
              "format": "uuid",
              "title": "Credential Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Credential secrets retrieved successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid credential ID"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Service account required"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Credential not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get credential secrets",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database": {
      "get": {
        "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": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "title": "Response List Databases Api Integrations Database Get",
                  "type": "array"
                }
              }
            },
            "description": "List of databases successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List user databases",
        "tags": [
          "integrations",
          "integrations"
        ]
      },
      "post": {
        "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": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentFileResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create Database",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database/{db_id}": {
      "delete": {
        "description": "Delete a database integration.\n\nRemoves the database integration and its associated CSV file from storage.\nThis operation may affect workflows that reference this database.\n\nUse Cases:\n    - Clean up unused database integrations\n    - Remove test databases\n    - Decommission data sources",
        "operationId": "delete_database_api_integrations_database__db_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Db Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "title": "Response Delete Database Api Integrations Database  Db Id  Delete",
                  "type": "boolean"
                }
              }
            },
            "description": "Database deleted successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Database not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Delete database",
        "tags": [
          "integrations",
          "integrations"
        ]
      },
      "get": {
        "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": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "title": "Db Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Get Database Api Integrations Database  Db Id  Get",
                  "type": "object"
                }
              }
            },
            "description": "Database details retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Database not found with the specified ID"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get database by ID",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database/{db_id}/columns": {
      "get": {
        "description": "Retrieve column names from a specific database.\n\nReturns the list of columns available in the database, useful for:\n- Building query interfaces\n- Configuring data mappings\n- Validating field references in workflows\n\nUse Cases:\n    - Display available columns in query builder\n    - Configure column mappings for data transformation\n    - Validate workflow field references",
        "operationId": "get_database_columns_api_integrations_database__db_id__columns_get",
        "parameters": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "title": "Db Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatabaseColumnsResponse"
                }
              }
            },
            "description": "Database columns retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Database or columns not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get database columns",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database/{db_id}/download": {
      "get": {
        "description": "Generate pre-signed URL for downloading the database CSV file.",
        "operationId": "get_download_url_api_integrations_database__db_id__download_get",
        "parameters": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "title": "Db Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatabaseDownloadResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get Download Url",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database/{db_id}/upload-url": {
      "post": {
        "description": "Generate a pre-signed URL for uploading files to a database.\n\nCreates a temporary upload URL that allows direct file uploads to cloud storage\nwithout routing data through the API server. The URL expires after 1 hour.\n\nThis is the first step in the multi-step upload workflow:\n1. Generate upload URL (this endpoint)\n2. Upload file directly to cloud storage using the URL\n3. Preview uploaded file (optional)\n4. Complete upload and process file\n\nUse Cases:\n    - Upload CSV files for data import\n    - Upload large datasets efficiently\n    - Batch data ingestion\n\nSecurity:\n    - URL expires after 1 hour\n    - File is uploaded to user-specific path\n    - Metadata includes database ID for tracking",
        "operationId": "generate_database_upload_url_api_integrations_database__db_id__upload_url_post",
        "parameters": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "title": "Db Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "content_type",
            "required": false,
            "schema": {
              "title": "Content Type",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadUrlResponse"
                }
              }
            },
            "description": "Pre-signed upload URL generated successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Database not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Generate database upload URL",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database/{db_id}/upload/compare": {
      "post": {
        "description": "Compare existing CSV with new CSV for replace operation.",
        "operationId": "compare_csv_for_replace_api_integrations_database__db_id__upload_compare_post",
        "parameters": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "title": "Db Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "title": "Request",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Compare Csv For Replace",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database/{db_id}/upload/complete": {
      "post": {
        "description": "Complete file upload and process the file.",
        "operationId": "complete_file_upload_api_integrations_database__db_id__upload_complete_post",
        "parameters": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "title": "Db Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FileUploadCompleteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Complete File Upload",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database/{db_id}/upload/preview": {
      "post": {
        "description": "Preview CSV file before final import.\n\nShows the first 5 rows and file metadata to help users:\n- Verify correct file was uploaded\n- Confirm header row detection\n- Check delimiter parsing\n- Review column names\n- Validate data format\n\nThis is step 3 in the upload workflow (optional):\n1. Generate upload URL\n2. Upload file to cloud storage\n3. Preview file (this endpoint)\n4. Complete upload and process\n\nUse Cases:\n    - Verify file structure before import\n    - Confirm CSV parsing settings\n    - Preview data for validation",
        "operationId": "preview_csv_upload_api_integrations_database__db_id__upload_preview_post",
        "parameters": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "title": "Db Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "title": "Request",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CSVPreviewResponse"
                }
              }
            },
            "description": "CSV preview generated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid request - missing upload_id or empty CSV file"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "File not found with the specified upload_id"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Preview CSV file before import",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/database/{db_id}/upload/replace": {
      "post": {
        "description": "Replace existing database data with new file upload.",
        "operationId": "replace_file_upload_api_integrations_database__db_id__upload_replace_post",
        "parameters": [
          {
            "in": "path",
            "name": "db_id",
            "required": true,
            "schema": {
              "title": "Db Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FileUploadCompleteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Replace File Upload",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/email/process": {
      "post": {
        "description": "Manually trigger email processing (for testing).",
        "operationId": "process_emails_api_integrations_email_process_post",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Process Emails",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/email/tasks": {
      "post": {
        "description": "Create a new email task with a unique email address.",
        "operationId": "create_email_task_api_integrations_email_tasks_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailTaskRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailTaskResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create Email Task",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/email/tasks/{task_id}": {
      "get": {
        "description": "Get status of an email task.",
        "operationId": "get_email_task_status_api_integrations_email_tasks__task_id__get",
        "parameters": [
          {
            "in": "path",
            "name": "task_id",
            "required": true,
            "schema": {
              "title": "Task Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/EmailTaskStatus"
                    },
                    {
                      "type": "null"
                    }
                  ],
                  "title": "Response Get Email Task Status Api Integrations Email Tasks  Task Id  Get"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get Email Task Status",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/plugins/": {
      "get": {
        "description": "List all registered plugins from the integration registry.\n\nReturns plugins available in the new plugin system only, excluding legacy integrations.\nEach plugin includes metadata about its capabilities, version, and status.\n\nUse Cases:\n    - Display available integrations to users\n    - Validate plugin availability before configuration\n    - Integration discovery and selection",
        "operationId": "list_plugins_api_integrations_plugins__get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "title": "Response List Plugins Api Integrations Plugins  Get",
                  "type": "array"
                }
              }
            },
            "description": "List of plugins successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List all registered plugins",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/postgres/execute": {
      "post": {
        "description": "Execute PostgreSQL task using the new plugin system.",
        "operationId": "execute_postgres_plugin_task_api_integrations_plugins_postgres_execute_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "title": "Params",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Execute Postgres Plugin Task",
        "tags": [
          "integrations"
        ]
      }
    },
    "/api/integrations/plugins/postgres/test-connection": {
      "post": {
        "description": "Test PostgreSQL connection using the new plugin system.",
        "operationId": "test_postgres_plugin_connection_api_integrations_plugins_postgres_test_connection_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "title": "Connection Params",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Test Postgres Plugin Connection",
        "tags": [
          "integrations"
        ]
      }
    },
    "/api/integrations/plugins/sharepoint/drives": {
      "get": {
        "operationId": "get_sharepoint_drives_api_integrations_plugins_sharepoint_drives_get",
        "parameters": [
          {
            "in": "query",
            "name": "credential_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Credential Id",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "site_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Site Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get Sharepoint Drives",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/sharepoint/sites": {
      "get": {
        "operationId": "get_sharepoint_sites_api_integrations_plugins_sharepoint_sites_get",
        "parameters": [
          {
            "in": "query",
            "name": "credential_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Credential Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get Sharepoint Sites",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/capabilities": {
      "get": {
        "description": "Retrieve detailed capabilities of a specific plugin.\n\nReturns comprehensive information about what the plugin can do, including:\n- Supported operations and execution models\n- Required authentication types\n- Configuration schema and metadata\n- Webhook support status\n\nUse Cases:\n    - Display plugin configuration UI\n    - Validate plugin compatibility with workflow\n    - Generate plugin documentation",
        "operationId": "get_plugin_capabilities_api_integrations_plugins__plugin_name__capabilities_get",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "title": "Response Get Plugin Capabilities Api Integrations Plugins  Plugin Name  Capabilities Get",
                  "type": "object"
                }
              }
            },
            "description": "Plugin capabilities retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Plugin not found with the specified name"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get plugin capabilities",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/folders": {
      "get": {
        "operationId": "list_folders_api_integrations_plugins__plugin_name__folders_get",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "credential_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Credential Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List Folders",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/instances": {
      "get": {
        "operationId": "list_integration_instances_api_integrations_plugins__plugin_name__instances_get",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "flow_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Flow Id"
            }
          },
          {
            "in": "query",
            "name": "task_name",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Task Name"
            }
          },
          {
            "in": "query",
            "name": "task_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Task Id"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List Integration Instances",
        "tags": [
          "integrations",
          "plugins"
        ]
      },
      "post": {
        "operationId": "create_integration_legacy_api_integrations_plugins__plugin_name__instances_post",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "title": "Request Body",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create Integration Legacy",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/instances/{integration_id}": {
      "delete": {
        "operationId": "delete_integration_legacy_api_integrations_plugins__plugin_name__instances__integration_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Delete Integration Legacy",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/instances/{integration_id}/files": {
      "delete": {
        "operationId": "delete_file_api_integrations_plugins__plugin_name__instances__integration_id__files_delete",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Delete File",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/instances/{integration_id}/files/move": {
      "post": {
        "operationId": "move_file_api_integrations_plugins__plugin_name__instances__integration_id__files_move_post",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Move File",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/instances/{integration_id}/webhook/callback": {
      "post": {
        "operationId": "handle_webhook_legacy_api_integrations_plugins__plugin_name__instances__integration_id__webhook_callback_post",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Handle Webhook Legacy",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/oauth/authorize": {
      "post": {
        "operationId": "oauth_authorize_legacy",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/app__api__integrations__plugins__plugins_router__OauthAuthorizeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Oauth Authorize Legacy",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/plugins/{plugin_name}/oauth/callback": {
      "get": {
        "operationId": "oauth_callback_legacy",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "code",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Code"
            }
          },
          {
            "in": "query",
            "name": "state",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "State"
            }
          },
          {
            "in": "query",
            "name": "error",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Error"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Oauth Callback Legacy",
        "tags": [
          "integrations",
          "plugins"
        ]
      }
    },
    "/api/integrations/postgres/test-connection": {
      "post": {
        "description": "Test PostgreSQL connection (proxied to legacy system).",
        "operationId": "test_postgres_connection_api_integrations_postgres_test_connection_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PostgresCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "boolean"
                  },
                  "title": "Response Test Postgres Connection Api Integrations Postgres Test Connection Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Test Postgres Connection",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/postgres/test-connection/{credential_id}": {
      "post": {
        "description": "Test PostgreSQL connection by credential ID (proxied to legacy system).",
        "operationId": "test_postgres_connection_by_credential_id_api_integrations_postgres_test_connection__credential_id__post",
        "parameters": [
          {
            "in": "path",
            "name": "credential_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Credential Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "type": "boolean"
                  },
                  "title": "Response Test Postgres Connection By Credential Id Api Integrations Postgres Test Connection  Credential Id  Post",
                  "type": "object"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Test Postgres Connection By Credential Id",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/integrations/sftp/test-connection": {
      "post": {
        "description": "Test SFTP connection by attempting to connect and write a test file.",
        "operationId": "test_sftp_connection_api_integrations_sftp_test_connection_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SftpTestConnectionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Test Sftp Connection",
        "tags": [
          "integrations",
          "integrations"
        ]
      }
    },
    "/api/models": {
      "get": {
        "description": "Retrieve a list of available AI models, deduplicated by model name and optionally filtered by region.\n\n    Each model entry aggregates information from all available endpoints:\n    - **regions**: All regions where this model is deployed\n    - **locations**: All specific locations (e.g., westeurope, eastus)\n    - **providers**: All providers offering this model\n    - **endpoint_count**: Total number of endpoints available\n\n    Use the `region` parameter to filter models by deployment region:\n    - `eu`: Only models with at least one EU endpoint\n    - `global`: Only models with at least one global/US endpoint\n\n    If no region is specified, all models are returned.",
        "operationId": "get_models_api_models_get",
        "parameters": [
          {
            "description": "Filter models by region. If not specified, returns all models.",
            "in": "query",
            "name": "region",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "$ref": "#/components/schemas/Region"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter models by region. If not specified, returns all models.",
              "title": "Region"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ModelsResponse"
                }
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List available models",
        "tags": [
          "models"
        ]
      }
    },
    "/api/organizations/credits": {
      "get": {
        "description": "Get credit balance for the current user's organization.\n\nReturns the current credit balance including grants, consumption, and remaining credits\nfor the authenticated user's organization.\n\n**M1 Note**: Currently only shows granted credits. Usage tracking will be added\nin a future release, so credits_consumed is always 0.\n\n**Authorization**:\n- Organization admins and users can view their own organization's credits\n- RLS policies enforce organization-level data isolation at database level\n\n**Context**:\n- Credits are tracked at the organization level, not per user\n- Grants are permanent allocations (cannot be revoked)\n- New organizations receive 30,000 credits automatically\n- Credits consumed will track usage across all users in the organization\n\n**Use Cases**:\n- Display credit balance in user dashboard\n- Check remaining credits before starting workflows\n- Monitor organization usage\n\n**Related Endpoints**:\n- POST /admin/organizations/{id}/grants - Admin can grant additional credits (backoffice only)\n\n**Security**:\n- @require_roles decorator enforces role-based access\n- Uses current_user.organization_id (no path parameter to validate)\n- RLS policies provide database-level enforcement",
        "operationId": "get_organization_credits_api_organizations_credits_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreditBalanceResponse"
                }
              }
            },
            "description": "Credit balance retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get credit balance for current user's organization",
        "tags": [
          "organizations"
        ]
      }
    },
    "/api/plugins/instances": {
      "get": {
        "operationId": "list_instances_api_plugins_instances_get",
        "parameters": [
          {
            "in": "query",
            "name": "flow_id",
            "required": true,
            "schema": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Flow Id"
            }
          },
          {
            "in": "query",
            "name": "task_name",
            "required": true,
            "schema": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Task Name"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List Instances",
        "tags": [
          "plugins"
        ]
      }
    },
    "/api/plugins/{plugin_name}/instances": {
      "get": {
        "operationId": "list_integrations_api_plugins__plugin_name__instances_get",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "flow_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Flow Id"
            }
          },
          {
            "in": "query",
            "name": "task_name",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Task Name"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List Integrations",
        "tags": [
          "plugins"
        ]
      },
      "post": {
        "operationId": "create_integration_api_plugins__plugin_name__instances_post",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IntegrationCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create Integration",
        "tags": [
          "plugins"
        ]
      }
    },
    "/api/plugins/{plugin_name}/instances/{integration_id}": {
      "delete": {
        "operationId": "delete_integration_api_plugins__plugin_name__instances__integration_id__delete",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Delete Integration",
        "tags": [
          "plugins"
        ]
      },
      "put": {
        "operationId": "update_integration_api_plugins__plugin_name__instances__integration_id__put",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "title": "Request Body",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Update Integration",
        "tags": [
          "plugins"
        ]
      }
    },
    "/api/plugins/{plugin_name}/instances/{integration_id}/execute": {
      "post": {
        "operationId": "execute_integration_api_plugins__plugin_name__instances__integration_id__execute_post",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "title": "Request Body",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Execute Integration",
        "tags": [
          "plugins"
        ]
      }
    },
    "/api/plugins/{plugin_name}/instances/{integration_id}/ui_schema": {
      "post": {
        "operationId": "get_ui_schema_api_plugins__plugin_name__instances__integration_id__ui_schema_post",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GetUiSchemaRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get Ui Schema",
        "tags": [
          "plugins"
        ]
      }
    },
    "/api/plugins/{plugin_name}/instances/{integration_id}/webhook/callback": {
      "post": {
        "operationId": "handle_webhook_api_plugins__plugin_name__instances__integration_id__webhook_callback_post",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "integration_id",
            "required": true,
            "schema": {
              "format": "uuid",
              "title": "Integration Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Handle Webhook",
        "tags": [
          "plugins"
        ]
      }
    },
    "/api/plugins/{plugin_name}/oauth/authorize": {
      "post": {
        "operationId": "oauth_authorize_v2",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/app__api__integrations_new__integration_api_model__OauthAuthorizeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Oauth Authorize",
        "tags": [
          "plugins"
        ]
      }
    },
    "/api/plugins/{plugin_name}/{provider_name}/oauth/callback": {
      "get": {
        "operationId": "oauth_callback_v2",
        "parameters": [
          {
            "in": "path",
            "name": "plugin_name",
            "required": true,
            "schema": {
              "title": "Plugin Name",
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "provider_name",
            "required": true,
            "schema": {
              "title": "Provider Name",
              "type": "string"
            }
          },
          {
            "in": "query",
            "name": "code",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Code"
            }
          },
          {
            "in": "query",
            "name": "state",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "State"
            }
          },
          {
            "in": "query",
            "name": "error",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Error"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {}
              }
            },
            "description": "Successful Response"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Oauth Callback",
        "tags": [
          "plugins"
        ]
      }
    },
    "/api/profile/me": {
      "get": {
        "description": "Retrieve complete profile information for the currently authenticated user.\n\nReturns the full user profile including personal information, role, status,\nand organization membership with organization name. The user is automatically\nidentified from their authentication credentials. No user ID parameter is needed.\n\nContext:\n    - Returns user regardless of active/inactive/pending status\n    - Includes organization_id AND organization_name for multi-tenant access control\n    - Organization name used by frontend to enable/disable features (e.g., \"super-ai\" org)\n    - Profile data is read-only via this endpoint (use PATCH /profile/me to update)\n    - User role determines API permissions across the platform\n\nBehavior:\n    1. Extracts user_id from authenticated user context\n    2. Queries database for complete user profile by user_id\n    3. Queries organization to get organization name\n    4. Returns user profile with organization_name included\n    5. Raises 404 if user exists in auth system but not in database (rare edge case)\n\nUse Cases:\n    - Display user name and email in application header\n    - Check user role to show/hide UI features (org_admin, app_user, etc.)\n    - Check organization name for feature gating (e.g., credits visible for \"super-ai\")\n    - Verify user's organization for multi-tenant data filtering\n    - Determine user status for account activation workflows\n    - Fetch user details after authentication to initialize session\n\nRelated Endpoints:\n    - PATCH /profile/me - Update current user's name\n    - GET /admin/users/{user_id} - Admin endpoint to view any user\n    - GET /admin/organizations/{org_id}/users - List users in organization\n    - GET /organizations/{org_id}/credits - View organization credit balance",
        "operationId": "get_current_user_api_profile_me_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserProfileResponse"
                }
              }
            },
            "description": "User profile retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "User account not found in database despite valid authentication token"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get current user profile",
        "tags": [
          "profile"
        ]
      },
      "patch": {
        "description": "Update the currently authenticated user's profile information.\n\nAllows users to modify their personal information including first and last name.\nOnly the fields provided in the request body will be updated. Omitted fields\nremain unchanged. The user is automatically identified from their authentication credentials.\n\nContext:\n    - Only first_name and last_name can be updated via this endpoint\n    - Password field in request body is reserved for future use (not implemented)\n    - Email, role, status, and organization cannot be changed by users\n    - Updates are immediate and reflected in database upon success\n    - Full user profile returned in response with updated values\n\nBehavior:\n    1. Extracts user_id from authenticated user context\n    2. Validates request body fields (min/max length constraints)\n    3. Queries database to verify user exists\n    4. Updates only first_name and last_name if provided\n    5. Persists changes to database with updated_at timestamp\n    6. Returns complete updated user profile\n\nUse Cases:\n    - User wants to correct misspelled name\n    - User prefers different name display (nickname vs full name)\n    - User changes last name after marriage or legal name change\n    - Profile updates during onboarding or account setup\n    - Internationalization of name display\n\nField Update Rules:\n    - first_name: 1-100 characters if provided, unchanged if null\n    - last_name: 1-100 characters if provided, unchanged if null\n    - password: Not currently implemented, reserved for future use\n    - All other fields (email, role, status): Use admin endpoints to modify\n\nRelated Endpoints:\n    - GET /profile/me - Retrieve current user profile\n    - PUT /admin/users/{user_id} - Admin endpoint to update any user\n    - POST /auth/change-password - Change password (separate auth flow)",
        "operationId": "update_current_user_api_profile_me_patch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserUpdateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            },
            "description": "User profile updated successfully with new values"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "User account not found in database despite valid authentication token"
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "type_error": {
                    "summary": "Type validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "input": "not-a-uuid",
                            "loc": [
                              "path",
                              "flow_id"
                            ],
                            "msg": "Input should be a valid UUID",
                            "type": "uuid_parsing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "validation_error": {
                    "summary": "Validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "loc": [
                              "body",
                              "name"
                            ],
                            "msg": "Field required",
                            "type": "missing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Request validation failed"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Update current user profile",
        "tags": [
          "profile"
        ]
      }
    },
    "/api/service-accounts": {
      "get": {
        "description": "List all service accounts accessible to the current user.\n\nReturns organization accounts for your organization plus all system accounts.\n\nContext:\n    - Returns accounts from your organization\n    - Includes all system accounts\n    - Does not include accounts from other organizations\n\nRelated Endpoints:\n    - GET /service-accounts/{id} - Get specific account details\n    - POST /service-accounts - Create new account",
        "operationId": "list_service_accounts_api_service_accounts_get",
        "parameters": [
          {
            "description": "Number of records to skip for pagination",
            "example": 0,
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Number of records to skip for pagination",
              "minimum": 0,
              "title": "Offset",
              "type": "integer"
            }
          },
          {
            "description": "Maximum number of records to return",
            "example": 100,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "description": "Maximum number of records to return",
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ServiceAccountResponse"
                  },
                  "title": "Response List Service Accounts Api Service Accounts Get",
                  "type": "array"
                }
              }
            },
            "description": "List of service accounts retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List all service accounts",
        "tags": [
          "service-accounts"
        ]
      },
      "post": {
        "description": "Create a new service account.\n\nCreates a new service account and returns the full authentication token.\n**Important**: The full token is only shown once during creation. Store it securely.\n\nContext:\n    - This API creates organization-scoped accounts only\n    - Token format: saf_{type}_{org_prefix}_{account_id_prefix}_{random_part}\n\nUse Cases:\n    - Create API integration accounts\n    - Set up automated workflows\n    - Enable programmatic access to platform resources\n\nRelated Endpoints:\n    - GET /service-accounts - List all accounts\n    - GET /service-accounts/{id} - Get account details\n    - PATCH /service-accounts/{id} - Update account",
        "operationId": "create_service_account_api_service_accounts_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServiceAccountCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceAccountCreateResponse"
                }
              }
            },
            "description": "Service account created successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid input data"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create a new service account",
        "tags": [
          "service-accounts"
        ]
      }
    },
    "/api/service-accounts/{service_account_id}": {
      "delete": {
        "description": "Delete a service account.\n\nPermanently deletes a service account. This action cannot be undone.\n\nContext:\n    - Hard delete (permanent removal)\n    - Cannot be undone\n    - Use deactivate if you want to temporarily disable access\n\nRelated Endpoints:\n    - POST /service-accounts/{id}/deactivate - Temporarily disable account",
        "operationId": "delete_service_account_api_service_accounts__service_account_id__delete",
        "parameters": [
          {
            "description": "UUID of the service account to delete",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "service_account_id",
            "required": true,
            "schema": {
              "description": "UUID of the service account to delete",
              "format": "uuid",
              "title": "Service Account Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Service account deleted successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks access to this account"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Delete a service account",
        "tags": [
          "service-accounts"
        ]
      },
      "get": {
        "description": "Get details for a specific service account.\n\nReturns service account information including status and token prefix.\nNote: Full token is never returned after creation.\n\nContext:\n    - Users can only access accounts from their organization\n    - System accounts are accessible to all users\n    - Token prefix is shown for identification purposes\n\nRelated Endpoints:\n    - GET /service-accounts - List all accounts\n    - PATCH /service-accounts/{id} - Update account",
        "operationId": "get_service_account_api_service_accounts__service_account_id__get",
        "parameters": [
          {
            "description": "UUID of the service account to retrieve",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "service_account_id",
            "required": true,
            "schema": {
              "description": "UUID of the service account to retrieve",
              "format": "uuid",
              "title": "Service Account Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceAccountResponse"
                }
              }
            },
            "description": "Service account retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks access to this account"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get a specific service account",
        "tags": [
          "service-accounts"
        ]
      },
      "patch": {
        "description": "Update a service account.\n\nUpdates name and/or description of a service account.\nStatus updates should use activate/deactivate endpoints.\n\nContext:\n    - Can update name and description\n    - Cannot update token (use delete + create for new token)\n    - Cannot update status (use activate/deactivate endpoints)\n\nRelated Endpoints:\n    - POST /service-accounts/{id}/activate - Activate account\n    - POST /service-accounts/{id}/deactivate - Deactivate account",
        "operationId": "update_service_account_api_service_accounts__service_account_id__patch",
        "parameters": [
          {
            "description": "UUID of the service account to update",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "service_account_id",
            "required": true,
            "schema": {
              "description": "UUID of the service account to update",
              "format": "uuid",
              "title": "Service Account Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ServiceAccountUpdateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceAccountResponse"
                }
              }
            },
            "description": "Service account updated successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks access to this account"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Update a service account",
        "tags": [
          "service-accounts"
        ]
      }
    },
    "/api/service-accounts/{service_account_id}/activate": {
      "post": {
        "description": "Activate a service account.\n\nChanges the service account status to 'active', allowing it to authenticate.\n\nContext:\n    - Only active accounts can authenticate\n    - Activation is immediate\n    - Can activate already-active accounts (idempotent)\n\nRelated Endpoints:\n    - POST /service-accounts/{id}/deactivate - Deactivate account",
        "operationId": "activate_service_account_api_service_accounts__service_account_id__activate_post",
        "parameters": [
          {
            "description": "UUID of the service account to activate",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "service_account_id",
            "required": true,
            "schema": {
              "description": "UUID of the service account to activate",
              "format": "uuid",
              "title": "Service Account Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceAccountResponse"
                }
              }
            },
            "description": "Service account activated successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks access to this account"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Activate a service account",
        "tags": [
          "service-accounts"
        ]
      }
    },
    "/api/service-accounts/{service_account_id}/api-keys": {
      "get": {
        "description": "List all API keys associated with a specific service account.\n\nReturns all API keys that belong to the specified service account.\nThe user must have access to the service account to view its API keys.\n\nContext:\n    - Only returns API keys for the specified service account\n    - User must have access to the service account\n    - Returns empty list if no API keys exist for the account\n\nRelated Endpoints:\n    - GET /service-accounts/{id} - Get service account details\n    - POST /api-keys - Create a new API key",
        "operationId": "list_service_account_api_keys_api_service_accounts__service_account_id__api_keys_get",
        "parameters": [
          {
            "description": "UUID of the service account to list API keys for",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "service_account_id",
            "required": true,
            "schema": {
              "description": "UUID of the service account to list API keys for",
              "format": "uuid",
              "title": "Service Account Id",
              "type": "string"
            }
          },
          {
            "description": "Number of records to skip for pagination",
            "example": 0,
            "in": "query",
            "name": "offset",
            "required": false,
            "schema": {
              "default": 0,
              "description": "Number of records to skip for pagination",
              "minimum": 0,
              "title": "Offset",
              "type": "integer"
            }
          },
          {
            "description": "Maximum number of records to return",
            "example": 100,
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 100,
              "description": "Maximum number of records to return",
              "maximum": 1000,
              "minimum": 1,
              "title": "Limit",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ApiKeyResponse"
                  },
                  "title": "Response List Service Account Api Keys Api Service Accounts  Service Account Id  Api Keys Get",
                  "type": "array"
                }
              }
            },
            "description": "List of API keys retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks access to this service account"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List API keys for a service account",
        "tags": [
          "service-accounts"
        ]
      },
      "post": {
        "description": "Create a new API key for a specific service account.\n\nCreates a new API key associated with the specified service account and returns\nthe full authentication token.\n**Important**: The full token is only shown once during creation. Store it securely.\n\nContext:\n    - The user must have access to the service account\n    - System accounts are not visible to API users due to RLS restrictions\n    - All accessible service accounts are organization accounts\n    - Uses 'organization_service_account' identity type\n\nRelated Endpoints:\n    - GET /service-accounts/{id}/api-keys - List API keys for a service account\n    - GET /service-accounts/{id} - Get service account details",
        "operationId": "create_service_account_api_key_api_service_accounts__service_account_id__api_keys_post",
        "parameters": [
          {
            "description": "UUID of the service account to create an API key for",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "service_account_id",
            "required": true,
            "schema": {
              "description": "UUID of the service account to create an API key for",
              "format": "uuid",
              "title": "Service Account Id",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApiKeyCreateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyCreateResponse"
                }
              }
            },
            "description": "API key created successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid input data"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks access to this service account"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create an API key for a service account",
        "tags": [
          "service-accounts"
        ]
      }
    },
    "/api/service-accounts/{service_account_id}/deactivate": {
      "post": {
        "description": "Deactivate a service account.\n\nChanges the service account status to 'inactive', preventing authentication.\n\nContext:\n    - Inactive accounts cannot authenticate\n    - Deactivation is immediate\n    - Can deactivate already-inactive accounts (idempotent)\n\nRelated Endpoints:\n    - POST /service-accounts/{id}/activate - Activate account",
        "operationId": "deactivate_service_account_api_service_accounts__service_account_id__deactivate_post",
        "parameters": [
          {
            "description": "UUID of the service account to deactivate",
            "example": "550e8400-e29b-41d4-a716-446655440000",
            "in": "path",
            "name": "service_account_id",
            "required": true,
            "schema": {
              "description": "UUID of the service account to deactivate",
              "format": "uuid",
              "title": "Service Account Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceAccountResponse"
                }
              }
            },
            "description": "Service account deactivated successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks access to this account"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Deactivate a service account",
        "tags": [
          "service-accounts"
        ]
      }
    },
    "/api/sso": {
      "delete": {
        "description": "Remove SSO configuration for the current user's organization.\n\nDisables the SSO configuration by setting is_active=False. This is a soft delete\nthat preserves the configuration for potential future reactivation.\n\nContext:\n    - Soft delete (sets is_active=False, preserves data)\n    - Users will fall back to password authentication\n    - Configuration can be reactivated by creating a new SSO config\n    - Does not delete the Supabase SSO provider\n\nImpact:\n    - Immediate: Users can no longer authenticate via SSO\n    - Existing sessions may remain active until expiration\n    - Users must use password authentication\n    - Organization admins can recreate SSO configuration\n\nSecurity Considerations:\n    - Disabling SSO immediately affects all users in configured domains\n    - Ensure alternative authentication methods are available\n    - Consider communication to affected users before disabling\n\nUse Cases:\n    - Temporary SSO maintenance or troubleshooting\n    - Migrating to a different SSO provider\n    - Emergency access restoration via password auth\n    - Decommissioning SSO integration\n\nRelated Endpoints:\n    - POST /auth/sso - Create new SSO configuration\n    - GET /auth/sso - Check current configuration status",
        "operationId": "delete_sso_config_api_sso_delete",
        "responses": {
          "204": {
            "description": "SSO configuration disabled successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "SSO configuration not found for organization"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Remove SSO configuration for organization",
        "tags": [
          "sso"
        ]
      },
      "get": {
        "description": "Get SSO configuration for the current user's organization.\n\nReturns the current SAML SSO configuration including domains, metadata settings,\nand attribute mappings.\n\nContext:\n    - Returns SSO configuration for the authenticated user's organization\n    - Includes both active and inactive configurations\n    - Shows configuration stored in local database\n\nResponse Data:\n    - sso_provider_id: Supabase SSO provider identifier\n    - domains: Email domains using this SSO provider\n    - metadata_url: URL for SAML metadata (if configured)\n    - attribute_mapping: SAML attribute to user field mappings\n    - is_active: Whether the SSO provider is currently enabled\n\nUse Cases:\n    - Reviewing current SSO configuration\n    - Checking SSO status before updates\n    - Auditing SSO provider settings\n\nRelated Endpoints:\n    - POST /auth/sso - Create SSO configuration\n    - PATCH /auth/sso - Update SSO metadata",
        "operationId": "get_sso_config_api_sso_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SSOOrganizationResponse"
                }
              }
            },
            "description": "SSO configuration retrieved successfully"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "SSO configuration not found for organization"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get SSO configuration for organization",
        "tags": [
          "sso"
        ]
      },
      "patch": {
        "description": "Update SSO metadata configuration for the current user's organization.\n\nUpdates metadata-related fields only. This endpoint is restricted to updating:\n- metadata_url: URL for fetching SAML metadata\n- metadata_xml: Raw SAML metadata XML content\n- domains: Email domains that should use this SSO provider\n- attribute_mapping: SAML attribute to user profile field mappings\n\nContext:\n    - Only metadata-related fields can be updated via this endpoint\n    - Updates both Supabase SSO provider and local database\n    - Changes are applied immediately\n    - Cannot update provider ID or organization association\n\nMetadata Update Rules:\n    - Provide either metadata_url OR metadata_xml, not both\n    - Setting metadata_url clears any existing metadata_xml\n    - Setting metadata_xml clears any existing metadata_url\n    - Domains can be added, removed, or modified\n    - Attribute mappings are completely replaced if provided\n\nUse Cases:\n    - Updating SAML metadata after IdP changes\n    - Adding or removing email domains\n    - Modifying attribute mapping for user profiles\n    - Rotating SAML certificates or endpoints\n\nRelated Endpoints:\n    - GET /auth/sso - Get current configuration\n    - DELETE /auth/sso - Remove SSO configuration",
        "operationId": "update_sso_config_api_sso_patch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SSOProviderUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SSOOrganizationResponse"
                }
              }
            },
            "description": "SSO configuration updated successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid metadata configuration"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "SSO configuration not found for organization"
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "type_error": {
                    "summary": "Type validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "input": "not-a-uuid",
                            "loc": [
                              "path",
                              "flow_id"
                            ],
                            "msg": "Input should be a valid UUID",
                            "type": "uuid_parsing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "validation_error": {
                    "summary": "Validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "loc": [
                              "body",
                              "name"
                            ],
                            "msg": "Field required",
                            "type": "missing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Request validation failed"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Supabase API error or service unavailable"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Update SSO metadata configuration",
        "tags": [
          "sso"
        ]
      },
      "post": {
        "description": "Create SSO configuration for the current user's organization.\n\nCreates a new SAML SSO provider in Supabase and stores the configuration locally.\nThis is a transactional operation that ensures both Supabase and local database\nare updated atomically.\n\nContext:\n    - Only organization administrators can create SSO configurations\n    - Each organization can have only one SSO configuration\n\nSAML Configuration:\n    - Provide either metadata_url OR metadata_xml, not both\n    - metadata_url: URL where Supabase can fetch SAML metadata\n    - metadata_xml: Raw SAML metadata XML content\n    - domains: Email domains that should authenticate via this provider\n    - attribute_mapping: Maps SAML attributes to user profile fields\n\nRelated Endpoints:\n    - GET /auth/sso - Get current SSO configuration\n    - PATCH /auth/sso - Update SSO metadata\n    - DELETE /auth/sso - Remove SSO configuration",
        "operationId": "create_sso_config_api_sso_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SSOProviderCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SSOOrganizationResponse"
                }
              }
            },
            "description": "SSO configuration created successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid SSO configuration or organization already has SSO"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "type_error": {
                    "summary": "Type validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "input": "not-a-uuid",
                            "loc": [
                              "path",
                              "flow_id"
                            ],
                            "msg": "Input should be a valid UUID",
                            "type": "uuid_parsing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "validation_error": {
                    "summary": "Validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "loc": [
                              "body",
                              "name"
                            ],
                            "msg": "Field required",
                            "type": "missing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Request validation failed"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Supabase API error or service unavailable"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create SSO configuration for organization",
        "tags": [
          "sso"
        ]
      }
    },
    "/api/sso/metadata": {
      "get": {
        "description": "Fetches SAML metadata from external URLs to avoid browser CORS restrictions",
        "operationId": "proxy_saml_metadata_api_sso_metadata_get",
        "parameters": [
          {
            "description": "SAML metadata URL to fetch",
            "in": "query",
            "name": "url",
            "required": true,
            "schema": {
              "description": "SAML metadata URL to fetch",
              "format": "uri",
              "maxLength": 2083,
              "minLength": 1,
              "title": "Url",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataResponse"
                }
              },
              "application/xml": {}
            },
            "description": "SAML metadata XML content"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Invalid or missing metadata URL"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal server error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Proxy SAML metadata to avoid CORS issues",
        "tags": [
          "sso"
        ]
      }
    },
    "/api/task-data": {
      "post": {
        "description": "Analyze a flow definition to extract task output schemas, dynamic data, and validation errors.\n\n**Overview**\nThis endpoint validates a flow definition and returns metadata needed for flow building,\nexecution planning, and UI generation. It processes all tasks in the flow definition to\nextract their output schemas (for type validation), dynamic configuration data (for UI\ndropdowns and conditional fields), and any structural or semantic validation errors.\n\n**Use Cases**\n- **Flow Builder UI**: Get task output schemas for downstream task input validation\n- **Dynamic Configuration**: Retrieve runtime-dependent options (e.g., available spreadsheets, databases)\n- **Flow Validation**: Check for errors before saving or executing a flow\n- **Schema Discovery**: Understand what data each task will produce\n- **Custom Integrations**: Programmatically validate and analyze flow definitions\n\n**How It Works**\n1. Parses and validates the flow definition structure (basic validation)\n2. For each task in the flow:\n   - Loads the task executor implementation\n   - Calls the executor's `get_output_model()` to get the output schema\n   - Calls the executor's dynamic data methods (if available) to get runtime options\n   - Collects any errors encountered during schema/data extraction\n3. If `full_validation=true`, performs additional semantic validation (checks task\n   parameter values, validates connections between tasks, etc.)\n4. Returns all schemas, dynamic data, and validation errors in a single response\n\n**Dynamic Data Explained**\nDynamic data represents configuration options that depend on external state or user\ncredentials. For example:\n- Google Sheets task: List of spreadsheets accessible with user's credentials\n- Database task: List of available tables/columns\n- API task: Available endpoints or data models from connected service\n\n**Validation Levels**\n- **Basic (default)**: Structure validation only (required fields, data types)\n- **Full (`full_validation=true`)**: Includes semantic validation (valid references,\n  parameter constraints, external resource availability)\n\n**Performance Notes**\n- May make external API calls to fetch dynamic data (e.g., Google Sheets API)\n- Response time varies based on number of tasks and external service latency\n- Typical response time: 100ms-2s depending on task executors used\n\n**Related Endpoints**\n- `POST /flows` - Create flow (uses this endpoint's validation internally)\n- `PUT /flows/{flow_id}` - Update flow (uses this endpoint's validation internally)\n- `GET /task-executors` - List available task executors",
        "operationId": "get_task_dynamic_data_api_task_data_post",
        "parameters": [
          {
            "description": "Enable comprehensive semantic validation in addition to basic structural validation. When false (default): Only validates flow structure (required fields, data types, task executor existence). When true: Performs additional validation including: - Task parameter value validation (correct types, valid enums, etc.). - Task connection validation (input/output type compatibility). - Circular dependency detection. - External resource validation (e.g., checking if referenced files exist). Full validation may take longer and make external API calls. Use during flow save/publish operations. Use false (default) for faster validation during editing.",
            "in": "query",
            "name": "full_validation",
            "required": false,
            "schema": {
              "default": false,
              "description": "Enable comprehensive semantic validation in addition to basic structural validation. When false (default): Only validates flow structure (required fields, data types, task executor existence). When true: Performs additional validation including: - Task parameter value validation (correct types, valid enums, etc.). - Task connection validation (input/output type compatibility). - Circular dependency detection. - External resource validation (e.g., checking if referenced files exist). Full validation may take longer and make external API calls. Use during flow save/publish operations. Use false (default) for faster validation during editing.",
              "title": "Full Validation",
              "type": "boolean"
            }
          },
          {
            "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. Adds ~10-50ms latency for schema generation.",
            "in": "query",
            "name": "include_input_schema",
            "required": false,
            "schema": {
              "default": false,
              "description": "Include JSON Schema definitions for input task executors' input structure. Calls get_input_model() to generate dynamic input schemas for form building. Adds ~10-50ms latency for schema generation.",
              "title": "Include Input Schema",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskDynamicDataRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskDynamicDataResponse"
                }
              }
            },
            "description": "Flow definition successfully analyzed"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid flow definition structure"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Analyze flow definition and extract schemas",
        "tags": [
          "task-data"
        ]
      }
    },
    "/api/task-executions": {
      "get": {
        "description": "List task executions with optional filtering by flow execution, task name, or execution index.\n\n**Overview**\nRetrieve task executions across all flows in your organization. Results can be filtered\nby parent flow execution, specific task name, or execution index. Returns task executions\nwith their associated tags for categorization and filtering.\n\n**Filtering Logic**\nMultiple filters are combined with AND logic:\n- flow_execution_id AND task_name \u2192 All executions of a specific task in a flow\n- flow_execution_id AND task_execution_idx \u2192 All tasks at a specific execution index\n- All three filters \u2192 Exact task execution lookup (equivalent to GET /{id})\n\n**Common Query Patterns**\n1. All tasks in a flow execution: ?flow_execution_id={id}\n2. Specific task across retries: ?flow_execution_id={id}&task_name=send_email\n3. First execution of all tasks: ?flow_execution_id={id}&task_execution_idx=0\n4. All task executions (no filters): Returns all executions in organization\n\n**Response Format**\nReturns TaskExecutionWithTagsAPI objects containing:\n- Full task execution details (input, output, error, status)\n- Associated tags (e.g., reviewed, approved, flagged)\n- Metadata (created_at, updated_at, modified_by)\n- Organization context for multi-tenant isolation\n\n**Performance Considerations**\n- Queries are scoped to organization_id via RLS policies (automatic filtering)\n- Add flow_execution_id filter for better query performance on large datasets\n- Unfiltered queries may return large result sets; pagination planned for future\n\n**Tags**\nTask tags provide categorization and workflow state:\n- Tag types: 'review_status', 'approval', 'quality', 'custom'\n- Tags are returned with each task execution for filtering and display\n- Soft-deleted tags are excluded from results\n\n**Related Endpoints**\n- GET /task-executions/{id} - Get single task execution by ID\n- GET /task-tags - List all tags for a flow execution\n- POST /task-executions - Create new task execution",
        "operationId": "list_task_executions_api_task_executions_get",
        "parameters": [
          {
            "description": "Filter task executions by parent flow execution ID. Returns only tasks belonging to the specified flow execution. Combines with other filters using AND logic. Omit to search across all flow executions in your organization.",
            "in": "query",
            "name": "flow_execution_id",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "format": "uuid",
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter task executions by parent flow execution ID. Returns only tasks belonging to the specified flow execution. Combines with other filters using AND logic. Omit to search across all flow executions in your organization.",
              "title": "Flow Execution Id"
            }
          },
          {
            "description": "Filter task executions by exact task name (case-sensitive). Returns all execution attempts of the named task. Useful for tracking retries or finding specific task types. Must match task name exactly as defined in flow definition YAML.",
            "in": "query",
            "name": "task_name",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 200,
                  "minLength": 1,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter task executions by exact task name (case-sensitive). Returns all execution attempts of the named task. Useful for tracking retries or finding specific task types. Must match task name exactly as defined in flow definition YAML.",
              "title": "Task Name"
            }
          },
          {
            "description": "Filter task executions by execution index (zero-based). Returns tasks at a specific execution attempt number. Index 0 = first execution, 1 = first retry, 2 = second retry, etc. Useful for comparing initial vs retry executions or finding specific attempts.",
            "in": "query",
            "name": "task_execution_idx",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "minimum": 0,
                  "type": "integer"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Filter task executions by execution index (zero-based). Returns tasks at a specific execution attempt number. Index 0 = first execution, 1 = first retry, 2 = second retry, etc. Useful for comparing initial vs retry executions or finding specific attempts.",
              "title": "Task Execution Idx"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListTaskExecutionsResponse"
                }
              }
            },
            "description": "List of task executions successfully retrieved"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List task executions with filtering",
        "tags": [
          "task-executions"
        ]
      },
      "post": {
        "description": "Create a new task execution record for a specific task within a flow execution.\n\n**Overview**\nTask executions represent individual task invocations within a flow execution. Each task\nin a flow can be executed multiple times (retries, loops), tracked by task_execution_idx.\nThis endpoint is primarily used by system workers to report task execution state.\n\n**Resource Hierarchy**\nOrganization \u2192 Flow \u2192 Flow Execution \u2192 Task Execution\n\n**Lifecycle**\nTask executions progress through states: queued \u2192 running \u2192 completed/failed\n- queued: Task scheduled but not yet started\n- running: Task currently executing\n- completed: Task finished successfully with output\n- failed: Task encountered an error\n\n**Use Cases**\n- Workers reporting task execution start/completion\n- Recording task outputs for downstream tasks\n- Tracking task execution history and retries\n- Debugging failed workflow executions\n\n**Idempotency**\nThis endpoint is idempotent based on (flow_execution_id, task_name, task_execution_idx).\nIf a task execution with these identifiers exists, it will be updated rather than creating\na duplicate.\n\n**Performance Notes**\nWebSocket notifications are processed in the background to ensure fast worker responses.\nThe endpoint returns immediately after database write; notifications are async.\n\n**Related Endpoints**\n- GET /task-executions - List task executions with filtering\n- PUT /task-executions - Update existing task execution and optionally re-execute flow\n- GET /flow-executions/{id} - View parent flow execution",
        "operationId": "create_task_execution_api_task_executions_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTaskExecutionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskExecutionAPI"
                }
              }
            },
            "description": "Task execution created successfully"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid status value or missing required fields"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create a task execution record",
        "tags": [
          "task-executions"
        ]
      },
      "put": {
        "description": "Update an existing task execution and optionally trigger flow re-execution.\n\n**Overview**\nThis endpoint updates a task execution's output, status, or other fields, and can\nautomatically propagate changes to downstream tasks by re-executing the flow.\nCommonly used for human-in-the-loop workflows or manual corrections.\n\n**Update Behavior**\nWhen updating a task execution, the system:\n1. Updates the task execution record in the database\n2. Recalculates task output summaries for the parent flow execution\n3. Identifies downstream tasks that depend on the updated task (stale tasks)\n4. Optionally re-executes those stale tasks if execute_flow=true\n\n**Stale Task Detection**\nTasks become \"stale\" when an upstream task they depend on changes. The system\nanalyzes task dependencies from the flow definition to determine affected tasks.\nOnly stale tasks are re-executed, not the entire flow.\n\n**Use Cases**\n- Correcting task outputs after manual review (human-in-the-loop)\n- Updating task results based on external feedback\n- Fixing data quality issues in completed tasks\n- Triggering partial flow re-execution after corrections\n\n**Concurrency**\nUpdates use optimistic locking via updated_at timestamp. Concurrent updates to the\nsame task execution may result in last-write-wins behavior.\n\n**Related Endpoints**\n- POST /task-executions - Create new task execution\n- POST /flow-executions/{id}/execute - Re-execute entire flow\n- GET /task-executions - List task executions with filtering",
        "operationId": "update_task_execution_api_task_executions_put",
        "parameters": [
          {
            "description": "Whether to re-execute downstream tasks after updating this task execution. If true, identifies all tasks that depend on this task (stale tasks) and triggers their re-execution with updated inputs. If false, only updates the task execution record without propagation. Default: false for safety (explicit opt-in for re-execution).",
            "in": "query",
            "name": "execute_flow",
            "required": false,
            "schema": {
              "default": false,
              "description": "Whether to re-execute downstream tasks after updating this task execution. If true, identifies all tasks that depend on this task (stale tasks) and triggers their re-execution with updated inputs. If false, only updates the task execution record without propagation. Default: false for safety (explicit opt-in for re-execution).",
              "title": "Execute Flow",
              "type": "boolean"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskExecutionAPI"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskExecutionAPI"
                }
              }
            },
            "description": "Task execution updated successfully"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Update task execution and optionally re-execute flow",
        "tags": [
          "task-executions"
        ]
      }
    },
    "/api/task-executions/{task_execution_id}": {
      "get": {
        "description": "Retrieve a specific task execution by its unique identifier.\n\n**Overview**\nFetches a single task execution record with all details including input parameters,\noutput data, error information, and execution metadata. Used for detailed inspection\nof task execution results and debugging.\n\n**Resource Identification**\nTask executions are uniquely identified by UUID (id field). This is distinct from\nthe composite key (flow_execution_id, task_name, task_execution_idx) used for\ncreation and filtering.\n\n**Use Cases**\n- Debugging failed task executions (inspect error field and stack trace)\n- Retrieving task output for display or downstream processing\n- Auditing task execution history and modifications\n- Viewing detailed execution metadata (timestamps, modified_by)\n\n**Related Endpoints**\n- GET /task-executions - List task executions with filtering\n- PUT /task-executions - Update task execution\n- GET /flow-executions/{id} - View parent flow execution with all tasks",
        "operationId": "get_task_execution_api_task_executions__task_execution_id__get",
        "parameters": [
          {
            "description": "Unique identifier of the task execution to retrieve. This is the UUID assigned when the task execution was created. Task executions are scoped to organization via RLS; attempting to access another organization's task execution returns 404.",
            "in": "path",
            "name": "task_execution_id",
            "required": true,
            "schema": {
              "description": "Unique identifier of the task execution to retrieve. This is the UUID assigned when the task execution was created. Task executions are scoped to organization via RLS; attempting to access another organization's task execution returns 404.",
              "format": "uuid",
              "title": "Task Execution Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskExecutionAPI"
                }
              }
            },
            "description": "Task execution successfully retrieved"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - User lacks permission to access this task execution"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Retrieve a specific task execution",
        "tags": [
          "task-executions"
        ]
      }
    },
    "/api/task-executors": {
      "get": {
        "description": "List all available task executors for workflow composition.\n\n**Overview**\nTask executors are reusable building blocks for workflows. Each executor performs\na specific operation (send email, extract data, classify documents, etc.). This\nendpoint provides discovery of all registered executors with their schemas,\nenabling programmatic flow builder UIs and validation.\n\n**What are Task Executors?**\nTask executors are typed workflow components that:\n- Accept configuration parameters (e.g., API keys, endpoints, templates)\n- Optionally receive runtime input data (for input executors)\n- Perform an operation (API call, data transformation, ML inference)\n- Return structured output for downstream tasks\n- Support scheduling (for compatible executors)\n\n**Executor Categories**\n1. Input Executors (is_input_task_executor=true):\n   - Trigger flows from external sources\n   - Examples: receive_email, webhook_receive, receive_file\n   - Have flow_input_schema defining incoming data\n\n2. Processing Executors (is_input_task_executor=false):\n   - Transform data within flows\n   - Examples: doc_to_structured, classify_text, format_data\n   - No flow_input_schema (work on task outputs)\n\n3. Output Executors:\n   - Send data to external systems\n   - Examples: send_email, webhook_notification, external_db\n   - Can be terminal tasks in flows\n\n4. Schedulable Executors (is_schedulable_executor=true):\n   - Support time-based triggers\n   - Examples: scheduled_db_query\n   - Can run on cron schedules\n\n**Response Format**\nReturns array of TaskExecutorResponse objects containing:\n- Executor metadata (name, description, agent prompt)\n- Configuration schema (parameters_schema) - JSON Schema for static config\n- Runtime input schema (flow_input_schema) - JSON Schema for dynamic data\n- Capability flags (is_input_task_executor, is_schedulable_executor)\n\n**Schema Usage**\n- parameters_schema: Generate configuration UI, validate flow definitions\n- flow_input_schema: Validate incoming webhook/email/file data\n- Both schemas follow JSON Schema Draft 2020-12 specification\n\n**Use Cases**\n- Flow Builder UI: Display available task types with autocomplete\n- AI Agents: Use agent_prompt to intelligently select executors\n- Validation: Check flow definitions against executor schemas\n- Documentation: Generate API reference from executor metadata\n- Client SDKs: Generate type-safe executor configuration classes\n\n**Executor Registration**\nTask executors are registered via TaskExecutorsManager (flow-sdk).\nTo add custom executors, see flow-sdk/src/flow_sdk/task_executors/README.md\n\n**Performance Notes**\n- Response cached for 5 minutes (executors rarely change)\n- Typical response size: ~50-100 executors, 200-500KB\n- Schemas can be large (1-10KB per executor)\n- Consider client-side caching for production use\n\n**Related Endpoints**\n- POST /flows - Create flow using discovered executors\n- GET /flows/{id} - View flow definition with executor references\n- POST /task-data - Get task output schemas for flow validation",
        "operationId": "get_task_executors_api_task_executors_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/TaskExecutorResponse"
                  },
                  "title": "Response Get Task Executors Api Task Executors Get",
                  "type": "array"
                }
              }
            },
            "description": "List of task executors successfully retrieved"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List all available task executors",
        "tags": [
          "task-executors"
        ]
      }
    },
    "/api/task-outputs": {
      "get": {
        "description": "List all task outputs across all flow executions in your organization.\n\nRetrieve all task output records for your organization. Returns complete output data\nincluding summary, full output, tags, and status for each task that has produced output.\nResults are ordered by creation time (most recent first).\n\n## Important: No Pagination\n\nThis endpoint currently returns **ALL** task outputs in the organization without pagination.\nFor organizations with many flow executions, this may return large result sets. Pagination\nis planned for a future release. Consider using `GET /flow-executions/{id}` to filter by\nspecific flow execution.\n\n## What Are Task Outputs\n\nTask outputs represent the summarized, structured results of completed tasks:\n- **summary**: Structured data optimized for UI display and querying\n- **output**: Full output data for downstream task consumption\n- **tags**: Categorization metadata for filtering and organization\n- **status**: Task execution state when output was created\n\n## Filtering and Querying\n\nCurrently no query parameters are supported. To filter by flow execution, use\n`GET /flow-executions/{id}` which includes task outputs in response.\n\n**Planned enhancements**:\n- Filter by flow_execution_id\n- Filter by task_name\n- Filter by status\n- Pagination (limit, starting_after)\n- Date range filtering\n\n## Performance Considerations\n\n- Query returns all outputs (potentially thousands of records)\n- Results ordered by created_at desc (newest first)\n- Database query scoped to organization via RLS policies\n- Consider using `GET /flow-executions/{id}` for filtered results\n\n## Common Use Cases\n\n- Export all task outputs for audit or analysis\n- Debug output issues across multiple executions\n- Build organization-wide analytics dashboards\n- Bulk data extraction for external systems\n\n## Related Endpoints\n\n- `GET /task-outputs/{id}` - Get single task output by ID\n- `GET /flow-executions/{id}` - Get flow execution with filtered task outputs\n- `GET /task-executions` - Get full task execution details",
        "operationId": "list_task_outputs_api_task_outputs_get",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/TaskOutputAPI"
                  },
                  "title": "Response List Task Outputs Api Task Outputs Get",
                  "type": "array"
                }
              }
            },
            "description": "List of task outputs successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List all task outputs",
        "tags": [
          "task-outputs"
        ]
      },
      "post": {
        "description": "Create a task output record for a completed task and notify connected clients.\n\nTask outputs represent the processed, summarized results of task executions. Unlike\ntask executions which track the full execution lifecycle (input, output, error, status),\ntask outputs focus on the final output data formatted for display, downstream consumption,\nand workflow decisions.\n\n## What Are Task Outputs\n\nTask outputs serve multiple purposes:\n- **Structured Results**: Store task results in a queryable format via the summary field\n- **Full Output Data**: Provide complete output for downstream task consumption\n- **Metadata Tracking**: Associate tags for categorization and filtering\n- **Real-time Updates**: Enable WebSocket notifications for UI progress tracking\n- **Workflow Logic**: Support decision-making based on task outcomes\n\n## Relationship to Task Executions\n\n- **Task Execution**: Full execution record (input, output, error, retries, timing)\n- **Task Output**: Summarized result optimized for querying and display\n- One task execution typically produces one task output upon completion\n- Task outputs are created by system workers after task completion\n\n## Notification Behavior\n\nThis endpoint triggers two types of WebSocket notifications asynchronously:\n1. **Flow-level notification**: Updates all clients subscribed to the flow's WebSocket\n2. **Enhanced notification**: Broadcasts to summary-watching clients for real-time updates\n\nNotifications are processed in the background to ensure fast response times (< 100ms).\n\n## Common Use Cases\n\n- Workers reporting task completion with structured output\n- Storing task results for display in execution history UI\n- Providing data for downstream task inputs in workflows\n- Triggering real-time progress updates\n- Enabling workflow decisions based on task outcomes\n\n## Related Endpoints\n\n- `GET /task-outputs` - List all task outputs\n- `GET /task-outputs/{id}` - Get single task output\n- `GET /flow-executions/{id}` - View parent flow execution\n- `GET /task-executions` - View full task execution details",
        "operationId": "create_task_output_api_task_outputs_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TaskOutput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskOutputAPI"
                }
              }
            },
            "description": "Task output successfully created"
          },
          "400": {
            "content": {
              "application/json": {
                "examples": {
                  "generic": {
                    "summary": "Generic bad request",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Invalid request parameters"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "missing_field": {
                    "summary": "Missing required field",
                    "value": {
                      "error": {
                        "code": "bad_request",
                        "message": "Organization ID is required"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid input parameters or request format"
          },
          "404": {
            "description": "Flow execution not found for the provided flow_execution_id"
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "type_error": {
                    "summary": "Type validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "input": "not-a-uuid",
                            "loc": [
                              "path",
                              "flow_id"
                            ],
                            "msg": "Input should be a valid UUID",
                            "type": "uuid_parsing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "validation_error": {
                    "summary": "Validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "loc": [
                              "body",
                              "name"
                            ],
                            "msg": "Field required",
                            "type": "missing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Request validation failed"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Create task output",
        "tags": [
          "task-outputs"
        ]
      }
    },
    "/api/task-outputs/{task_output_id}": {
      "get": {
        "description": "Retrieve a specific task output by its unique identifier.\n\nFetch a single task output record with complete output data, summary, tags, and metadata.\nUsed for inspecting individual task results, debugging, and retrieving output for\ndownstream processing.\n\n## Resource Identification\n\nTask outputs are uniquely identified by UUID (id field). To find task outputs by\nother criteria (flow execution, task name), use `GET /flow-executions/{id}` or\n`GET /task-outputs` (list all).\n\n## What You'll Get\n\n- **summary**: Structured task output summary for display\n- **output**: Full output data produced by task\n- **tags**: Associated metadata tags\n- **status**: Task execution state when output was created\n- **Timestamps**: created_at, updated_at for audit trail\n- **Organization context**: organization_id for multi-tenant isolation\n\n## Common Use Cases\n\n- Inspect task output for debugging or validation\n- Retrieve output data for manual review or corrections\n- Audit task execution history\n- Display detailed task results in UI\n\n## Related Endpoints\n\n- `GET /task-outputs` - List all task outputs\n- `GET /flow-executions/{id}` - View parent flow execution with all outputs\n- `GET /task-executions/{id}` - View full task execution details",
        "operationId": "get_task_output_api_task_outputs__task_output_id__get",
        "parameters": [
          {
            "description": "Unique identifier of the task output to retrieve. UUID assigned when task output was created. Task outputs are scoped to organization; attempting to access another organization's output returns 404.",
            "in": "path",
            "name": "task_output_id",
            "required": true,
            "schema": {
              "description": "Unique identifier of the task output to retrieve. UUID assigned when task output was created. Task outputs are scoped to organization; attempting to access another organization's output returns 404.",
              "examples": [
                "123e4567-e89b-12d3-a456-426614174000"
              ],
              "format": "uuid",
              "title": "Task Output Id",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TaskOutputAPI"
                }
              }
            },
            "description": "Task output successfully retrieved"
          },
          "401": {
            "content": {
              "application/json": {
                "examples": {
                  "invalid_token": {
                    "summary": "Invalid or expired token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Invalid authentication token"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "missing_token": {
                    "summary": "Missing authentication token",
                    "value": {
                      "error": {
                        "code": "unauthorized",
                        "message": "Authentication required"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unauthorized - Missing or invalid authentication credentials"
          },
          "403": {
            "content": {
              "application/json": {
                "examples": {
                  "insufficient_permissions": {
                    "summary": "Insufficient permissions",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "You do not have permission to access this resource"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "wrong_organization": {
                    "summary": "Resource belongs to different organization",
                    "value": {
                      "error": {
                        "code": "forbidden",
                        "message": "This resource belongs to a different organization"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Forbidden - Insufficient permissions to access this resource"
          },
          "404": {
            "description": "Task output not found or belongs to a different organization"
          },
          "422": {
            "content": {
              "application/json": {
                "examples": {
                  "type_error": {
                    "summary": "Type validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "input": "not-a-uuid",
                            "loc": [
                              "path",
                              "flow_id"
                            ],
                            "msg": "Input should be a valid UUID",
                            "type": "uuid_parsing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "validation_error": {
                    "summary": "Validation error",
                    "value": {
                      "error": {
                        "code": "validation_error",
                        "details": [
                          {
                            "loc": [
                              "body",
                              "name"
                            ],
                            "msg": "Field required",
                            "type": "missing"
                          }
                        ],
                        "message": "Request validation failed"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Unprocessable Entity - Request validation failed"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Get task output by ID",
        "tags": [
          "task-outputs"
        ]
      }
    },
    "/api/task-tags": {
      "get": {
        "description": "List all active tags for task executions within a flow execution.\n\n**Overview**\nRetrieve tags associated with task executions in a specific flow execution.\nResults can be filtered to a single task or return all tasks' tags. Only\nactive tags are returned; soft-deleted tags (status='deleted') are excluded.\n\n**What are Task Tags?**\nTask tags provide flexible categorization and workflow state for task executions:\n- Review status: 'reviewed', 'approved', 'rejected'\n- Quality flags: 'quality_checked', 'flagged', 'verified'\n- Custom categories: 'priority_high', 'customer_acme', 'requires_attention'\nEach tag includes optional metadata for context (reviewer name, notes, etc.)\n\n**Filtering Logic**\nQuery parameters combine with AND logic:\n- flow_execution_id (required): Return tags for this flow execution\n- task_name (optional): Filter to tags for a specific task\nWithout task_name: Returns all tags across all tasks in the flow execution\n\n**Common Query Patterns**\n1. All tags in flow execution:\n   GET /task-tags?flow_execution_id={id}\n\n2. Tags for specific task:\n   GET /task-tags?flow_execution_id={id}&task_name=send_email\n\n3. Check if task reviewed:\n   GET /task-tags?flow_execution_id={id}&task_name=extract_data\n   Filter results where tag='reviewed'\n\n**Response Format**\nReturns array of FlowTaskTagAPI objects with:\n- Tag identification: tag, tag_type, task_name\n- Metadata: tag_metadata (JSON object for custom data)\n- Lifecycle: created_at, updated_at, modified_by\n- Status: Always 'active' (deleted tags excluded)\n- Organization context: organization_id for tenant isolation\n\n**Tag Types and Usage**\nCommon tag_type values:\n- 'review_status': Workflow state ('reviewed', 'approved', 'rejected')\n- 'quality': Quality assurance ('quality_checked', 'flagged')\n- 'priority': Business priority ('high', 'medium', 'low')\n- 'custom': Domain-specific categories\n\n**Performance Considerations**\n- Queries scoped by organization_id via RLS (automatic filtering)\n- Indexes on (flow_execution_id, task_name, status) for fast lookups\n- Typical response: 5-50 tags per flow execution\n- Soft-deleted tags excluded at query time (no filtering overhead)\n\n**Use Cases**\n- Display task status in UI (show 'reviewed' badge)\n- Filter tasks by approval state (find all 'approved' tasks)\n- Audit workflow progression (who reviewed what, when)\n- Custom business logic (trigger actions based on tag presence)\n\n**Error Scenarios**\n- 400 Bad Request: Invalid UUID format for flow_execution_id\n- 403 Forbidden: User lacks permission to access flow execution's organization\n- 404 Not Found: flow_execution_id doesn't exist\nNote: Missing task_name is NOT an error; returns empty array\n\n**Related Endpoints**\n- PATCH /task-tags - Add/remove tags\n- GET /task-executions - List task executions (includes tags via TaskExecutionWithTagsAPI)\n- GET /flow-executions/{id} - View parent flow execution",
        "operationId": "list_task_tags_api_task_tags_get",
        "parameters": [
          {
            "description": "Unique identifier of the flow execution to query tags from. Required parameter; returns all active tags for this execution. Combine with task_name to filter to a specific task. \n\nFiltering: Queries automatically scoped to user's organization via RLS. Attempting to access another organization's execution returns 404. \n\nResponse: All active tags (status='active') for the execution. Soft-deleted tags (status='deleted') are excluded automatically.",
            "in": "query",
            "name": "flow_execution_id",
            "required": true,
            "schema": {
              "description": "Unique identifier of the flow execution to query tags from. Required parameter; returns all active tags for this execution. Combine with task_name to filter to a specific task. \n\nFiltering: Queries automatically scoped to user's organization via RLS. Attempting to access another organization's execution returns 404. \n\nResponse: All active tags (status='active') for the execution. Soft-deleted tags (status='deleted') are excluded automatically.",
              "format": "uuid",
              "title": "Flow Execution Id",
              "type": "string"
            }
          },
          {
            "description": "Optional task name to filter tags by specific task. Case-sensitive; must match task name exactly as defined in flow YAML. Omit to return tags for all tasks in the flow execution. \n\nFiltering behavior:\n- Specified: Returns only tags for this task_name\n- Omitted: Returns tags for all tasks in flow execution\n\nCombines with flow_execution_id using AND logic. \n\nExample: task_name='extract_data' returns tags only for that task. Useful for checking task-specific workflow states (is task reviewed?).",
            "in": "query",
            "name": "task_name",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "maxLength": 200,
                  "minLength": 1,
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Optional task name to filter tags by specific task. Case-sensitive; must match task name exactly as defined in flow YAML. Omit to return tags for all tasks in the flow execution. \n\nFiltering behavior:\n- Specified: Returns only tags for this task_name\n- Omitted: Returns tags for all tasks in flow execution\n\nCombines with flow_execution_id using AND logic. \n\nExample: task_name='extract_data' returns tags only for that task. Useful for checking task-specific workflow states (is task reviewed?).",
              "title": "Task Name"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/FlowTaskTagAPI"
                  },
                  "title": "Response List Task Tags Api Task Tags Get",
                  "type": "array"
                }
              }
            },
            "description": "List of task tags successfully retrieved"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "List active task tags for a flow execution",
        "tags": [
          "task-tags"
        ]
      },
      "patch": {
        "description": "Add or remove tags from task executions in batch operations.\n\n**Overview**\nTask tags provide flexible categorization and workflow state tracking for task executions.\nTags enable custom workflows like review/approval processes, quality assurance, and\nbusiness-specific categorization. This endpoint supports batch operations to efficiently\nadd or remove multiple tags in a single request.\n\n**What are Task Tags?**\nTask tags are key-value metadata attached to task executions for:\n- Workflow state tracking: 'reviewed', 'approved', 'rejected'\n- Quality assurance: 'quality_checked', 'flagged', 'verified'\n- Custom categorization: 'priority_high', 'customer_vip', 'requires_attention'\n- Audit trails: Track who reviewed what and when (via tag_metadata)\n\n**Batch Operations**\nThis endpoint accepts an array of tag operations in a single request:\n- operation='add': Creates new tag (idempotent - returns 'already_exists' if duplicate)\n- operation='remove': Soft-deletes tag (sets status='deleted')\n- Mixed operations: Can add and remove different tags in same request\n- Atomic processing: All operations succeed or all fail\n\n**Idempotency**\nAdding an existing tag returns status='already_exists' without error.\nRemoving a non-existent tag returns status='not_found' without error.\nThis enables safe retries and prevents duplicate tag creation.\n\n**Soft Delete Behavior**\nTags are never hard-deleted. Removal sets status='deleted' and records:\n- updated_at: Timestamp of deletion\n- modified_by: User/service that performed deletion\nSoft-deleted tags are excluded from all list queries automatically.\n\n**Use Cases**\n1. Human-in-the-loop workflows: Tag tasks as 'reviewed' after manual inspection\n2. Approval chains: Track 'pending_approval', 'approved', 'rejected' states\n3. Quality control: Flag suspicious outputs with 'requires_review' tag\n4. Custom business logic: Apply domain-specific tags for routing/filtering\n\n**Error Scenarios**\n- 404 Not Found: flow_execution_id doesn't exist or belongs to different organization\n- 403 Forbidden: User lacks permission to modify tags in this organization\n- 400 Bad Request: Invalid operation value or malformed request\n\n**Performance Notes**\nBatch operations are optimized with a single database transaction.\nAll tag additions/removals commit atomically. WebSocket notifications\nare sent after commit to notify connected clients of tag changes.\n\n**Related Endpoints**\n- GET /task-tags - List tags for a flow execution\n- GET /task-executions - View task executions with their tags\n- PUT /task-executions - Update task execution (separate from tagging)",
        "operationId": "patch_flow_task_tags_api_task_tags_patch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PatchFlowTaskTagsRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PatchFlowTaskTagsResponse"
                }
              }
            },
            "description": "Task tags successfully updated"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Bad Request - Invalid tag operation or missing required fields"
          },
          "404": {
            "content": {
              "application/json": {
                "examples": {
                  "flow_not_found": {
                    "summary": "Flow not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Flow not found"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  },
                  "resource_not_found": {
                    "summary": "Resource not found",
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "Resource not found"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Not Found - The requested resource does not exist"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            },
            "description": "Validation Error"
          },
          "500": {
            "content": {
              "application/json": {
                "examples": {
                  "internal_error": {
                    "summary": "Internal server error",
                    "value": {
                      "error": {
                        "code": "internal_error",
                        "message": "Internal server error"
                      },
                      "request_id": "01K8KABR6S16YETA2SZPVBS9SP"
                    }
                  },
                  "repository_error": {
                    "summary": "Database error",
                    "value": {
                      "error": {
                        "code": "repository_error",
                        "message": "Database operation failed"
                      },
                      "request_id": "01K8KACP7D2XFGHJ9KLM4NPQR8"
                    }
                  }
                },
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            },
            "description": "Internal Server Error - An unexpected error occurred"
          }
        },
        "security": [
          {
            "APIKeyAuth": [],
            "BearerAuth": []
          }
        ],
        "summary": "Add or remove task tags in batch",
        "tags": [
          "task-tags"
        ]
      }
    }
  },
  "servers": [
    {
      "description": "Production server",
      "url": "https://flows.super.ai"
    }
  ],
  "tags": [
    {
      "description": "Flow management operations for defining and organizing workflows.\n\nFlows represent workflow definitions with tasks, dependencies, and execution logic. They serve as reusable templates that can be executed multiple times with different inputs.\n\n**What is a flow?**\nA flow consists of:\n- **Tasks**: Individual units of work that perform specific actions\n- **Dependencies**: Relationships between tasks that define execution order\n- **Configuration**: Settings and parameters that control flow behavior\n\n**Use these endpoints to:**\n- Create new flow definitions from scratch or import from YAML\n- List and search existing flows in your organization\n- Retrieve detailed flow information including task definitions\n- Update flow configurations and task parameters\n- Delete flows that are no longer needed\n\nFlows are the foundation of your workflow automation\u2014once defined, they can be executed via the flow-executions endpoints.",
      "name": "flows",
      "x-displayName": "Flows"
    },
    {
      "description": "Flow execution operations for running and monitoring workflows.\n\nFlow 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.\n\n**Key concepts:**\n- **Execution Status**: Tracks the lifecycle (running, completed, failed, cancelled)\n- **Run Number**: Sequential identifier for executions of the same flow\n- **Execution Context**: Contains input parameters, user information, and metadata\n- **Task Results**: Stores outputs from each task within the execution\n\n**Use these endpoints to:**\n- Start new flow executions with custom input parameters\n- Monitor execution progress and status in real-time\n- Retrieve execution history and detailed results\n- Filter and search executions by status, date, or flow\n- Cancel running executions when needed\n- Access task-level execution details and outputs\n\nFlow executions transform flow definitions into actual work and deliverable results.",
      "name": "flow-executions",
      "x-displayName": "Flow Executions"
    },
    {
      "description": "Task execution operations for tracking individual task runs within flow executions.\n\nTask 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.\n\n**What is tracked:**\n- **Status**: Current state (pending, running, completed, failed, skipped)\n- **Input/Output**: Data passed to and produced by the task\n- **Timing**: Start time, end time, and duration\n- **Errors**: Failure details and error messages\n- **Tags**: Metadata and categorization\n\n**Use these endpoints to:**\n- Query task execution status for debugging\n- Retrieve task outputs for analysis\n- Debug task failures with detailed error information\n- Track task performance and timing\n- Monitor task execution progress within flows\n\nTask executions provide granular visibility into workflow execution, essential for debugging and optimization.",
      "name": "task-executions",
      "x-displayName": "Task Executions"
    },
    {
      "description": "Task executor operations for discovering available task types and their capabilities.\n\nTask 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.\n\n**What task executors provide:**\n- **Input Schema**: JSON Schema defining required and optional parameters\n- **Output Schema**: Expected output structure and data types\n- **Description**: Human-readable explanation of functionality\n- **Agent Prompts**: Instructions for AI-powered flow generation\n\n**Use these endpoints to:**\n- Discover available task types for flow building\n- View task input/output schemas for validation\n- Understand task capabilities and requirements\n- Build flow builder UIs with dynamic task lists\n- Enable AI agents to select appropriate tasks\n\nTask executors enable dynamic, flexible workflow creation by providing a registry of available operations.",
      "name": "task-executors",
      "x-displayName": "Task Executors"
    },
    {
      "description": "Task output operations for storing and retrieving task execution results.\n\nTask 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.\n\n**Key characteristics:**\n- **Summary Field**: Structured output data ready for consumption\n- **Historical Record**: Permanent storage of task results\n- **Queryable**: Filter and search outputs by task, execution, or flow\n- **Linked**: Connected to parent flow execution and task execution\n\n**Use these endpoints to:**\n- Store task results after successful execution\n- Retrieve outputs for specific tasks or entire executions\n- Query historical outputs for analysis and reporting\n- Access formatted results for display in dashboards\n- Feed outputs to downstream tasks or external systems\n\nTask outputs provide the data foundation for workflow analytics, debugging, and result visualization.",
      "name": "task-outputs",
      "x-displayName": "Task Outputs"
    },
    {
      "description": "Task data operations for flow validation, schema discovery, and dynamic configuration.\n\nThe 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.\n\n**Primary Use Cases:**\n- **Flow Builder UI**: Get task output schemas for validating downstream task inputs\n- **Schema Discovery**: Understand the structure of data each task produces\n- **Dynamic Configuration**: Retrieve runtime-dependent options (e.g., available spreadsheets, database tables)\n- **Flow Validation**: Validate flow definitions programmatically before saving or executing\n- **Custom Integrations**: Build tools that work with SuperAI Flows programmatically\n\n**What You Get:**\n- **Output Schemas**: JSON Schema definitions for each task's output structure\n- **Dynamic Data**: Runtime-dependent configuration options (dropdown choices, conditional fields)\n- **Validation Errors**: Detailed error messages for invalid flow definitions\n\n**How It Works:**\n1. Submit a flow definition in SuperAI Flows DSL format\n2. The endpoint validates the structure and loads each task executor\n3. For each task, it extracts the output schema and any dynamic configuration data\n4. Returns all schemas, dynamic data, and any validation errors encountered\n\n**Key Concepts:**\n- **Output Schema**: JSON Schema describing the structure of data a task produces\n- **Dynamic Data**: Configuration options that depend on user credentials or external state (e.g., list of Google Sheets accessible with your credentials)\n- **Validation Levels**: Basic (structure only) vs Full (includes semantic validation)\n\n**Integration Notes:**\n- The flow builder frontend uses this endpoint to power the task configuration UI\n- Flows API uses this validation internally when creating/updating flows\n- Response includes validation errors even on HTTP 200 - always check `validation_errors` field\n- May make external API calls to fetch dynamic data, so response time varies (100ms-2s typical)\n\n**Related Endpoints:**\n- `GET /task-executors`: List available task executor types and their schemas\n- `POST /flows`: Create flow (uses task-data validation internally)\n- `PUT /flows/{flow_id}`: Update flow (uses task-data validation internally)",
      "name": "task-data",
      "x-displayName": "Task Data"
    },
    {
      "description": "Task tag operations for categorizing and organizing tasks with metadata.\n\nTask tags provide metadata and categorization for tasks within flow executions. Tags enable flexible organization, filtering, and grouping of tasks beyond their structural relationships.\n\n**What tags enable:**\n- **Categorization**: Group related tasks across different flows\n- **Filtering**: Query executions by tag criteria\n- **Metadata**: Attach custom key-value pairs to tasks\n- **Organization**: Create logical groupings for reporting\n\n**Use these endpoints to:**\n- Manage task labels and categories\n- Add organizational metadata to tasks\n- Query tasks by tag criteria\n- Build custom views and dashboards\n\nTask tags provide flexible organization capabilities that enhance workflow management and analysis.",
      "name": "task-tags",
      "x-displayName": "Task Tags"
    },
    {
      "description": "Integration operations for connecting flows to external services and platforms.\n\nIntegrations 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.\n\n**Supported integration types:**\n- **Databases**: PostgreSQL, MySQL, and other SQL databases\n- **Storage**: SFTP, cloud storage, and file systems\n- **Communication**: Email (SMTP, SES), webhooks, notifications\n- **Collaboration**: SharePoint, Google Drive, document management\n- **Custom**: Plugin architecture for extending functionality\n\n**Key concepts:**\n- **Credentials**: Securely stored authentication information per integration\n- **Plugins**: Modular integration implementations with discovery and registration\n- **OAuth Flows**: Automated authorization for third-party services\n- **Webhooks**: Inbound event handling from external platforms\n- **Connection Testing**: Validate credentials and connectivity before use\n\n**Use these endpoints to:**\n- Configure and manage integration credentials\n- Test connections to external services\n- Handle OAuth authorization flows for cloud services\n- Set up and manage webhooks for inbound events\n- Discover available integration capabilities\n- Access integration-specific features (folders, schemas, etc.)\n\nIntegrations bridge your workflows with the external world, enabling powerful automation across your entire technology stack.",
      "name": "integrations",
      "x-displayName": "Integrations"
    },
    {
      "description": "Authentication operations for user authentication, authorization, and session management.\n\nAuthentication 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.\n\n**Authentication flow:**\n1. Obtain credentials from your account at core.flows.super.ai\n2. Authenticate to receive JWT access token and refresh token\n3. Include access token in API requests via Authorization header\n4. API validates tokens and extracts user identity and organization context\n5. Tokens expire after 1 hour and must be refreshed\n\n**Key concepts:**\n- **Bearer Tokens**: Short-lived JWT tokens (1 hour) used for API requests\n- **Anon-Key**: Long-lived API key used to authenticate to the authentication API.\n- **Refresh Tokens**: Long-lived tokens used to obtain new access tokens\n- **Protected Routes**: Most endpoints require valid authentication\n- **Public Endpoints**: Limited whitelisted paths accessible without auth\n\n**Getting started with authentication:**\n\n1. **Obtain your Anonymous Key** (public endpoint - no authentication required):\n   ```bash\n   curl https://flows.super.ai/api/auth/anon-key\n   ```\n\n2. **Authenticate** to receive your tokens:\n   ```bash\n   curl -X POST 'https://core.flows.super.ai/auth/v1/token?grant_type=password' \\\n     -H 'Content-Type: application/json' \\\n     -H 'apikey: ANON_KEY' \\\n     -d '{\"email\": \"you@example.com\", \"password\": \"your-password\"}'\n   ```\n   This will return a JWT access token and refresh token.\n\n3. **Use the access token** in your requests:\n   ```bash\n   curl -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\" \\\n        https://flows.super.ai/api/flows\n   ```\n\n**Token management:**\n- Access tokens expire after 1 hour\n- Use refresh tokens to obtain new access tokens without re-authenticating\n- Store tokens securely and never commit them to version control\n\nAll API endpoints (except whitelisted public paths) require authentication. Include your bearer token in the Authorization header: `Bearer <token>`",
      "name": "auth",
      "x-displayName": "Authentication"
    },
    {
      "description": "User profile operations for viewing and updating account information.\n\nProfile 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.\n\n**Account information includes:**\n- **Personal Details**: First name, last name, email\n- **Organization**: Associated organization and role\n- **Status**: Account status and permissions\n- **Metadata**: Created/updated timestamps\n\n**Use these endpoints to:**\n- Retrieve current user information for display\n- Update personal details (name, preferences)\n- View organization membership and role\n- Access account metadata\n\nProfile endpoints provide self-service account management capabilities, reducing the need for administrative intervention for routine updates.\n\n**Note:** All profile endpoints are protected and automatically scope to the authenticated user. Email and organization changes require admin privileges.",
      "name": "profile",
      "x-displayName": "Profile"
    },
    {
      "description": "Model operations for querying available AI models and their configurations.\n\nModel endpoints provide information about the AI models available through the platform. These endpoints enable discovery of models, their capabilities, and regional availability.\n\n**Key features:**\n- **Model Discovery**: List all available AI models\n- **Regional Filtering**: Query models by geographic region (EU, Global)\n- **Model Metadata**: Access model information including provider, location, and capabilities\n\n**Use these endpoints to:**\n- Discover available AI models for your workflows\n- Filter models by region for compliance or latency requirements\n- Retrieve model metadata for configuration and selection\n- Build dynamic model selection UIs\n\n**Regional filtering:**\n- `eu`: Models deployed in European regions (West Europe, France Central, Germany, Sweden)\n- `global`: Models deployed in US and other global regions\n\nModel endpoints enable intelligent model selection and routing based on your requirements for compliance, performance, and cost.",
      "name": "models",
      "x-displayName": "Models"
    },
    {
      "description": "File download operations for retrieving files from gs:// storage URIs.\n\nWhen Super.AI Flows processes documents, task outputs often include file references as `gs://` URIs pointing to Google Cloud Storage. These endpoints let you download those files without needing to understand GCS internals or parse storage URLs.\n\n**The problem these endpoints solve:**\n\nPreviously, downloading a file required:\n1. Recognizing the URL as a GCS reference\n2. Parsing out the file key from the URI\n3. Calling a separate endpoint to get a signed URL\n4. Downloading using that signed URL\n\n**Now it's simple:** Pass the `gs://` URI exactly as received and get your file.\n\n**Two ways to download:**\n\n1. **Direct download** (`GET /files/download`): Returns a redirect to the file. Perfect for curl with `-L` flag.\n   ```\n   curl -L -H \"X-API-Key: saf_xxx\" \"https://flows.super.ai/api/files/download?uri=gs://...\" -o file.pdf\n   ```\n\n2. **Resolve first** (`POST /files/resolve`): Returns a JSON response with the download URL. Better for programmatic use and sensitive files (keeps URI out of logs).\n   ```\n   curl -X POST \"https://flows.super.ai/api/files/resolve\" \\\n     -H \"X-API-Key: saf_xxx\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"uri\": \"gs://...\"}'\n   ```\n\n**Security:**\n- Files are organization-scoped: you can only download files from flows your organization owns\n- URIs are validated to prevent path traversal attacks\n- Download URLs expire after 1 hour\n\n**Common use cases:**\n- Download processed documents from completed flow executions\n- Retrieve extracted data files from task outputs\n- Integrate file downloads into automated pipelines",
      "name": "files",
      "x-displayName": "Files"
    },
    {
      "description": "Human review task operations for creating and managing human-in-the-loop review workflows.",
      "name": "human-review-tasks",
      "x-displayName": "Human Review Tasks"
    },
    {
      "description": "Service account operations for managing programmatic API access credentials.",
      "name": "service-accounts",
      "x-displayName": "Service Accounts"
    },
    {
      "description": "Organization operations for viewing credit balance and organization-scoped information.",
      "name": "organizations",
      "x-displayName": "Organizations"
    },
    {
      "description": "Single Sign-On operations for configuring SAML-based SSO authentication.",
      "name": "sso",
      "x-displayName": "SSO"
    },
    {
      "description": "Plugin operations for managing integration plugin instances, OAuth flows, and webhooks.",
      "name": "plugins",
      "x-displayName": "Plugins"
    }
  ]
}