Analyze flow definition and extract schemas
Analyze a flow definition to extract task output schemas, dynamic data, and validation errors.
Overview This endpoint validates a flow definition and returns metadata needed for flow building, execution planning, and UI generation. It processes all tasks in the flow definition to extract their output schemas (for type validation), dynamic configuration data (for UI dropdowns and conditional fields), and any structural or semantic validation errors.
Use Cases
- Flow Builder UI: Get task output schemas for downstream task input validation
- Dynamic Configuration: Retrieve runtime-dependent options (e.g., available spreadsheets, databases)
- Flow Validation: Check for errors before saving or executing a flow
- Schema Discovery: Understand what data each task will produce
- Custom Integrations: Programmatically validate and analyze flow definitions
How It Works
- Parses and validates the flow definition structure (basic validation)
- For each task in the flow:
- Loads the task executor implementation
- Calls the executor's
get_output_model()to get the output schema - Calls the executor's dynamic data methods (if available) to get runtime options
- Collects any errors encountered during schema/data extraction
- If
full_validation=true, performs additional semantic validation (checks task parameter values, validates connections between tasks, etc.) - Returns all schemas, dynamic data, and validation errors in a single response
Dynamic Data Explained Dynamic data represents configuration options that depend on external state or user credentials. For example:
- Google Sheets task: List of spreadsheets accessible with user's credentials
- Database task: List of available tables/columns
- API task: Available endpoints or data models from connected service
Validation Levels
- Basic (default): Structure validation only (required fields, data types)
- Full (
full_validation=true): Includes semantic validation (valid references, parameter constraints, external resource availability)
Performance Notes
- May make external API calls to fetch dynamic data (e.g., Google Sheets API)
- Response time varies based on number of tasks and external service latency
- Typical response time: 100ms-2s depending on task executors used
Related Endpoints
POST /flows- Create flow (uses this endpoint's validation internally)PUT /flows/{flow_id}- Update flow (uses this endpoint's validation internally)GET /task-executors- List available task executors
Header Parameters
Query Parameters
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)....
Body Parameters
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.
Response
Response Attributes
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 ...
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 v...
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 ta...
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.
Show child attributes
Response Attributes
Show child attributes
Response Attributes
Standard error detail structure.
This model matches the error format returned by the centralized exception handlers in app/api/errors/handlers.py.