> ## Documentation Index > Fetch the complete documentation index at: https://docs.flows.super.ai/llms.txt > Use this file to discover all available pages before exploring further. # List human review tasks for a flow execution (org-level access) > List human review tasks for a flow execution without user-assignment filtering. Returns all non-deleted HITL tasks for the given flow execution, regardless of which user they are assigned to. Requires org membership (get_user_info). Intended for admin/observer use-cases such as viewing a completed HITL task. Supplying both source filters narrows the result to the single task identified by (flow_execution_id, source_task_name, source_task_execution_idx) — the natural key of a HITL task. This is what lets an external system deep-link a reviewer straight to a review task using only data it already holds (FLO-2696); the task's own id is never exposed outside the platform. Context: - Both source filters must be given together, or neither (400 otherwise) - Excludes soft-deleted tasks - Authorization is handled by RLS policies (user must have access to the organization) Related Endpoints: - GET /human-review-tasks/{task_id} - Get a single task once its id is known - GET /human-review-tasks - List tasks assigned to the current user ## OpenAPI ````yaml /openapi/superai-flows-openapi.json get /api/human-review-tasks/by-execution openapi: 3.1.0 info: description: >- SuperAI Flows is a workflow orchestration platform that enables you to design, deploy, and monitor automated workflows at scale. Build complex workflows using our declarative YAML DSL, execute them reliably, and integrate seamlessly with AI models, cloud storage, and enterprise systems. **Key Capabilities:** - **Workflow Management**: Define workflows as code with version control and automated execution - **Task Orchestration**: Chain together API calls, data processing, and AI operations - **Real-time Monitoring**: Track execution progress with WebSocket notifications and comprehensive logging - **Multi-tenant Architecture**: Organization-scoped resources with role-based access control **API Versioning and Breaking Changes:** We follow a strict compatibility policy to ensure your integrations remain stable: - **Non-breaking changes** (safe, no action required): - Adding new API endpoints - Adding new optional query parameters to existing endpoints - Adding new fields to API responses - Adding new values to existing enums - **Breaking changes** (requires client updates): - Removing or renaming API endpoints - Removing query parameters or request fields - Removing response fields - Changing field types or validation rules - Removing values from existing enums **Client Implementation Requirements:** Your API clients MUST be designed to gracefully handle additional fields in responses. We may add new fields to any response object without considering this a breaking change. Ensure your JSON parsers ignore unknown fields rather than raising errors. **Backward Compatibility Guarantee:** We commit to maintaining backward compatibility for all non-breaking changes. Breaking changes will be: - Announced at least 15 days in advance - Documented in our changelog with migration guide For the latest API updates and migration guides, see our changelog. title: SuperAI Flow Platform version: 0.1.0 servers: - description: Production server url: https://flows.super.ai security: [] tags: - description: >- Flow management operations for defining and organizing workflows. Flows represent workflow definitions with tasks, dependencies, and execution logic. They serve as reusable templates that can be executed multiple times with different inputs. **What is a flow?** A flow consists of: - **Tasks**: Individual units of work that perform specific actions - **Dependencies**: Relationships between tasks that define execution order - **Configuration**: Settings and parameters that control flow behavior **Use these endpoints to:** - Create new flow definitions from scratch or import from YAML - List and search existing flows in your organization - Retrieve detailed flow information including task definitions - Update flow configurations and task parameters - Delete flows that are no longer needed Flows are the foundation of your workflow automation—once defined, they can be executed via the flow-executions endpoints. name: flows x-displayName: Flows - description: >- Flow execution operations for running and monitoring workflows. Flow executions represent runtime instances of flows. When you execute a flow, a new flow execution is created with its own unique ID, status, and execution context. Each execution is independent and maintains its own state, input data, and results. **Key concepts:** - **Execution Status**: Tracks the lifecycle (running, completed, failed, cancelled) - **Run Number**: Sequential identifier for executions of the same flow - **Execution Context**: Contains input parameters, user information, and metadata - **Task Results**: Stores outputs from each task within the execution **Use these endpoints to:** - Start new flow executions with custom input parameters - Monitor execution progress and status in real-time - Retrieve execution history and detailed results - Filter and search executions by status, date, or flow - Cancel running executions when needed - Access task-level execution details and outputs Flow executions transform flow definitions into actual work and deliverable results. name: flow-executions x-displayName: Flow Executions - description: >- Task execution operations for tracking individual task runs within flow executions. Task executions represent individual task runs within a flow execution. Each task in a flow execution has its own task execution record that tracks its lifecycle, inputs, outputs, and status. **What is tracked:** - **Status**: Current state (pending, running, completed, failed, skipped) - **Input/Output**: Data passed to and produced by the task - **Timing**: Start time, end time, and duration - **Errors**: Failure details and error messages - **Tags**: Metadata and categorization **Use these endpoints to:** - Query task execution status for debugging - Retrieve task outputs for analysis - Debug task failures with detailed error information - Track task performance and timing - Monitor task execution progress within flows Task executions provide granular visibility into workflow execution, essential for debugging and optimization. name: task-executions x-displayName: Task Executions - description: >- Task executor operations for discovering available task types and their capabilities. Task executors define the available task types that can be used in flow definitions. Each executor specifies its input schema, execution behavior, and capabilities. This endpoint enables programmatic discovery of task types for building flows dynamically. **What task executors provide:** - **Input Schema**: JSON Schema defining required and optional parameters - **Output Schema**: Expected output structure and data types - **Description**: Human-readable explanation of functionality - **Agent Prompts**: Instructions for AI-powered flow generation **Use these endpoints to:** - Discover available task types for flow building - View task input/output schemas for validation - Understand task capabilities and requirements - Build flow builder UIs with dynamic task lists - Enable AI agents to select appropriate tasks Task executors enable dynamic, flexible workflow creation by providing a registry of available operations. name: task-executors x-displayName: Task Executors - description: >- Task output operations for storing and retrieving task execution results. Task outputs store the results produced by task executions in a structured, queryable format. While task executions track the full lifecycle (input, output, error, status), task outputs focus specifically on the final output data formatted for display, analysis, and downstream consumption. **Key characteristics:** - **Summary Field**: Structured output data ready for consumption - **Historical Record**: Permanent storage of task results - **Queryable**: Filter and search outputs by task, execution, or flow - **Linked**: Connected to parent flow execution and task execution **Use these endpoints to:** - Store task results after successful execution - Retrieve outputs for specific tasks or entire executions - Query historical outputs for analysis and reporting - Access formatted results for display in dashboards - Feed outputs to downstream tasks or external systems Task outputs provide the data foundation for workflow analytics, debugging, and result visualization. name: task-outputs x-displayName: Task Outputs - description: >- Task data operations for flow validation, schema discovery, and dynamic configuration. The task-data endpoint analyzes flow definitions to extract task output schemas, dynamic configuration options, and validation errors. This is essential for building flow configuration UIs, validating flows before execution, and understanding task data structures. **Primary Use Cases:** - **Flow Builder UI**: Get task output schemas for validating downstream task inputs - **Schema Discovery**: Understand the structure of data each task produces - **Dynamic Configuration**: Retrieve runtime-dependent options (e.g., available spreadsheets, database tables) - **Flow Validation**: Validate flow definitions programmatically before saving or executing - **Custom Integrations**: Build tools that work with SuperAI Flows programmatically **What You Get:** - **Output Schemas**: JSON Schema definitions for each task's output structure - **Dynamic Data**: Runtime-dependent configuration options (dropdown choices, conditional fields) - **Validation Errors**: Detailed error messages for invalid flow definitions **How It Works:** 1. Submit a flow definition in SuperAI Flows DSL format 2. The endpoint validates the structure and loads each task executor 3. For each task, it extracts the output schema and any dynamic configuration data 4. Returns all schemas, dynamic data, and any validation errors encountered **Key Concepts:** - **Output Schema**: JSON Schema describing the structure of data a task produces - **Dynamic Data**: Configuration options that depend on user credentials or external state (e.g., list of Google Sheets accessible with your credentials) - **Validation Levels**: Basic (structure only) vs Full (includes semantic validation) **Integration Notes:** - The flow builder frontend uses this endpoint to power the task configuration UI - Flows API uses this validation internally when creating/updating flows - Response includes validation errors even on HTTP 200 - always check `validation_errors` field - May make external API calls to fetch dynamic data, so response time varies (100ms-2s typical) **Related Endpoints:** - `GET /task-executors`: List available task executor types and their schemas - `POST /flows`: Create flow (uses task-data validation internally) - `PUT /flows/{flow_id}`: Update flow (uses task-data validation internally) name: task-data x-displayName: Task Data - description: >- Task tag operations for categorizing and organizing tasks with metadata. Task tags provide metadata and categorization for tasks within flow executions. Tags enable flexible organization, filtering, and grouping of tasks beyond their structural relationships. **What tags enable:** - **Categorization**: Group related tasks across different flows - **Filtering**: Query executions by tag criteria - **Metadata**: Attach custom key-value pairs to tasks - **Organization**: Create logical groupings for reporting **Use these endpoints to:** - Manage task labels and categories - Add organizational metadata to tasks - Query tasks by tag criteria - Build custom views and dashboards Task tags provide flexible organization capabilities that enhance workflow management and analysis. name: task-tags x-displayName: Task Tags - description: >- Integration operations for connecting flows to external services and platforms. Integrations enable your workflows to interact with third-party services, databases, storage systems, and communication platforms. They provide a unified interface for managing credentials, testing connections, and configuring service-specific features. **Supported integration types:** - **Databases**: PostgreSQL, MySQL, and other SQL databases - **Storage**: SFTP, cloud storage, and file systems - **Communication**: Email (SMTP, SES), webhooks, notifications - **Collaboration**: SharePoint, Google Drive, document management - **Custom**: Plugin architecture for extending functionality **Key concepts:** - **Credentials**: Securely stored authentication information per integration - **Plugins**: Modular integration implementations with discovery and registration - **OAuth Flows**: Automated authorization for third-party services - **Webhooks**: Inbound event handling from external platforms - **Connection Testing**: Validate credentials and connectivity before use **Use these endpoints to:** - Configure and manage integration credentials - Test connections to external services - Handle OAuth authorization flows for cloud services - Set up and manage webhooks for inbound events - Discover available integration capabilities - Access integration-specific features (folders, schemas, etc.) Integrations bridge your workflows with the external world, enabling powerful automation across your entire technology stack. name: integrations x-displayName: Integrations - description: >- Authentication operations for user authentication, authorization, and session management. Authentication endpoints handle user identity verification, token generation, and access control throughout the platform. The system uses JWT (JSON Web Token) based authentication managed through core.flows.super.ai. **Authentication flow:** 1. Obtain credentials from your account at core.flows.super.ai 2. Authenticate to receive JWT access token and refresh token 3. Include access token in API requests via Authorization header 4. API validates tokens and extracts user identity and organization context 5. Tokens expire after 1 hour and must be refreshed **Key concepts:** - **Bearer Tokens**: Short-lived JWT tokens (1 hour) used for API requests - **Anon-Key**: Long-lived API key used to authenticate to the authentication API. - **Refresh Tokens**: Long-lived tokens used to obtain new access tokens - **Protected Routes**: Most endpoints require valid authentication - **Public Endpoints**: Limited whitelisted paths accessible without auth **Getting started with authentication:** 1. **Obtain your Anonymous Key** (public endpoint - no authentication required): ```bash curl https://flows.super.ai/api/auth/anon-key ``` 2. **Authenticate** to receive your tokens: ```bash curl -X POST 'https://core.flows.super.ai/auth/v1/token?grant_type=password' \ -H 'Content-Type: application/json' \ -H 'apikey: ANON_KEY' \ -d '{"email": "you@example.com", "password": "your-password"}' ``` This will return a JWT access token and refresh token. **Human verification:** when `GET /api/auth/captcha-config` reports `"enabled": true`, this environment requires a human-verification token on the direct password grant, and the command above returns 400 without one. Add the solved challenge token to the body: ```json {"email": "you@example.com", "password": "your-password", "gotrue_meta_security": {"captcha_token": "TOKEN_FROM_THE_WIDGET"}} ``` Obtaining such a token requires rendering the challenge in a browser, so non-interactive API consumers should prefer a service-role integration, which is exempt from human verification. 3. **Use the access token** in your requests: ```bash curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ https://flows.super.ai/api/flows ``` **Token management:** - Access tokens expire after 1 hour - Use refresh tokens to obtain new access tokens without re-authenticating - Store tokens securely and never commit them to version control All API endpoints (except whitelisted public paths) require authentication. Include your bearer token in the Authorization header: `Bearer ` name: auth x-displayName: Authentication - description: >- User profile operations for viewing and updating account information. Profile endpoints allow authenticated users to view and update their own account information and preferences. These endpoints operate on the currently authenticated user (determined from the JWT token) and do not require specifying a user ID. **Account information includes:** - **Personal Details**: First name, last name, email - **Organization**: Associated organization and role - **Status**: Account status and permissions - **Metadata**: Created/updated timestamps **Use these endpoints to:** - Retrieve current user information for display - Update personal details (name, preferences) - View organization membership and role - Access account metadata Profile endpoints provide self-service account management capabilities, reducing the need for administrative intervention for routine updates. **Note:** All profile endpoints are protected and automatically scope to the authenticated user. Email and organization changes require admin privileges. name: profile x-displayName: Profile - description: >- Model operations for querying available AI models and their configurations. Model endpoints provide information about the AI models available through the platform. These endpoints enable discovery of models, their capabilities, and regional availability. **Key features:** - **Model Discovery**: List all available AI models - **Regional Filtering**: Query models by geographic region (EU, Global) - **Model Metadata**: Access model information including provider, location, and capabilities **Use these endpoints to:** - Discover available AI models for your workflows - Filter models by region for compliance or latency requirements - Retrieve model metadata for configuration and selection - Build dynamic model selection UIs **Regional filtering:** - `eu`: Models deployed in European regions (West Europe, France Central, Germany, Sweden) - `global`: Models deployed in US and other global regions Model 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. When 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. **The problem these endpoints solve:** Previously, downloading a file required: 1. Recognizing the URL as a GCS reference 2. Parsing out the file key from the URI 3. Calling a separate endpoint to get a signed URL 4. Downloading using that signed URL **Now it's simple:** Pass the `gs://` URI exactly as received and get your file. **Two ways to download:** 1. **Direct download** (`GET /files/download`): Returns a redirect to the file. Perfect for curl with `-L` flag. ``` curl -L -H "X-API-Key: saf_xxx" "https://flows.super.ai/api/files/download?uri=gs://..." -o file.pdf ``` 2. **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). ``` curl -X POST "https://flows.super.ai/api/files/resolve" \ -H "X-API-Key: saf_xxx" \ -H "Content-Type: application/json" \ -d '{"uri": "gs://..."}' ``` **Security:** - Files are organization-scoped: you can only download files from flows your organization owns - URIs are validated to prevent path traversal attacks - Download URLs expire after 1 hour **Common use cases:** - Download processed documents from completed flow executions - Retrieve extracted data files from task outputs - 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: >- Push data from external systems to a flow execution's waiting 'Wait for Webhook' task. A 2xx acknowledgment means the data is durably stored; identical redeliveries are idempotent. name: webhook-data x-displayName: Webhook Data - 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: >- Worker group operations for organizing an organization's members into groups. Restricted to organization admins. name: worker-groups x-displayName: Worker Groups - 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 paths: /api/human-review-tasks/by-execution: get: tags: - human-review-tasks summary: List human review tasks for a flow execution (org-level access) description: >- List human review tasks for a flow execution without user-assignment filtering. Returns all non-deleted HITL tasks for the given flow execution, regardless of which user they are assigned to. Requires org membership (get_user_info). Intended for admin/observer use-cases such as viewing a completed HITL task. Supplying both source filters narrows the result to the single task identified by (flow_execution_id, source_task_name, source_task_execution_idx) — the natural key of a HITL task. This is what lets an external system deep-link a reviewer straight to a review task using only data it already holds (FLO-2696); the task's own id is never exposed outside the platform. Context: - Both source filters must be given together, or neither (400 otherwise) - Excludes soft-deleted tasks - Authorization is handled by RLS policies (user must have access to the organization) Related Endpoints: - GET /human-review-tasks/{task_id} - Get a single task once its id is known - GET /human-review-tasks - List tasks assigned to the current user operationId: >- list_human_review_tasks_by_execution_api_human_review_tasks_by_execution_get parameters: - description: The flow execution ID to filter tasks by in: query name: flow_execution_id required: true schema: description: The flow execution ID to filter tasks by format: uuid title: Flow Execution Id type: string - description: >- Name of the human review task to narrow to. Must be provided together with source_task_execution_idx. in: query name: source_task_name required: false schema: anyOf: - type: string - type: 'null' description: >- Name of the human review task to narrow to. Must be provided together with source_task_execution_idx. title: Source Task Name - description: >- Fan-out index of the human review task execution. Must be provided together with source_task_name. in: query name: source_task_execution_idx required: false schema: anyOf: - minimum: 0 type: integer - type: 'null' description: >- Fan-out index of the human review task execution. Must be provided together with source_task_name. title: Source Task Execution Idx - description: >- Controls delivery of large task values stored as GCS references. 'inline' (default) resolves references server-side and returns real values, subject to a per-request size budget (HTTP 413 when exceeded; individual references whose objects no longer exist are replaced by a '__gcs_ref_error__' marker). 'refs' returns stored reference envelopes ('__gcs_ref__') untouched, to be resolved by the client. in: query name: large_values required: false schema: $ref: '#/components/schemas/LargeValuesMode' default: inline description: >- Controls delivery of large task values stored as GCS references. 'inline' (default) resolves references server-side and returns real values, subject to a per-request size budget (HTTP 413 when exceeded; individual references whose objects no longer exist are replaced by a '__gcs_ref_error__' marker). 'refs' returns stored reference envelopes ('__gcs_ref__') untouched, to be resolved by the client. responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/HumanReviewTaskResponse' title: >- Response List Human Review Tasks By Execution Api Human Review Tasks By Execution Get type: array description: List of human review tasks retrieved successfully '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request - only one of the source task filters was provided '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 '413': content: application/json: examples: large_values_budget_exceeded: summary: Inline large-values budget exceeded value: error: code: large_values_budget_exceeded details: budget_bytes: 67108864 max_refs: 500 ref_count: 12 total_ref_bytes: 88080384 message: >- Response exceeds the inline large-values budget; retry with large_values=refs or narrow the query request_id: 01K8KABR6S16YETA2SZPVBS9SP schema: $ref: '#/components/schemas/ErrorResponse' description: >- Payload Too Large - Inline large-values dereference budget exceeded; retry with large_values=refs or narrow the query '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: - BearerAuth: [] - APIKeyAuth: [] components: schemas: LargeValuesMode: enum: - inline - refs title: LargeValuesMode type: string 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. examples: - '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. examples: - 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. examples: - 550e8400-e29b-41d4-a716-446655440000 format: uuid title: Flow Execution Id type: string human_messages: anyOf: - items: type: string type: array - type: 'null' description: >- Visible messages to display to the human reviewer as contextual information. examples: - - Please verify the total amount - Check the invoice date title: Human Messages 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. examples: - 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. examples: - 550e8400-e29b-41d4-a716-446655440000 format: uuid title: Organization Id type: string review_annotations: anyOf: - items: $ref: '#/components/schemas/ReviewAnnotation' type: array - type: 'null' description: >- Failed validations mapped onto the reviewed outputs, one entry per failed validation execution and affected target. Null for reviews created before annotations existed. title: Review Annotations review_result: anyOf: - type: boolean - type: 'null' description: >- Review result: True for correct, False for incorrect, null for not yet finished. examples: - true - false title: Review Result reviewed_output: anyOf: - items: {} type: array - type: 'null' description: >- Output of the completed review. Null for tasks not yet completed. List positionally aligned with target_task_executions; each entry is a reviewed item (a dict, or a scalar for per-item references to scalar outputs). examples: - - comments: All dates are correct. verified: true title: Reviewed Output signal_sent: default: true description: >- Whether the Temporal resume signal was sent. False when deferred due to concurrency limits. title: Signal Sent type: boolean source_task_execution_idx: description: Index of the source task execution that created this review. examples: - 0 title: Source Task Execution Idx type: integer source_task_name: description: Name of the source task that created this review. examples: - process_document title: Source Task Name type: string status: description: >- Status of the task. Valid values: 'pending', 'in_progress', 'completed'. examples: - pending title: Status type: string target_task_executions: description: >- List of target task executions to review. The reviewer sees one card per entry; reviewed_output on completion is a positional list aligned with this list. items: $ref: '#/components/schemas/HumanReviewTargetTaskExecution' minItems: 1 title: Target Task Executions type: array task_metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: Additional metadata associated with the human review task. examples: - 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_executions - source_task_name - source_task_execution_idx - status title: HumanReviewTaskResponse type: object ErrorResponse: description: |- Standard API error response structure. All error responses from the API follow this format, ensuring consistent error handling for API consumers. Example: { "error": { "message": "Flow not found", "code": "not_found" }, "request_id": "01K8KABR6S16YETA2SZPVBS9SP" } 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 HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' title: Detail type: array title: HTTPValidationError type: object ReviewAnnotation: description: >- A failed validation mapped onto the reviewed data, so the UI can mark the affected field. Addresses one of the review's target executions. ``task_name`` null means the message could not be tied to any target and is shown as a general message only. ``path`` addresses a place inside the target output: a leading integer is the index of a collection item (row, split, value), a string is a property name. The ``source_*`` fields identify the validation execution that failed. properties: message: description: 'Reviewer-facing message: the validation task''s description.' examples: - Each line item needs a SKU title: Message type: string output_name: anyOf: - type: string - type: 'null' description: >- Output of the target task the annotation applies to. Null for the whole task output. examples: - line_items title: Output Name path: description: >- Address inside the output: a leading integer is the collection item index, strings are property names. Empty for the whole output. examples: - - 2 - sku items: anyOf: - type: string - type: integer title: Path type: array source_task_execution_idx: anyOf: - type: integer - type: 'null' description: Index of the validation task execution that failed. examples: - 2 title: Source Task Execution Idx source_task_name: anyOf: - type: string - type: 'null' description: Validation task that produced the annotation. examples: - validate_rows title: Source Task Name task_execution_idx: anyOf: - type: integer - type: 'null' description: >- Index of the target task execution, when the failed validation was bound to exactly one. examples: - 0 title: Task Execution Idx task_name: anyOf: - type: string - type: 'null' description: Target task the annotation applies to. Null for a general message. examples: - extract_doc title: Task Name required: - message title: ReviewAnnotation type: object HumanReviewTargetTaskExecution: description: >- One target execution being reviewed in a human review task. When ``output_name`` and ``output_collection_idx`` are both set, the entry targets a specific item of the named output collection rather than the whole task output: the reviewer sees/edits just that item, and the matching ``reviewed_output[idx]`` carries that item's value (not the whole task output dict). properties: is_editable: default: false description: >- Whether the reviewer is allowed to edit this item's data. Read-only items pass through unchanged on completion. examples: - true - false title: Is Editable type: boolean output_collection_idx: anyOf: - type: integer - type: 'null' description: >- Zero-based index into the target task's named output collection. Required when output_name is set; must be null otherwise. examples: - 0 title: Output Collection Idx output_name: anyOf: - type: string - type: 'null' description: >- When set together with output_collection_idx, narrows the target to a single item of the named output collection on the target task. Both fields must be set or both null. examples: - rows title: Output Name task_execution_idx: description: Index of the target task execution. examples: - 0 title: Task Execution Idx type: integer task_name: description: Name of the target task being reviewed. examples: - extract_doc title: Task Name type: string required: - task_name - task_execution_idx title: HumanReviewTargetTaskExecution type: object ErrorDetail: description: |- Standard error detail structure. This model matches the error format returned by the centralized exception 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 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 securitySchemes: BearerAuth: bearerFormat: JWT description: >- JWT Bearer token authentication. Include your access token in the Authorization header as: `Bearer YOUR_ACCESS_TOKEN` Example: ``` Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... ``` scheme: bearer type: http APIKeyAuth: description: >- API key authentication. Include your API key in the X-API-Key header as: `X-API-Key YOUR_API_KEY` Example: ``` X-API-Key: saf_1234567890 ``` in: header name: X-API-Key type: apiKey ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.