openapi: 3.0.3
info:
  title: Dify Console API
  description: API documentation for Dify Console – Datasets, Snippets, Snippet Workflows, and Evaluation modules.
  version: 1.0.0

servers:
  - url: /console/api

tags:
  - name: Datasets
    description: Knowledge base (dataset) CRUD and ancillary operations
  - name: Dataset Evaluation
    description: Knowledge base retrieval evaluation
  - name: Snippets
    description: Customized snippet CRUD, import/export, and dependency checks
  - name: Snippet Workflows
    description: Snippet draft/published workflow operations, node runs, and workflow runs
  - name: Evaluation
    description: Evaluation configuration, runs, metrics, and node info for App / Snippet targets

# ============================================================
# Paths
# ============================================================
paths:

  # ----------------------------------------------------------
  # Datasets
  # ----------------------------------------------------------

  /datasets:
    get:
      tags: [Datasets]
      summary: List datasets
      operationId: get_datasets
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: keyword
          in: query
          schema: { type: string }
        - name: include_all
          in: query
          schema: { type: boolean, default: false }
        - name: ids
          in: query
          schema: { type: array, items: { type: string } }
        - name: tag_ids
          in: query
          schema: { type: array, items: { type: string } }
      responses:
        '200':
          description: Datasets retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/DatasetDetail' } }
                  page: { type: integer }
                  limit: { type: integer }
                  total: { type: integer }
                  has_more: { type: boolean }
    post:
      tags: [Datasets]
      summary: Create a dataset
      operationId: create_dataset
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DatasetCreatePayload' }
      responses:
        '201':
          description: Dataset created successfully
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DatasetDetail' }
        '400':
          $ref: '#/components/responses/BadRequest'

  /datasets/{dataset_id}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Datasets]
      summary: Get dataset details
      operationId: get_dataset
      responses:
        '200':
          description: Dataset retrieved successfully
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DatasetDetail' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [Datasets]
      summary: Update dataset
      operationId: update_dataset
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DatasetUpdatePayload' }
      responses:
        '200':
          description: Dataset updated successfully
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DatasetDetail' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Datasets]
      summary: Delete dataset
      operationId: delete_dataset
      responses:
        '204': { description: Dataset deleted successfully }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/use-check:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Datasets]
      summary: Check if dataset is in use
      operationId: check_dataset_use
      responses:
        '200':
          description: Dataset use status
          content:
            application/json:
              schema:
                type: object
                properties:
                  is_using: { type: boolean }

  /datasets/{dataset_id}/queries:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Datasets]
      summary: Get dataset query history
      operationId: get_dataset_queries
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Query history retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
                  page: { type: integer }
                  limit: { type: integer }
                  total: { type: integer }
                  has_more: { type: boolean }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/indexing-estimate:
    post:
      tags: [Datasets]
      summary: Estimate dataset indexing cost
      operationId: estimate_dataset_indexing
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/IndexingEstimatePayload' }
      responses:
        '200': { description: Indexing estimate calculated }

  /datasets/{dataset_id}/related-apps:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Datasets]
      summary: Get applications related to dataset
      operationId: get_dataset_related_apps
      responses:
        '200':
          description: Related apps retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
                  total: { type: integer }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/indexing-status:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Datasets]
      summary: Get dataset indexing status
      operationId: get_dataset_indexing_status
      responses:
        '200':
          description: Indexing status retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }

  /datasets/api-keys:
    get:
      tags: [Datasets]
      summary: Get dataset API keys
      operationId: get_dataset_api_keys
      responses:
        '200':
          description: API keys retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  items: { type: array, items: { $ref: '#/components/schemas/ApiKeyItem' } }
    post:
      tags: [Datasets]
      summary: Create dataset API key
      operationId: create_dataset_api_key
      responses:
        '200':
          description: API key created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ApiKeyItem' }
        '400': { $ref: '#/components/responses/BadRequest' }

  /datasets/api-keys/{api_key_id}:
    parameters:
      - name: api_key_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    delete:
      tags: [Datasets]
      summary: Delete dataset API key
      operationId: delete_dataset_api_key
      responses:
        '204': { description: API key deleted }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/api-keys/{status}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: status
        in: path
        required: true
        schema: { type: string, enum: [enable, disable] }
    post:
      tags: [Datasets]
      summary: Enable or disable dataset API
      operationId: toggle_dataset_api
      responses:
        '200': { description: Status updated }

  /datasets/api-base-info:
    get:
      tags: [Datasets]
      summary: Get dataset API base URL
      operationId: get_dataset_api_base_info
      responses:
        '200':
          description: API base info
          content:
            application/json:
              schema:
                type: object
                properties:
                  api_base_url: { type: string }

  /datasets/retrieval-setting:
    get:
      tags: [Datasets]
      summary: Get dataset retrieval settings
      operationId: get_dataset_retrieval_setting
      responses:
        '200':
          description: Retrieval settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  retrieval_method: { type: array, items: { type: string } }

  /datasets/retrieval-setting/{vector_type}:
    parameters:
      - name: vector_type
        in: path
        required: true
        schema: { type: string }
    get:
      tags: [Datasets]
      summary: Get mock retrieval settings by vector type
      operationId: get_dataset_retrieval_setting_mock
      responses:
        '200':
          description: Mock retrieval settings
          content:
            application/json:
              schema:
                type: object
                properties:
                  retrieval_method: { type: array, items: { type: string } }

  /datasets/{dataset_id}/error-docs:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Datasets]
      summary: Get dataset error documents
      operationId: get_dataset_error_docs
      responses:
        '200':
          description: Error documents retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
                  total: { type: integer }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/permission-part-users:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Datasets]
      summary: Get dataset permission user list
      operationId: get_dataset_permission_users
      responses:
        '200':
          description: Permission users retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { type: object } }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/auto-disable-logs:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Datasets]
      summary: Get dataset auto-disable logs
      operationId: get_dataset_auto_disable_logs
      responses:
        '200': { description: Auto-disable logs retrieved }
        '404': { $ref: '#/components/responses/NotFound' }

  # ----------------------------------------------------------
  # Dataset Evaluation
  # ----------------------------------------------------------

  /datasets/{dataset_id}/evaluation/template/download:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    post:
      tags: [Dataset Evaluation]
      summary: Download evaluation dataset template for knowledge base
      operationId: download_dataset_evaluation_template
      responses:
        '200':
          description: XLSX template streamed as attachment
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: {}
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/evaluation:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Dataset Evaluation]
      summary: Get evaluation configuration for knowledge base
      operationId: get_dataset_evaluation_config
      responses:
        '200':
          description: Evaluation configuration retrieved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EvaluationConfig' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      tags: [Dataset Evaluation]
      summary: Save evaluation configuration for knowledge base
      operationId: save_dataset_evaluation_config
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EvaluationConfigData' }
      responses:
        '200':
          description: Configuration saved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EvaluationConfig' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/evaluation/run:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    post:
      tags: [Dataset Evaluation]
      summary: Start evaluation run for knowledge base
      operationId: start_dataset_evaluation_run
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EvaluationRunRequest' }
      responses:
        '200':
          description: Evaluation run started
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EvaluationRun' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { description: Max concurrent runs reached }

  /datasets/{dataset_id}/evaluation/logs:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Dataset Evaluation]
      summary: Get evaluation run history for knowledge base
      operationId: get_dataset_evaluation_logs
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - name: page_size
          in: query
          schema: { type: integer, default: 20 }
      responses:
        '200':
          description: Evaluation logs retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/EvaluationRun' } }
                  total: { type: integer }
                  page: { type: integer }
                  page_size: { type: integer }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/evaluation/runs/{run_id}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
      - $ref: '#/components/parameters/RunId'
    get:
      tags: [Dataset Evaluation]
      summary: Get evaluation run detail for knowledge base
      operationId: get_dataset_evaluation_run_detail
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - name: page_size
          in: query
          schema: { type: integer, default: 50 }
      responses:
        '200':
          description: Run detail with items
          content:
            application/json:
              schema:
                type: object
                properties:
                  run: { $ref: '#/components/schemas/EvaluationRun' }
                  items:
                    type: object
                    properties:
                      data: { type: array, items: { $ref: '#/components/schemas/EvaluationRunItem' } }
                      total: { type: integer }
                      page: { type: integer }
                      page_size: { type: integer }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/evaluation/runs/{run_id}/cancel:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
      - $ref: '#/components/parameters/RunId'
    post:
      tags: [Dataset Evaluation]
      summary: Cancel a running knowledge base evaluation
      operationId: cancel_dataset_evaluation_run
      responses:
        '200':
          description: Evaluation run cancelled
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EvaluationRun' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/evaluation/metrics:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
    get:
      tags: [Dataset Evaluation]
      summary: Get available retrieval evaluation metrics
      operationId: get_dataset_evaluation_metrics
      responses:
        '200':
          description: Metrics retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  metrics: { type: array, items: { type: string } }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  /datasets/{dataset_id}/evaluation/files/{file_id}:
    parameters:
      - $ref: '#/components/parameters/DatasetId'
      - name: file_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [Dataset Evaluation]
      summary: Download evaluation file for knowledge base
      operationId: download_dataset_evaluation_file
      responses:
        '200':
          description: File info and download URL
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FileInfo' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }

  # ----------------------------------------------------------
  # Snippets
  # ----------------------------------------------------------

  /workspaces/current/customized-snippets:
    get:
      tags: [Snippets]
      summary: List customized snippets
      operationId: list_customized_snippets
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: keyword
          in: query
          schema: { type: string }
        - name: is_published
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Snippets retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/SnippetListItem' } }
                  page: { type: integer }
                  limit: { type: integer }
                  total: { type: integer }
                  has_more: { type: boolean }
    post:
      tags: [Snippets]
      summary: Create a customized snippet
      operationId: create_customized_snippet
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateSnippetPayload' }
      responses:
        '201':
          description: Snippet created
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Snippet' }
        '400': { $ref: '#/components/responses/BadRequest' }

  /workspaces/current/customized-snippets/{snippet_id}:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    get:
      tags: [Snippets]
      summary: Get snippet details
      operationId: get_customized_snippet
      responses:
        '200':
          description: Snippet retrieved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Snippet' }
        '404': { $ref: '#/components/responses/NotFound' }
    patch:
      tags: [Snippets]
      summary: Update snippet
      operationId: update_customized_snippet
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateSnippetPayload' }
      responses:
        '200':
          description: Snippet updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Snippet' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
    delete:
      tags: [Snippets]
      summary: Delete snippet
      operationId: delete_customized_snippet
      responses:
        '204': { description: Snippet deleted }
        '404': { $ref: '#/components/responses/NotFound' }

  /workspaces/current/customized-snippets/{snippet_id}/export:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    get:
      tags: [Snippets]
      summary: Export snippet as DSL (YAML)
      operationId: export_customized_snippet
      parameters:
        - name: include_secret
          in: query
          schema: { type: string, enum: ['true', 'false'], default: 'false' }
      responses:
        '200':
          description: Snippet DSL exported
          content:
            application/x-yaml: {}
        '404': { $ref: '#/components/responses/NotFound' }

  /workspaces/current/customized-snippets/imports:
    post:
      tags: [Snippets]
      summary: Import snippet from DSL
      operationId: import_customized_snippet
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SnippetImportPayload' }
      responses:
        '200': { description: Import succeeded }
        '202': { description: Import pending confirmation }
        '400': { $ref: '#/components/responses/BadRequest' }

  /workspaces/current/customized-snippets/imports/{import_id}/confirm:
    parameters:
      - name: import_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [Snippets]
      summary: Confirm a pending snippet import
      operationId: confirm_snippet_import
      responses:
        '200': { description: Import confirmed }
        '400': { $ref: '#/components/responses/BadRequest' }

  /workspaces/current/customized-snippets/{snippet_id}/check-dependencies:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    get:
      tags: [Snippets]
      summary: Check snippet dependencies
      operationId: check_snippet_dependencies
      responses:
        '200': { description: Dependencies checked }
        '404': { $ref: '#/components/responses/NotFound' }

  /workspaces/current/customized-snippets/{snippet_id}/use-count/increment:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    post:
      tags: [Snippets]
      summary: Increment snippet use count
      operationId: increment_snippet_use_count
      responses:
        '200':
          description: Use count incremented
          content:
            application/json:
              schema:
                type: object
                properties:
                  result: { type: string }
                  use_count: { type: integer }
        '404': { $ref: '#/components/responses/NotFound' }

  # ----------------------------------------------------------
  # Snippet Workflows
  # ----------------------------------------------------------

  /snippets/{snippet_id}/workflows/draft:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    get:
      tags: [Snippet Workflows]
      summary: Get draft workflow for snippet
      operationId: get_snippet_draft_workflow
      responses:
        '200':
          description: Draft workflow retrieved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Workflow' }
        '404': { $ref: '#/components/responses/NotFound' }
    post:
      tags: [Snippet Workflows]
      summary: Sync draft workflow
      operationId: sync_snippet_draft_workflow
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SnippetDraftSyncPayload' }
      responses:
        '200':
          description: Draft synced
          content:
            application/json:
              schema:
                type: object
                properties:
                  result: { type: string }
                  hash: { type: string }
                  updated_at: { type: number }
        '400': { description: Hash mismatch }

  /snippets/{snippet_id}/workflows/draft/config:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    get:
      tags: [Snippet Workflows]
      summary: Get snippet draft workflow config limits
      operationId: get_snippet_draft_config
      responses:
        '200':
          description: Config retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  parallel_depth_limit: { type: integer }

  /snippets/{snippet_id}/workflows/publish:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    get:
      tags: [Snippet Workflows]
      summary: Get published workflow for snippet
      operationId: get_snippet_published_workflow
      responses:
        '200':
          description: Published workflow retrieved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Workflow' }
        '404': { $ref: '#/components/responses/NotFound' }
    post:
      tags: [Snippet Workflows]
      summary: Publish snippet workflow
      operationId: publish_snippet_workflow
      responses:
        '200':
          description: Workflow published
          content:
            application/json:
              schema:
                type: object
                properties:
                  result: { type: string }
                  created_at: { type: number }
        '400': { $ref: '#/components/responses/BadRequest' }

  /snippets/{snippet_id}/workflows/default-workflow-block-configs:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    get:
      tags: [Snippet Workflows]
      summary: Get default block configurations
      operationId: get_snippet_default_block_configs
      responses:
        '200': { description: Default block configs retrieved }

  /snippets/{snippet_id}/workflow-runs:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    get:
      tags: [Snippet Workflows]
      summary: List workflow runs for snippet
      operationId: list_snippet_workflow_runs
      parameters:
        - name: last_id
          in: query
          schema: { type: string }
        - $ref: '#/components/parameters/LimitParam'
      responses:
        '200':
          description: Workflow runs retrieved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkflowRunPagination' }

  /snippets/{snippet_id}/workflow-runs/{run_id}:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
      - $ref: '#/components/parameters/RunId'
    get:
      tags: [Snippet Workflows]
      summary: Get workflow run detail
      operationId: get_snippet_workflow_run_detail
      responses:
        '200':
          description: Run detail retrieved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkflowRunDetail' }
        '404': { $ref: '#/components/responses/NotFound' }

  /snippets/{snippet_id}/workflow-runs/{run_id}/node-executions:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
      - $ref: '#/components/parameters/RunId'
    get:
      tags: [Snippet Workflows]
      summary: List node executions for a workflow run
      operationId: list_snippet_workflow_run_node_executions
      responses:
        '200':
          description: Node executions retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/WorkflowNodeExecution' } }

  /snippets/{snippet_id}/workflows/draft/nodes/{node_id}/run:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
      - $ref: '#/components/parameters/NodeId'
    post:
      tags: [Snippet Workflows]
      summary: Run a single node in draft workflow (single-step debug)
      operationId: run_snippet_draft_node
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SnippetDraftNodeRunPayload' }
      responses:
        '200':
          description: Node run result
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkflowNodeExecution' }
        '404': { $ref: '#/components/responses/NotFound' }

  /snippets/{snippet_id}/workflows/draft/nodes/{node_id}/last-run:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
      - $ref: '#/components/parameters/NodeId'
    get:
      tags: [Snippet Workflows]
      summary: Get last run result for a node
      operationId: get_snippet_draft_node_last_run
      responses:
        '200':
          description: Node last run retrieved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkflowNodeExecution' }
        '404': { $ref: '#/components/responses/NotFound' }

  /snippets/{snippet_id}/workflows/draft/iteration/nodes/{node_id}/run:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
      - $ref: '#/components/parameters/NodeId'
    post:
      tags: [Snippet Workflows]
      summary: Run iteration node (SSE stream)
      operationId: run_snippet_draft_iteration_node
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SnippetIterationNodeRunPayload' }
      responses:
        '200':
          description: SSE stream with iteration progress
          content:
            text/event-stream: {}
        '404': { $ref: '#/components/responses/NotFound' }

  /snippets/{snippet_id}/workflows/draft/loop/nodes/{node_id}/run:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
      - $ref: '#/components/parameters/NodeId'
    post:
      tags: [Snippet Workflows]
      summary: Run loop node (SSE stream)
      operationId: run_snippet_draft_loop_node
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SnippetLoopNodeRunPayload' }
      responses:
        '200':
          description: SSE stream with loop progress
          content:
            text/event-stream: {}
        '404': { $ref: '#/components/responses/NotFound' }

  /snippets/{snippet_id}/workflows/draft/run:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
    post:
      tags: [Snippet Workflows]
      summary: Run draft workflow (SSE stream)
      operationId: run_snippet_draft_workflow
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SnippetDraftRunPayload' }
      responses:
        '200':
          description: SSE stream with execution progress
          content:
            text/event-stream: {}
        '404': { $ref: '#/components/responses/NotFound' }

  /snippets/{snippet_id}/workflow-runs/tasks/{task_id}/stop:
    parameters:
      - $ref: '#/components/parameters/SnippetId'
      - name: task_id
        in: path
        required: true
        schema: { type: string }
    post:
      tags: [Snippet Workflows]
      summary: Stop a running snippet workflow task
      operationId: stop_snippet_workflow_task
      responses:
        '200':
          description: Task stopped
          content:
            application/json:
              schema:
                type: object
                properties:
                  result: { type: string }

  # ----------------------------------------------------------
  # Evaluation (App / Snippet targets)
  # ----------------------------------------------------------

  /{evaluate_target_type}/{evaluate_target_id}/dataset-template/download:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
    post:
      tags: [Evaluation]
      summary: Download evaluation dataset template
      operationId: download_evaluation_dataset_template
      responses:
        '200':
          description: XLSX template streamed as attachment
          content:
            application/vnd.openxmlformats-officedocument.spreadsheetml.sheet: {}
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }

  /{evaluate_target_type}/{evaluate_target_id}/evaluation:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
    get:
      tags: [Evaluation]
      summary: Get evaluation configuration
      operationId: get_evaluation_detail
      responses:
        '200':
          description: Evaluation configuration retrieved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EvaluationConfig' }
        '404': { $ref: '#/components/responses/NotFound' }
    put:
      tags: [Evaluation]
      summary: Save evaluation configuration
      operationId: save_evaluation_detail
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EvaluationConfigData' }
      responses:
        '200':
          description: Configuration saved
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EvaluationConfig' }
        '404': { $ref: '#/components/responses/NotFound' }

  /{evaluate_target_type}/{evaluate_target_id}/evaluation/logs:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
    get:
      tags: [Evaluation]
      summary: Get evaluation run history
      operationId: get_evaluation_logs
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - name: page_size
          in: query
          schema: { type: integer, default: 20 }
      responses:
        '200':
          description: Evaluation logs retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  data: { type: array, items: { $ref: '#/components/schemas/EvaluationRun' } }
                  total: { type: integer }
                  page: { type: integer }
                  page_size: { type: integer }
        '404': { $ref: '#/components/responses/NotFound' }

  /{evaluate_target_type}/{evaluate_target_id}/evaluation/run:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
    post:
      tags: [Evaluation]
      summary: Start an evaluation run
      operationId: start_evaluation_run
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/EvaluationRunRequest' }
      responses:
        '200':
          description: Evaluation run started
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EvaluationRun' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { description: Max concurrent runs reached }

  /{evaluate_target_type}/{evaluate_target_id}/evaluation/runs/{run_id}:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
      - $ref: '#/components/parameters/RunId'
    get:
      tags: [Evaluation]
      summary: Get evaluation run detail with items
      operationId: get_evaluation_run_detail
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - name: page_size
          in: query
          schema: { type: integer, default: 50 }
      responses:
        '200':
          description: Run detail with paginated items
          content:
            application/json:
              schema:
                type: object
                properties:
                  run: { $ref: '#/components/schemas/EvaluationRun' }
                  items:
                    type: object
                    properties:
                      data: { type: array, items: { $ref: '#/components/schemas/EvaluationRunItem' } }
                      total: { type: integer }
                      page: { type: integer }
                      page_size: { type: integer }
        '404': { $ref: '#/components/responses/NotFound' }

  /{evaluate_target_type}/{evaluate_target_id}/evaluation/runs/{run_id}/cancel:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
      - $ref: '#/components/parameters/RunId'
    post:
      tags: [Evaluation]
      summary: Cancel a running evaluation
      operationId: cancel_evaluation_run
      responses:
        '200':
          description: Evaluation run cancelled
          content:
            application/json:
              schema: { $ref: '#/components/schemas/EvaluationRun' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }

  /{evaluate_target_type}/{evaluate_target_id}/evaluation/metrics:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
    get:
      tags: [Evaluation]
      summary: Get available evaluation metrics per category
      operationId: get_evaluation_metrics
      responses:
        '200':
          description: Metrics grouped by category
          content:
            application/json:
              schema:
                type: object
                properties:
                  metrics:
                    type: object
                    additionalProperties:
                      type: array
                      items: { type: string }

  /{evaluate_target_type}/{evaluate_target_id}/evaluation/node-info:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
    post:
      tags: [Evaluation]
      summary: Get workflow/snippet node info grouped by metric
      operationId: get_evaluation_node_info
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                metrics:
                  type: array
                  items: { type: string }
                  description: Metric names to query. Omit or pass empty to get all nodes.
      responses:
        '200':
          description: Node info grouped by metric or "all"
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items: { $ref: '#/components/schemas/NodeInfo' }
        '404': { $ref: '#/components/responses/NotFound' }

  /evaluation/available-metrics:
    get:
      tags: [Evaluation]
      summary: Get centrally-defined list of evaluation metrics
      operationId: get_available_evaluation_metrics
      responses:
        '200':
          description: Available metrics list
          content:
            application/json:
              schema:
                type: object
                properties:
                  metrics:
                    type: array
                    items: { type: string }
                    example:
                      - faithfulness
                      - answer_relevancy
                      - answer_correctness
                      - semantic_similarity
                      - context_precision
                      - context_recall
                      - context_relevance
                      - tool_correctness
                      - task_completion

  /{evaluate_target_type}/{evaluate_target_id}/evaluation/files/{file_id}:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
      - name: file_id
        in: path
        required: true
        schema: { type: string, format: uuid }
    get:
      tags: [Evaluation]
      summary: Download evaluation file
      operationId: download_evaluation_file
      responses:
        '200':
          description: File info and download URL
          content:
            application/json:
              schema: { $ref: '#/components/schemas/FileInfo' }
        '404': { $ref: '#/components/responses/NotFound' }

  /{evaluate_target_type}/{evaluate_target_id}/evaluation/version:
    parameters:
      - $ref: '#/components/parameters/EvaluateTargetType'
      - $ref: '#/components/parameters/EvaluateTargetId'
    get:
      tags: [Evaluation]
      summary: Get evaluation target version details
      operationId: get_evaluation_version_detail
      parameters:
        - name: version
          in: query
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Version graph retrieved
          content:
            application/json:
              schema:
                type: object
                properties:
                  graph: { type: object }
        '400': { $ref: '#/components/responses/BadRequest' }
        '404': { $ref: '#/components/responses/NotFound' }

# ============================================================
# Components
# ============================================================
components:

  # ---------- Parameters ----------
  parameters:
    PageParam:
      name: page
      in: query
      schema: { type: integer, default: 1 }
    LimitParam:
      name: limit
      in: query
      schema: { type: integer, default: 20 }
    DatasetId:
      name: dataset_id
      in: path
      required: true
      schema: { type: string, format: uuid }
    SnippetId:
      name: snippet_id
      in: path
      required: true
      schema: { type: string, format: uuid }
    RunId:
      name: run_id
      in: path
      required: true
      schema: { type: string, format: uuid }
    NodeId:
      name: node_id
      in: path
      required: true
      schema: { type: string }
    EvaluateTargetType:
      name: evaluate_target_type
      in: path
      required: true
      schema:
        type: string
        enum: [app, snippets]
      description: "Evaluation target type: app or snippets"
    EvaluateTargetId:
      name: evaluate_target_id
      in: path
      required: true
      schema: { type: string, format: uuid }
      description: Evaluation target ID (App ID or Snippet ID)

  # ---------- Responses ----------
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            type: object
            properties:
              message: { type: string }
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              message: { type: string }
    Forbidden:
      description: Permission denied
      content:
        application/json:
          schema:
            type: object
            properties:
              message: { type: string }

  # ---------- Schemas ----------
  schemas:

    # -- Dataset --
    DatasetDetail:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        description: { type: string }
        provider: { type: string }
        permission: { type: string }
        indexing_technique: { type: string }
        embedding_model: { type: string }
        embedding_model_provider: { type: string }
        embedding_available: { type: boolean }
        created_at: { type: number }
        updated_at: { type: number }

    DatasetCreatePayload:
      type: object
      required: [name]
      properties:
        name: { type: string, minLength: 1, maxLength: 40 }
        description: { type: string, maxLength: 400 }
        indexing_technique: { type: string }
        permission: { type: string, enum: [only_me, all_team_members, partial_members] }
        provider: { type: string, default: vendor }
        external_knowledge_api_id: { type: string }
        external_knowledge_id: { type: string }

    DatasetUpdatePayload:
      type: object
      properties:
        name: { type: string, minLength: 1, maxLength: 40 }
        description: { type: string, maxLength: 400 }
        permission: { type: string }
        indexing_technique: { type: string }
        embedding_model: { type: string }
        embedding_model_provider: { type: string }
        retrieval_model: { type: object }
        icon_info: { type: object }

    IndexingEstimatePayload:
      type: object
      required: [info_list, process_rule, indexing_technique]
      properties:
        info_list: { type: object }
        process_rule: { type: object }
        indexing_technique: { type: string }
        doc_form: { type: string, default: text_model }
        dataset_id: { type: string }
        doc_language: { type: string, default: English }

    ApiKeyItem:
      type: object
      properties:
        id: { type: string, format: uuid }
        type: { type: string }
        token: { type: string }
        created_at: { type: number }

    # -- Snippet --
    Snippet:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        description: { type: string }
        type: { type: string, enum: [node, group] }
        is_published: { type: boolean }
        version: { type: string }
        use_count: { type: integer }
        icon_info: { type: object }
        input_fields: { type: array, items: { type: object } }
        created_at: { type: number }
        updated_at: { type: number }

    SnippetListItem:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        description: { type: string }
        type: { type: string }
        is_published: { type: boolean }
        use_count: { type: integer }
        icon_info: { type: object }
        created_at: { type: number }
        updated_at: { type: number }

    CreateSnippetPayload:
      type: object
      required: [name]
      properties:
        name: { type: string }
        description: { type: string }
        type: { type: string, enum: [node, group] }
        icon_info: { type: object }
        input_fields: { type: array, items: { type: object } }

    UpdateSnippetPayload:
      type: object
      properties:
        name: { type: string }
        description: { type: string }
        icon_info: { type: object }

    SnippetImportPayload:
      type: object
      properties:
        mode: { type: string }
        yaml_content: { type: string }
        yaml_url: { type: string }
        snippet_id: { type: string }
        name: { type: string }
        description: { type: string }

    # -- Snippet Workflow --
    Workflow:
      type: object
      properties:
        id: { type: string, format: uuid }
        graph: { type: object }
        features: { type: object }
        hash: { type: string }
        created_at: { type: number }
        updated_at: { type: number }

    SnippetDraftSyncPayload:
      type: object
      properties:
        graph: { type: object }
        hash: { type: string }
        environment_variables: { type: array, items: { type: object } }
        conversation_variables: { type: array, items: { type: object } }
        input_variables: { type: array, items: { type: object } }

    SnippetDraftNodeRunPayload:
      type: object
      properties:
        inputs: { type: object }
        query: { type: string }
        files: { type: array, items: { type: object } }

    SnippetDraftRunPayload:
      type: object
      properties:
        inputs: { type: object }
        files: { type: array, items: { type: object } }

    SnippetIterationNodeRunPayload:
      type: object
      properties:
        inputs: { type: object }

    SnippetLoopNodeRunPayload:
      type: object
      properties:
        inputs: { type: object }

    WorkflowRunPagination:
      type: object
      properties:
        limit: { type: integer }
        has_more: { type: boolean }
        data: { type: array, items: { $ref: '#/components/schemas/WorkflowRunDetail' } }

    WorkflowRunDetail:
      type: object
      properties:
        id: { type: string, format: uuid }
        version: { type: string }
        status: { type: string, enum: [running, succeeded, failed, stopped, partial-succeeded] }
        elapsed_time: { type: number }
        total_tokens: { type: integer }
        total_steps: { type: integer }
        created_at: { type: number }
        finished_at: { type: number }
        exceptions_count: { type: integer }

    WorkflowNodeExecution:
      type: object
      properties:
        id: { type: string, format: uuid }
        index: { type: integer }
        node_id: { type: string }
        node_type: { type: string }
        title: { type: string }
        inputs: { type: object }
        process_data: { type: object }
        outputs: { type: object }
        status: { type: string }
        error: { type: string }
        elapsed_time: { type: number }
        created_at: { type: number }
        finished_at: { type: number }

    # -- Evaluation --
    EvaluationConfig:
      type: object
      properties:
        evaluation_model: { type: string, nullable: true }
        evaluation_model_provider: { type: string, nullable: true }
        metrics_config: { type: object, nullable: true }
        judgement_conditions: { type: object, nullable: true }

    EvaluationConfigData:
      type: object
      properties:
        evaluation_model: { type: string }
        evaluation_model_provider: { type: string }
        default_metrics:
          type: array
          items:
            type: object
            properties:
              metric: { type: string }
              node_info_list:
                type: array
                items: { $ref: '#/components/schemas/NodeInfo' }
        customized_metrics:
          type: object
          nullable: true
          properties:
            evaluation_workflow_id: { type: string }
            input_fields: { type: object }
            output_fields: { type: array, items: { type: object } }
        judgment_config:
          type: object
          nullable: true

    EvaluationRunRequest:
      allOf:
        - $ref: '#/components/schemas/EvaluationConfigData'
        - type: object
          required: [file_id]
          properties:
            file_id: { type: string, format: uuid }

    EvaluationRun:
      type: object
      properties:
        id: { type: string, format: uuid }
        tenant_id: { type: string, format: uuid }
        target_type: { type: string }
        target_id: { type: string, format: uuid }
        evaluation_config_id: { type: string, format: uuid }
        status: { type: string, enum: [pending, running, completed, failed, cancelled] }
        dataset_file_id: { type: string, format: uuid, nullable: true }
        result_file_id: { type: string, format: uuid, nullable: true }
        total_items: { type: integer }
        completed_items: { type: integer }
        failed_items: { type: integer }
        progress: { type: number }
        metrics_summary: { type: object }
        error: { type: string, nullable: true }
        created_by: { type: string, format: uuid }
        started_at: { type: number, nullable: true }
        completed_at: { type: number, nullable: true }
        created_at: { type: number }

    EvaluationRunItem:
      type: object
      properties:
        id: { type: string, format: uuid }
        item_index: { type: integer }
        inputs: { type: object }
        expected_output: { type: string, nullable: true }
        actual_output: { type: string, nullable: true }
        metrics:
          type: array
          items:
            type: object
            properties:
              name: { type: string }
              value: {}
              details: { type: object }
        judgment: { type: object }
        metadata: { type: object }
        error: { type: string, nullable: true }
        overall_score: { type: number, nullable: true }

    NodeInfo:
      type: object
      properties:
        node_id: { type: string }
        type: { type: string }
        title: { type: string }

    FileInfo:
      type: object
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        size: { type: integer }
        extension: { type: string }
        mime_type: { type: string }
        created_at: { type: number }
        download_url: { type: string }