# yaml-language-server: $schema=oapi_20241018_mod.json
openapi: "3.0.0"
info:
  version: "1.0.0"
  title: "Dagu"
  contact:
    name: "Yota Hamada"
    url: "https://github.com/yottahmd"
  description: API for controlling and monitoring Dagu server.
  license:
    name: "GPL-3.0"
    url: "https://github.com/dagucloud/dagu/blob/main/LICENSE.md"

servers:
  - url: "{schema}://{host}/api/v1"
    description: "Dagu API server"
    variables:
      schema:
        default: http
        enum: [http, https]
      host:
        default: localhost
        description: "Host name of the server"

tags:
  - name: "dags"
    description: "Operations for managing and creating DAG definitions"
  - name: "dag-runs"
    description: "Operations for retrieving historical data and logs of DAG-run executions"
  - name: "system"
    description: "System operations for monitoring and managing the Dagu server"
  - name: "monitoring"
    description: "Prometheus-compatible metrics for monitoring Dagu operations"
  - name: "queues"
    description: "Operations for managing and monitoring execution queues"
  - name: "auth"
    description: "Authentication operations (login, logout, token management)"
  - name: "users"
    description: "User management operations (CRUD, password management)"
  - name: "api-keys"
    description: "API key management operations (admin only)"
  - name: "webhooks"
    description: "Webhook endpoints for triggering DAG execution"
  - name: "notifications"
    description: "DAG run notification settings and delivery tests"
  - name: "incidents"
    description: "Incident connection and routing management"
  - name: "audit"
    description: "Audit log operations (admin only)"
  - name: "events"
    description: "Centralized operational event log operations (manager or admin only)"
  - name: "sync"
    description: "Git synchronization operations for DAGs"
  - name: "remote-nodes"
    description: "Remote node management operations (admin only)"
  - name: "secrets"
    description: "Workspace secret registry operations"
  - name: "profiles"
    description: "Runtime profile operations for managed environment variables and secrets"
  - name: "views"
    description: "Saved Overview view configurations (custom Kanban boards)"

paths:
  /health:
    get:
      summary: "Check server health status"
      description: "Returns health information about the Dagu server"
      operationId: "getHealthStatus"
      tags:
        - "system"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HealthResponse"
        default:
          description: "Unexpected error"

  /openapi.json:
    get:
      summary: "Get the OpenAPI document"
      description: "Returns the normalized OpenAPI document served by this Dagu instance"
      operationId: "getOpenapiJson"
      tags:
        - "system"
      responses:
        "200":
          description: "The OpenAPI document"
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/setup:
    post:
      summary: "Create initial admin account"
      description: "Creates the first admin user during initial setup. Only available when no users exist. Returns a JWT token for immediate login."
      operationId: "setup"
      tags:
        - "auth"
      security: []
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetupRequest"
      responses:
        "200":
          description: "Admin account created successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginResponse"
        "400":
          description: "Invalid request (e.g., weak password)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Setup already completed (users exist)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/login:
    post:
      summary: "Authenticate user and obtain JWT token"
      description: "Authenticates a user with username and password, returns a JWT token on success"
      operationId: "login"
      tags:
        - "auth"
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LoginRequest"
      responses:
        "200":
          description: "Authentication successful"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LoginResponse"
        "401":
          description: "Invalid credentials"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: "Too many login attempts — rate limit exceeded"
          headers:
            Retry-After:
              description: "Seconds to wait before retrying"
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/me:
    get:
      summary: "Get current authenticated user"
      description: "Returns information about the currently authenticated user"
      operationId: "getCurrentUser"
      tags:
        - "auth"
      responses:
        "200":
          description: "Current user information"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /auth/change-password:
    post:
      summary: "Change current user's password"
      description: "Allows a locally authenticated builtin user to change their own password. Externally authenticated users do not have Dagu passwords."
      operationId: "changePassword"
      tags:
        - "auth"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChangePasswordRequest"
      responses:
        "200":
          description: "Password changed successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: "Invalid request (e.g., weak password)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated or wrong current password"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Password is managed by the authentication provider"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /users:
    get:
      summary: "List all users"
      description: "Returns a list of all users. Requires admin role."
      operationId: "listUsers"
      tags:
        - "users"
      responses:
        "200":
          description: "List of users"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsersListResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: "Create a new user"
      description: "Creates a new user account. Requires admin role."
      operationId: "createUser"
      tags:
        - "users"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateUserRequest"
      responses:
        "201":
          description: "User created successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "400":
          description: "Invalid request (e.g., weak password, invalid role)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict - username already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /users/{userId}:
    get:
      summary: "Get user by ID"
      description: "Returns a specific user by their ID. Requires admin role."
      operationId: "getUser"
      tags:
        - "users"
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          description: "User details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    patch:
      summary: "Update user"
      description: "Updates a user's information. Requires admin role."
      operationId: "updateUser"
      tags:
        - "users"
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateUserRequest"
      responses:
        "200":
          description: "User updated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UserResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict - username already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete user"
      description: "Deletes a user account. Requires admin role. Cannot delete yourself."
      operationId: "deleteUser"
      tags:
        - "users"
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "204":
          description: "User deleted successfully"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires admin role or cannot delete self"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /users/{userId}/reset-password:
    post:
      summary: "Reset user's password"
      description: "Resets a locally authenticated builtin user's password to a new value. Requires admin role. Externally authenticated users do not have Dagu passwords."
      operationId: "resetUserPassword"
      tags:
        - "users"
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResetPasswordRequest"
      responses:
        "200":
          description: "Password reset successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: "Invalid request (e.g., weak password)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires admin role, or the target user uses an external authentication provider"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "User not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # API Key Management (Admin only)
  /api-keys:
    get:
      summary: "List all API keys"
      description: "Returns all API keys. Requires admin role."
      operationId: "listAPIKeys"
      tags:
        - "api-keys"
      responses:
        "200":
          description: "List of API keys"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeysListResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Requires admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: "Create API key"
      description: "Full key returned only in this response. Community edition installs can create up to 2 API keys."
      operationId: "createAPIKey"
      tags:
        - "api-keys"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateAPIKeyRequest"
      responses:
        "201":
          description: "Created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CreateAPIKeyResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Requires admin role or community API key limit reached"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Name already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api-keys/{keyId}:
    get:
      summary: "Get API key"
      description: "Returns API key by ID. Requires admin role."
      operationId: "getAPIKey"
      tags:
        - "api-keys"
      parameters:
        - $ref: "#/components/parameters/APIKeyId"
      responses:
        "200":
          description: "API key details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Requires admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    patch:
      summary: "Update API key"
      description: "Updates API key info. Requires admin role."
      operationId: "updateAPIKey"
      tags:
        - "api-keys"
      parameters:
        - $ref: "#/components/parameters/APIKeyId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateAPIKeyRequest"
      responses:
        "200":
          description: "Updated API key"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/APIKeyResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Requires admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Name already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete API key"
      description: "Revokes an API key. Requires admin role."
      operationId: "deleteAPIKey"
      tags:
        - "api-keys"
      parameters:
        - $ref: "#/components/parameters/APIKeyId"
      responses:
        "204":
          description: "API key deleted"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Requires admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /workers:
    get:
      summary: "List distributed workers"
      description: "Retrieves information about distributed workers connected to the coordinator. Developer, manager, or admin only."
      operationId: "getWorkers"
      tags:
        - "system"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkersListResponse"
        "503":
          description: "Coordinator service unavailable"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags:
    get:
      summary: "List all available DAGs"
      description: "Retrieves DAG definitions with optional filtering by name and labels"
      operationId: "listDAGs"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/Page"
        - $ref: "#/components/parameters/PerPage"
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/Workspace"
        - name: "name"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Filter DAGs by name"
        - name: "labels"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Filter DAGs by labels (comma-separated). Returns DAGs that have ALL specified labels. Mutually exclusive with `tags`; the server returns HTTP 400 if both are set."
        - name: "tags"
          in: "query"
          required: false
          schema:
            type: "string"
          deprecated: true
          description: "Deprecated alias for `labels`; mutually exclusive with `labels`. Filter DAGs by labels (comma-separated)."
        - name: "sort"
          in: "query"
          required: false
          schema:
            type: "string"
            enum: ["name", "nextRun"]
            default: "name"
          description: |
            Field to sort by:
            - `name`: Sort alphabetically by DAG name (case-insensitive)
            - `nextRun`: Sort by next scheduled run time. DAGs with earlier next run times appear first in ascending order. DAGs without schedules appear last.
        - name: "order"
          in: "query"
          required: false
          schema:
            type: "string"
            enum: ["asc", "desc"]
            default: "asc"
          description: "Sort order (ascending or descending)"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dags:
                    type: array
                    description: "List of DAG definitions with their status and metadata"
                    items:
                      $ref: "#/components/schemas/DAGFile"
                  errors:
                    type: array
                    description: "List of errors encountered during the request"
                    items:
                      type: string
                  pagination:
                    $ref: "#/components/schemas/Pagination"
                required:
                  - dags
                  - errors
                  - pagination
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: "Create a new DAG definition"
      description: "Creates a new empty DAG file with the specified name"
      operationId: "createNewDAG"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  $ref: "#/components/schemas/DAGName"
                spec:
                  type: string
                  description: "Optional DAG spec in YAML format to initialize the DAG. If provided, the spec will be validated before creation."
              required:
                - name
      responses:
        "201":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: "Name of the newly created DAG"
                required:
                  - name
        "400":
          description: "Invalid DAG spec"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /dags/validate:
    post:
      summary: "Validate a DAG specification"
      description: |
        Validates a DAG YAML specification without persisting any changes.

        Returns a list of validation errors. When the spec can be partially parsed,
        the response may also include parsed DAG details built with error-tolerant loading.
      operationId: "validateDAGSpec"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spec:
                  type: string
                  description: "DAG specification in YAML format"
                name:
                  type: string
                  description: "Optional name to use when the spec omits a name"
              required:
                - spec
      responses:
        "200":
          description: "Validation result"
          content:
            application/json:
              schema:
                type: object
                properties:
                  valid:
                    type: boolean
                    description: "True if the spec is valid (no errors)"
                  dag:
                    $ref: "#/components/schemas/DAGDetails"
                  errors:
                    type: array
                    description: "List of validation errors"
                    items:
                      type: string
                required:
                  - valid
                  - errors
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /dags/{fileName}:
    get:
      summary: "Retrieve comprehensive DAG information"
      description: "Fetches detailed information about a specific DAG definition"
      operationId: "getDAGDetails"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                description: "Response object for getting details of a DAG"
                properties:
                  filePath:
                    type: string
                    description: "Absolute file path of the DAG file on disk"
                  dag:
                    $ref: "#/components/schemas/DAGDetails"
                  localDags:
                    type: array
                    description: "List of local DAGs that are part of this DAG"
                    items:
                      $ref: "#/components/schemas/LocalDag"
                  latestDAGRun:
                    $ref: "#/components/schemas/DAGRunDetails"
                  suspended:
                    type: boolean
                    description: "Whether the DAG is suspended"
                  errors:
                    type: array
                    description: "List of errors encountered during the request"
                    items:
                      type: string
                  spec:
                    type: string
                    description: "The DAG specification in YAML format"
                  editorHints:
                    $ref: "#/components/schemas/DAGEditorHints"
                required:
                  - latestDAGRun
                  - suspended
                  - localDags
                  - errors
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete an existing DAG"
      description: "Permanently removes a DAG definition from the system"
      operationId: "deleteDAG"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "204":
          description: "DAG successfully deleted"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/start:
    post:
      summary: "Create and execute a DAG-run from DAG"
      description: "Creates a DAG-run from the DAG definition and starts its execution with optional parameters"
      operationId: "executeDAG"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                params:
                  type: string
                  description: "Parameters to pass to the DAG-run in JSON format"
                dagRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunId"
                    - description: "Optional ID for the DAG-run, if not provided a new one will be generated"
                dagName:
                  type: string
                  description: "Optional DAG name override to use for the created dag-run"
                profile:
                  $ref: "#/components/schemas/RuntimeProfileOverride"
                  description: "Runtime profile override. Omit to use the DAG default profile, set to an empty string to run without a profile, or set to a profile name to override the DAG default."
                singleton:
                  type: boolean
                  description: "If true, prevent starting if DAG is already running (returns 409 conflict)"
                  default: false
                labels:
                  $ref: "#/components/schemas/Labels"
                  description: "Additional labels to apply to the DAG-run. Mutually exclusive with `tags`; the server returns HTTP 400 if both are set."
                tags:
                  $ref: "#/components/schemas/Tags"
                  description: "Deprecated alias for `labels`; mutually exclusive with `labels`."
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRunId:
                    $ref: "#/components/schemas/DAGRunId"
                required:
                  - dagRunId
        "400":
          description: "Invalid request parameters or labels"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "DAG is already running (singleton mode) or dagRunId already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/start-sync:
    post:
      summary: "Execute DAG synchronously and wait for completion"
      deprecated: true
      description: |
        **Deprecated:** Use `POST /dags/{fileName}/start`, then monitor the DAG run through the DAG-run status API or SSE.

        Creates a DAG-run from the DAG definition, starts its execution, waits for it to complete (or timeout), and returns the full execution details including node statuses.

        **Important behaviors:**
        - If the timeout is exceeded, the DAG run continues executing in the background. The 408 response includes the `dagRunId` so clients can monitor or cancel the run.
        - If the DAG reaches a 'waiting' status (human-in-the-loop approval needed), the endpoint returns immediately with 200 and the current status.
      operationId: "executeDAGSync"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - timeout
              properties:
                params:
                  type: string
                  description: "Parameters to pass to the DAG-run in JSON format"
                dagRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunId"
                    - description: "Optional ID for the DAG-run, if not provided a new one will be generated"
                dagName:
                  type: string
                  description: "Optional DAG name override to use for the created dag-run"
                profile:
                  $ref: "#/components/schemas/RuntimeProfileOverride"
                  description: "Runtime profile override. Omit to use the DAG default profile, set to an empty string to run without a profile, or set to a profile name to override the DAG default."
                singleton:
                  type: boolean
                  description: "If true, prevent starting if DAG is already running (returns 409 conflict)"
                  default: false
                labels:
                  $ref: "#/components/schemas/Labels"
                  description: "Additional labels to apply to the DAG-run. Mutually exclusive with `tags`; the server returns HTTP 400 if both are set."
                tags:
                  $ref: "#/components/schemas/Tags"
                  description: "Deprecated alias for `labels`; mutually exclusive with `labels`."
                timeout:
                  type: integer
                  minimum: 1
                  maximum: 86400
                  description: "Maximum seconds to wait for DAG execution to complete (required)"
      responses:
        "200":
          description: "DAG-run completed (or reached waiting status)"
          content:
            application/json:
              schema:
                type: object
                required:
                  - dagRun
                properties:
                  dagRun:
                    $ref: "#/components/schemas/DAGRunDetails"
        "400":
          description: "Invalid request parameters or labels"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "408":
          description: "Timeout waiting for DAG execution to complete. The DAG run continues executing in the background."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TimeoutError"
        "409":
          description: "DAG is already running (singleton mode) or dagRunId already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/enqueue:
    post:
      summary: "Enqueue a DAG-run from DAG"
      description: "Creates a DAG-run from the DAG definition and adds it to the queue for execution"
      operationId: "enqueueDAGDAGRun"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                params:
                  type: string
                  description: "Parameters to pass to the DAG-run in JSON format"
                dagRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunId"
                    - description: "Optional ID for the DAG-run, if not provided a new one will be generated"
                dagName:
                  type: string
                  description: "Optional DAG name override to use for the queued dag-run"
                profile:
                  $ref: "#/components/schemas/RuntimeProfileOverride"
                  description: "Runtime profile override. Omit to use the DAG default profile, set to an empty string to run without a profile, or set to a profile name to override the DAG default."
                queue:
                  type: string
                  description: "Override the DAG-level queue definition"
                singleton:
                  type: boolean
                  description: "If true, prevent enqueuing if DAG is already running or queued (returns 409 conflict)"
                  default: false
                labels:
                  $ref: "#/components/schemas/Labels"
                  description: "Additional labels to apply to the DAG-run. Mutually exclusive with `tags`; the server returns HTTP 400 if both are set."
                tags:
                  $ref: "#/components/schemas/Tags"
                  description: "Deprecated alias for `labels`; mutually exclusive with `labels`."
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRunId:
                    $ref: "#/components/schemas/DAGRunId"
                required:
                  - dagRunId
        "400":
          description: "Invalid request parameters or labels"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "DAG is already running or queued (singleton mode)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/dag-runs:
    get:
      summary: "Retrieve execution history of a DAG"
      description: "Fetches history of DAG-runs created from this DAG definition"
      operationId: "getDAGDAGRunHistory"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRuns:
                    type: array
                    description: "List of historical DAG-runs created from this DAG"
                    items:
                      $ref: "#/components/schemas/DAGRunDetails"
                  gridData:
                    type: array
                    description: "Grid data for visualization"
                    items:
                      $ref: "#/components/schemas/DAGGridItem"
                required:
                  - dagRuns
                  - gridData
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/dag-runs/{dagRunId}:
    get:
      summary: "Get detailed status of a specific DAG-run"
      description: "Retrieves status information about a particular DAG-run created from this DAG"
      tags:
        - "dags"
      operationId: "getDAGDAGRunDetails"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
        - $ref: "#/components/parameters/DAGRunId"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRun:
                    $ref: "#/components/schemas/DAGRunDetails"
                required:
                  - dagRun
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/spec:
    get:
      summary: "Retrieve DAG specification"
      description: "Fetches the YAML specification of a DAG definition"
      operationId: "getDAGSpec"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dag:
                    $ref: "#/components/schemas/DAGDetails"
                  spec:
                    type: string
                    description: "The DAG spec in YAML format"
                  errors:
                    type: array
                    description: "List of errors in the spec"
                    items:
                      type: string
                  valueReferenceNotices:
                    type: array
                    description: "Passive value-reference notices produced while loading this spec. These notices are not persisted."
                    items:
                      $ref: "#/components/schemas/ValueReferenceNotice"
                required:
                  - spec
                  - errors
                  - valueReferenceNotices
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: "Update DAG spec"
      description: "Modifies the YAML specification of a DAG definition"
      operationId: "updateDAGSpec"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spec:
                  type: string
                  description: "The new DAG spec in YAML format"
              required:
                - spec
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    description: "List of errors in the spec"
                    items:
                      type: string
                required:
                  - errors

        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/suspend:
    post:
      summary: "Toggle DAG suspension state"
      description: "Controls whether the scheduler should create DAG-runs from this DAG according to its defined cron schedule"
      operationId: "updateDAGSuspensionState"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                suspend:
                  type: boolean
                  description: "Suspend status to set for the DAG"
              required:
                - suspend
      responses:
        "200":
          description: "A successful response"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/rename:
    post:
      summary: "Change DAG file ID"
      description: "Changes the file ID of the DAG definition"
      operationId: "renameDAG"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newFileName:
                  type: string
                  description: "New file name for the DAG"
              required:
                - newFileName
      responses:
        "200":
          description: "A successful response"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/stop-all:
    post:
      summary: "Stop all running instances of a DAG"
      description: "Terminates all currently running DAG-runs for the specified DAG"
      operationId: "stopAllDAGRuns"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "Successfully stopped all running instances"
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    description: "Errors encountered"
                    items:
                      type: string
                    type: array
                required:
                  - errors
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/search:
    get:
      summary: "Search DAGs"
      description: "Performs a full-text search across all DAG definitions"
      operationId: "searchDAGs"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: "q"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "A search query string"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                description: "Response object for searching DAGs"
                properties:
                  results:
                    type: array
                    description: "Search results matching the query"
                    items:
                      $ref: "#/components/schemas/SearchResultItem"
                  errors:
                    type: array
                    description: "Errors encountered during the search"
                    items:
                      type: string
                required:
                  - results
                  - errors
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /search/dags:
    get:
      summary: "Search DAGs"
      description: "Returns cursor-based, lightweight DAG search results for the global search page."
      operationId: "searchDAGFeed"
      tags:
        - "search"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/Workspace"
        - name: "q"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "A search query string"
        - name: "labels"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Filter DAGs by labels (comma-separated). Returns DAGs that have ALL specified labels."
        - $ref: "#/components/parameters/SearchCursor"
        - $ref: "#/components/parameters/SearchLimit"
      responses:
        "200":
          description: "Cursor-based DAG search results"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DAGSearchFeedResponse"
        "400":
          description: "Invalid search request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /search/dags/{fileName}/matches:
    get:
      summary: "Search DAG match snippets"
      description: "Returns cursor-based snippets for one matching DAG definition."
      operationId: "searchDagMatches"
      tags:
        - "search"
      parameters:
        - $ref: "#/components/parameters/DAGFileName"
        - $ref: "#/components/parameters/RemoteNode"
        - name: "q"
          in: "query"
          required: true
          schema:
            type: "string"
          description: "A search query string"
        - name: "labels"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Filter DAG matches by labels (comma-separated). Returns matches only when the DAG has ALL specified labels."
        - $ref: "#/components/parameters/Workspace"
        - $ref: "#/components/parameters/SearchCursor"
        - $ref: "#/components/parameters/SearchMatchLimit"
      responses:
        "200":
          description: "Cursor-based DAG match snippets"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchMatchesResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/labels:
    get:
      summary: "List all available DAG labels"
      description: "Retrieves all unique labels used across DAG definitions"
      operationId: "getAllDAGLabels"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/Workspace"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListLabelResponse"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/tags:
    get:
      summary: "List all available DAG tags"
      description: "Deprecated alias for /dags/labels. Retrieves all unique labels used across DAG definitions."
      operationId: "getAllDAGTags"
      deprecated: true
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/Workspace"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListTagResponse"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs:
    get:
      summary: "List all DAG-runs"
      description: "Retrieves a list of all DAG-runs with optional filtering by name and status"
      operationId: "listDAGRuns"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/StatusList"
        - $ref: "#/components/parameters/DateTimeFrom"
        - $ref: "#/components/parameters/DateTimeTo"
        - $ref: "#/components/parameters/DAGRunIdSearch"
        - $ref: "#/components/parameters/DAGRunListLimit"
        - $ref: "#/components/parameters/DAGRunListCursor"
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/Workspace"
        - name: "name"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Filter DAG-runs by name"
        - name: "labels"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Filter DAG-runs by DAG labels (comma-separated). Returns runs from DAGs that have ALL specified labels. Mutually exclusive with `tags`; the server returns HTTP 400 if both are set."
        - name: "tags"
          in: "query"
          required: false
          schema:
            type: "string"
          deprecated: true
          description: "Deprecated alias for `labels`; mutually exclusive with `labels`. Filter DAG-runs by DAG labels (comma-separated)."
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DAGRunsPageResponse"
        "400":
          description: "Malformed cursor or invalid pagination parameters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: "Create and execute a DAG-run from inline spec"
      description: |
        Creates a DAG-run directly from a provided DAG specification (YAML) and starts execution.

        This endpoint does not require a pre-existing DAG file; the supplied `spec` is parsed and validated
        similarly to `/dags/validate`, and the run is executed immediately if valid.
      operationId: "executeDAGRunFromSpec"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spec:
                  type: string
                  description: "DAG specification in YAML format"
                name:
                  type: string
                  description: "Optional name to use when the spec omits a name"
                profile:
                  $ref: "#/components/schemas/RuntimeProfileOverride"
                  description: "Runtime profile to apply to this DAG-run. Set to an empty string or omit to run without a profile."
                params:
                  type: string
                  description: "Parameters to pass to the DAG-run in JSON format"
                dagRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunId"
                    - description: "Optional ID for the DAG-run; if omitted, a new one is generated"
                singleton:
                  type: boolean
                  description: "If true, prevent starting if a DAG with the same name is already running (returns 409)"
                  default: false
                labels:
                  $ref: "#/components/schemas/Labels"
                  description: "Additional labels to apply to the DAG-run. Mutually exclusive with `tags`; the server returns HTTP 400 if both are set."
                tags:
                  $ref: "#/components/schemas/Tags"
                  description: "Deprecated alias for `labels`; mutually exclusive with `labels`."
              required:
                - spec
      responses:
        "200":
          description: "Run created and started"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRunId:
                    $ref: "#/components/schemas/DAGRunId"
                required:
                  - dagRunId
        "400":
          description: "Invalid DAG spec or parameters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "A DAG with the same name is already running and singleton is enabled"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/enqueue:
    post:
      summary: "Enqueue a DAG-run from inline spec"
      description: |
        Creates a DAG-run directly from a provided DAG specification (YAML) and enqueues it for execution.

        This endpoint does not require a pre-existing DAG file; the supplied `spec` is parsed and validated
        similarly to `/dags/validate`, and the run is persisted to the queue if valid.
      operationId: "enqueueDAGRunFromSpec"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spec:
                  type: string
                  description: "DAG specification in YAML format"
                name:
                  type: string
                  description: "Optional name to use when the spec omits a name"
                profile:
                  $ref: "#/components/schemas/RuntimeProfileOverride"
                  description: "Runtime profile to apply to this queued DAG-run. Set to an empty string or omit to run without a profile."
                params:
                  type: string
                  description: "Parameters to persist with the queued DAG-run in JSON format"
                dagRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunId"
                    - description: "Optional ID for the DAG-run; if omitted a new one will be generated"
                queue:
                  type: string
                  description: "Override the queue to use for this DAG-run"
                singleton:
                  type: boolean
                  description: "If true, prevent enqueuing if DAG is already running or queued (returns 409 conflict)"
                  default: false
                labels:
                  $ref: "#/components/schemas/Labels"
                  description: "Additional labels to apply to the DAG-run. Mutually exclusive with `tags`; the server returns HTTP 400 if both are set."
                tags:
                  $ref: "#/components/schemas/Tags"
                  description: "Deprecated alias for `labels`; mutually exclusive with `labels`."
              required:
                - spec
      responses:
        "200":
          description: "DAG-run successfully enqueued"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRunId:
                    $ref: "#/components/schemas/DAGRunId"
                required:
                  - dagRunId
        "400":
          description: "Invalid DAG spec or parameters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "DAG is already running or queued (singleton mode), or dagRunId already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}:
    get:
      summary: "List all DAG-runs with a specific name"
      description: "Retrieves a list of all DAG-runs with optional filtering by name and status"
      operationId: "listDAGRunsByName"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/StatusList"
        - $ref: "#/components/parameters/DateTimeFrom"
        - $ref: "#/components/parameters/DateTimeTo"
        - $ref: "#/components/parameters/DAGRunName"
        - $ref: "#/components/parameters/DAGRunIdSearch"
        - $ref: "#/components/parameters/DAGRunListLimit"
        - $ref: "#/components/parameters/DAGRunListCursor"
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/Workspace"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DAGRunsPageResponse"
        "400":
          description: "Malformed cursor or invalid pagination parameters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}:
    get:
      summary: "Retrieve detailed status of a DAG-run"
      description: "Fetches detailed status information about a specific DAG-run. Use 'latest' as the dagRunId to retrieve the most recent DAG-run for the specified DAG name."
      operationId: "getDAGRunDetails"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRunDetails:
                    $ref: "#/components/schemas/DAGRunDetails"
                required:
                  - dagRunDetails
        "404":
          description: "DAGRun not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete a DAG-run"
      description: "Permanently removes a DAG-run record and its associated run data. Developer, manager, or admin only."
      operationId: "deleteDAGRun"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunConcreteId"
      responses:
        "204":
          description: "DAG-run successfully deleted"
        "400":
          description: "DAG-run cannot be deleted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG-run not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/spec:
    get:
      summary: "Retrieve DAG specification for a DAG-run"
      description: "Fetches the YAML specification of the DAG definition associated with this DAG-run"
      operationId: "getDAGRunSpec"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  spec:
                    type: string
                    description: "The DAG spec in YAML format"
                required:
                  - spec
        "404":
          description: "DAG-run or DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/reschedule:
    post:
      summary: "Reschedule DAG-run with a new run ID"
      description: "Launch a fresh DAG-run from a historic execution while reusing its stored parameters."
      operationId: "rescheduleDAGRun"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                dagRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunId"
                    - description: "Explicit run ID for the new DAG-run; if omitted a new ID is generated."
                dagName:
                  type: string
                  description: "Optional DAG name override for the new run."
                useCurrentDagFile:
                  type: boolean
                  description: "When true, reschedule from the current contents of the original DAG file instead of the stored historical YAML snapshot."
      responses:
        "200":
          description: "Successfully scheduled a new DAG-run"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRunId:
                    $ref: "#/components/schemas/DAGRunId"
                  queued:
                    type: boolean
                    description: "Indicates whether the run was queued instead of starting immediately."
                required:
                  - dagRunId
                  - queued
        "400":
          description: "Invalid request parameters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Historic run not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict (run ID already exists)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/edit-retry/preview:
    post:
      summary: "Preview edited DAG-run retry"
      description: "Validates an edited DAG definition against a previous DAG-run and returns the default step skip selection."
      operationId: "previewEditRetryDAGRun"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spec:
                  type: string
                  description: "Edited DAG specification in YAML format."
                dagName:
                  type: string
                  description: "Optional DAG name override for the edited retry run."
              required:
                - spec
      responses:
        "200":
          description: "Successfully previewed the edited retry"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagName:
                    type: string
                    description: "Resolved DAG name for the edited retry."
                  skippedSteps:
                    type: array
                    description: "Default steps selected to be skipped."
                    items:
                      type: string
                  runnableSteps:
                    type: array
                    description: "Steps that will be started if not skipped."
                    items:
                      type: string
                  steps:
                    type: array
                    description: "Resolved edited DAG steps in execution order for preview rendering."
                    items:
                      $ref: "#/components/schemas/Step"
                  ineligibleSteps:
                    type: array
                    description: "Previous completed steps that cannot be skipped with the edited specification."
                    items:
                      type: object
                      properties:
                        stepName:
                          type: string
                        reason:
                          type: string
                      required:
                        - stepName
                        - reason
                  errors:
                    type: array
                    description: "Validation errors that must be fixed before launching."
                    items:
                      type: string
                  warnings:
                    type: array
                    description: "Non-blocking warnings for the edited retry."
                    items:
                      type: string
                required:
                  - dagName
                  - skippedSteps
                  - runnableSteps
                  - steps
                  - ineligibleSteps
                  - errors
                  - warnings
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/edit-retry:
    post:
      summary: "Run edited DAG retry"
      description: "Creates a new DAG-run from an edited DAG definition while preserving outputs from selected skipped steps."
      operationId: "editRetryDAGRun"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spec:
                  type: string
                  description: "Edited DAG specification in YAML format."
                dagRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunCreateId"
                    - description: "Explicit run ID for the new DAG-run; if omitted a new ID is generated."
                dagName:
                  type: string
                  description: "Optional DAG name override for the edited retry run."
                skipSteps:
                  type: array
                  description: "Steps to mark skipped while preserving their previous output variables."
                  items:
                    type: string
              required:
                - spec
      responses:
        "200":
          description: "Successfully launched edited retry"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRunId:
                    $ref: "#/components/schemas/DAGRunId"
                  queued:
                    type: boolean
                    description: "Indicates whether the run was queued instead of starting immediately."
                  skippedSteps:
                    type: array
                    items:
                      type: string
                  startedSteps:
                    type: array
                    items:
                      type: string
                required:
                  - dagRunId
                  - queued
                  - skippedSteps
                  - startedSteps
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs:
    get:
      summary: "Get sub DAG runs with timing info"
      description: "Retrieves timing and status information for all sub DAG runs (including repeated executions) of a specific step. When parentSubDAGRunId is provided, returns sub-runs of that specific sub DAG run (for multi-level nested DAGs)."
      operationId: "getSubDAGRuns"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "parentSubDAGRunId"
          in: "query"
          required: false
          schema:
            type: "string"
          description: "Optional parent sub DAG run ID. When provided, returns sub-runs of this specific sub DAG run instead of the root DAG run. Used for multi-level nested DAGs."
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  subRuns:
                    type: array
                    items:
                      $ref: "#/components/schemas/SubDAGRunDetail"
                required:
                  - subRuns
        "404":
          description: "DAG run not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/dequeue:
    get:
      summary: "Dequeue a queued DAG-run"
      description: "Dequeue a DAG-run execution that is currently queued"
      operationId: "dequeueDAGRun"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      responses:
        "200":
          description: "A successful response"
        "404":
          description: "DAGRun not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/log:
    get:
      summary: "Retrieve full execution log of a DAG-run"
      description: "Fetches the execution log for a DAG-run"
      operationId: "getDAGRunLog"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/Tail"
        - $ref: "#/components/parameters/Head"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Limit"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Log"
        "404":
          description: "Log file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/log/download:
    get:
      summary: "Download full execution log of a DAG-run"
      description: "Downloads the entire execution log file for a DAG-run"
      operationId: "downloadDAGRunLog"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      responses:
        "200":
          description: "Log file content"
          headers:
            Content-Disposition:
              schema:
                type: "string"
              description: "Attachment filename"
          content:
            text/plain:
              schema:
                type: "string"
        "404":
          description: "Log file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/artifacts:
    get:
      summary: "List artifacts for a DAG-run"
      description: "Returns the artifact file tree for a DAG-run"
      operationId: "getDAGRunArtifacts"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/ArtifactRecursive"
      responses:
        "200":
          description: "Artifact tree retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactTreeResponse"
        "404":
          description: "Artifact directory not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/artifacts/preview:
    get:
      summary: "Preview an artifact for a DAG-run"
      description: "Returns preview metadata and text content for a single artifact file"
      operationId: "getDAGRunArtifactPreview"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/ArtifactPath"
      responses:
        "200":
          description: "Artifact preview retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactPreviewResponse"
        "404":
          description: "Artifact file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/artifacts/download:
    get:
      summary: "Download an artifact for a DAG-run"
      description: "Downloads a single artifact file from a DAG-run"
      operationId: "downloadDAGRunArtifact"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/ArtifactPath"
      responses:
        "200":
          description: "Artifact file content"
          headers:
            Content-Disposition:
              schema:
                type: "string"
              description: "Attachment filename"
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          description: "Artifact file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/outputs:
    get:
      summary: "Retrieve collected outputs from a DAG-run"
      description: "Fetches the outputs.json file containing all step outputs collected during the DAG-run execution. Returns the outputs as a JSON object where keys are the output names (converted from UPPER_CASE to camelCase by default, or custom key if specified) and values are the captured output strings."
      operationId: "getDAGRunOutputs"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      responses:
        "200":
          description: "Successfully retrieved outputs. Returns the collected outputs with metadata. If the DAG-run completed but captured no outputs, returns an empty outputs object."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DAGRunOutputs"
        "404":
          description: "DAG-run not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/retry:
    post:
      summary: "Retry DAG-run execution"
      description: "Creates a new DAG-run based on a previous execution"
      operationId: "retryDAGRun"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                dagRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunId"
                    - description: "ID of the DAG-run to retry"
                stepName:
                  type: string
                  description: "Optional. If provided, only this step will be retried."
                subDAGRunId:
                  allOf:
                    - $ref: "#/components/schemas/DAGRunId"
                    - description: "Optional. Persisted child DAG-run containing the step. Requires stepName; the path and dagRunId remain the root DAG-run."
              required:
                - dagRunId
      responses:
        "200":
          description: "A successful response"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/human-tasks/{stepId}/complete:
    post:
      summary: "Complete a waiting human task"
      description: "Validates typed input against the stored human-task form, completes the step atomically, and queues the same DAG-run when no manual steps remain waiting."
      operationId: "completeHumanTask"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunConcreteId"
        - $ref: "#/components/parameters/HumanTaskStepId"
      requestBody:
        required: true
        description: "Typed form input. The JSON request body is limited to 16 MiB."
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HumanTaskInput"
      responses:
        "200":
          description: "Human task completed or an identical prior completion confirmed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HumanTaskCompletionResponse"
        "400":
          description: "Malformed or invalid human-task input"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG-run or human task not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Human task is not actionable or completion conflicts with current state"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "413":
          description: "Human-task input exceeds the 16 MiB request-body limit"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: "Completion was stored but the DAG-run retry could not be queued"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/human-tasks/resume:
    post:
      summary: "Queue a completed human-task checkpoint for resume"
      description: "Queues a retry for a completed human-task checkpoint without requiring the previously submitted form values."
      operationId: "resumeHumanTaskDAGRun"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunConcreteId"
      responses:
        "200":
          description: "The retry was queued or was already queued or running"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/HumanTaskResumeResponse"
        "404":
          description: "DAG-run not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "The DAG-run still has waiting steps or no recoverable human-task checkpoint"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: "The retry could not be queued and remains retryable"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/stop:
    post:
      summary: "Terminate or cancel a DAG-run"
      description: "Forcefully stops a running DAG-run, or cancels a failed root DAG-run that is still pending DAG-level automatic retry."
      operationId: "terminateDAGRun"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
      responses:
        "200":
          description: "A successful response"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/steps/{stepName}/log:
    get:
      summary: "Retrieve log for a specific step in a DAG-run"
      description: "Fetches the log for an individual step in a DAG-run"
      operationId: "getDAGRunStepLog"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/StepName"
        - $ref: "#/components/parameters/Tail"
        - $ref: "#/components/parameters/Head"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Stream"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Log"
        "404":
          description: "Log file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/steps/{stepName}/log/download:
    get:
      summary: "Download log for a specific step in a DAG-run"
      description: "Downloads the entire log file for an individual step in a DAG-run"
      operationId: "downloadDAGRunStepLog"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/StepName"
        - $ref: "#/components/parameters/Stream"
      responses:
        "200":
          description: "Log file content"
          headers:
            Content-Disposition:
              schema:
                type: "string"
              description: "Attachment filename"
          content:
            text/plain:
              schema:
                type: "string"
        "404":
          description: "Log file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/steps/{stepName}/messages:
    get:
      summary: "Retrieve chat messages for a step"
      description: "Fetches the LLM chat message history for a chat step. Returns empty array for non-chat steps."
      operationId: "getDAGRunStepMessages"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/StepName"
      responses:
        "200":
          description: "Chat messages retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatMessagesResponse"
        "404":
          description: "DAG-run or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/steps/{stepName}/status:
    patch:
      summary: "Manually update a step's execution status"
      description: "Changes the status of a specific step after the DAG-run is no longer active"
      operationId: "updateDAGRunStepStatus"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/StepName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: "#/components/schemas/NodeStatus"
              required:
                - status
      responses:
        "200":
          description: "A successful response"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAGRun or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/steps/{stepName}/approve:
    post:
      summary: "Approve a waiting step"
      description: "Approves a step that is in Waiting status, optionally providing input parameters that will be available as environment variables in subsequent steps"
      operationId: "approveDAGRunStep"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/StepName"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApproveStepRequest"
      responses:
        "200":
          description: "Step approved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApproveStepResponse"
        "400":
          description: "Step is not in Waiting status or required inputs missing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG-run or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/steps/{stepName}/reject:
    post:
      summary: "Reject a waiting step"
      description: "Rejects a step that is in Waiting status, optionally providing a reason for rejection"
      operationId: "rejectDAGRunStep"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/StepName"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RejectStepRequest"
      responses:
        "200":
          description: "Step rejected successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectStepResponse"
        "400":
          description: "Step is not in Waiting status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG-run or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/steps/{stepName}/push-back:
    post:
      summary: "Push back a waiting step for re-execution with feedback"
      description: "Pushes back a step that is in Waiting status, providing input parameters that will be injected as environment variables when the step re-executes. The step must have an approval configuration."
      operationId: "pushBackDAGRunStep"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/StepName"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PushBackStepRequest"
      responses:
        "200":
          description: "Step pushed back successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PushBackStepResponse"
        "400":
          description: "Step is not in Waiting status, missing required inputs, or step does not have approval config"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG-run or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}:
    get:
      summary: "Retrieve detailed status of a sub DAG-run"
      description: "Fetches detailed status information about a specific sub DAG-run"
      operationId: "getSubDAGRunDetails"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to retrieve details for"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                type: object
                properties:
                  dagRunDetails:
                    $ref: "#/components/schemas/DAGRunDetails"
                required:
                  - dagRunDetails
        "404":
          description: "Sub DAG-run not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/spec:
    get:
      summary: "Get Sub-DAG Run Specification"
      description: "Returns the YAML specification used for a specific sub-DAG run"
      operationId: "getSubDAGRunSpec"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to retrieve the spec for"
      responses:
        "200":
          description: "Sub-DAG specification retrieved successfully"
          content:
            application/json:
              schema:
                type: object
                required:
                  - spec
                properties:
                  spec:
                    type: string
                    description: "YAML specification of the sub-DAG"
        "404":
          description: "Sub-DAG run not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/log:
    get:
      summary: "Retrieve log for a specific sub DAG-run"
      description: "Fetches the log for an individual sub DAG-run"
      operationId: "getSubDAGRunLog"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/Tail"
        - $ref: "#/components/parameters/Head"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Limit"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to retrieve the log for"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Log"
        "404":
          description: "Log file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/log/download:
    get:
      summary: "Download log for a specific sub DAG-run"
      description: "Downloads the entire log file for an individual sub DAG-run"
      operationId: "downloadSubDAGRunLog"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to download the log for"
      responses:
        "200":
          description: "Log file content"
          headers:
            Content-Disposition:
              schema:
                type: "string"
              description: "Attachment filename"
          content:
            text/plain:
              schema:
                type: "string"
        "404":
          description: "Log file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/artifacts:
    get:
      summary: "List artifacts for a sub DAG-run"
      description: "Returns the artifact file tree for a specific sub DAG-run"
      operationId: "getSubDAGRunArtifacts"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to retrieve artifacts for"
        - $ref: "#/components/parameters/ArtifactRecursive"
      responses:
        "200":
          description: "Artifact tree retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactTreeResponse"
        "404":
          description: "Artifact directory not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/artifacts/preview:
    get:
      summary: "Preview an artifact for a sub DAG-run"
      description: "Returns preview metadata and text content for a single sub DAG-run artifact file"
      operationId: "getSubDAGRunArtifactPreview"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to preview an artifact for"
        - $ref: "#/components/parameters/ArtifactPath"
      responses:
        "200":
          description: "Artifact preview retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ArtifactPreviewResponse"
        "404":
          description: "Artifact file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/artifacts/download:
    get:
      summary: "Download an artifact for a sub DAG-run"
      description: "Downloads a single artifact file from a sub DAG-run"
      operationId: "downloadSubDAGRunArtifact"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to download an artifact for"
        - $ref: "#/components/parameters/ArtifactPath"
      responses:
        "200":
          description: "Artifact file content"
          headers:
            Content-Disposition:
              schema:
                type: "string"
              description: "Attachment filename"
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          description: "Artifact file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/steps/{stepName}/log:
    get:
      summary: "Retrieve log for a specific step in a sub DAG-run"
      description: "Fetches the log for an individual step in a sub DAG-run"
      operationId: "getSubDAGRunStepLog"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - $ref: "#/components/parameters/Tail"
        - $ref: "#/components/parameters/Head"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Stream"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to retrieve the log for"
        - $ref: "#/components/parameters/StepName"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Log"
        "404":
          description: "Log file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/steps/{stepName}/log/download:
    get:
      summary: "Download log for a specific step in a sub DAG-run"
      description: "Downloads the entire log file for an individual step in a sub DAG-run"
      operationId: "downloadSubDAGRunStepLog"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to download the step log for"
        - $ref: "#/components/parameters/StepName"
        - $ref: "#/components/parameters/Stream"
      responses:
        "200":
          description: "Log file content"
          headers:
            Content-Disposition:
              schema:
                type: "string"
              description: "Attachment filename"
          content:
            text/plain:
              schema:
                type: "string"
        "404":
          description: "Log file not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/steps/{stepName}/messages:
    get:
      summary: "Retrieve chat messages for a step in a sub DAG-run"
      description: "Fetches the LLM chat message history for a chat step in a sub DAG-run. Returns empty array for non-chat steps."
      operationId: "getSubDAGRunStepMessages"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run"
        - $ref: "#/components/parameters/StepName"
      responses:
        "200":
          description: "Chat messages retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatMessagesResponse"
        "404":
          description: "Sub DAG-run or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/steps/{stepName}/status:
    patch:
      summary: "Manually update a step's execution status in a sub DAG-run"
      description: "Changes the status of a specific step after the sub DAG-run and its embedded root run are no longer active"
      operationId: "updateSubDAGRunStepStatus"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run to update the step status for"
        - $ref: "#/components/parameters/StepName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  $ref: "#/components/schemas/NodeStatus"
              required:
                - status
      responses:
        "200":
          description: "A successful response"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAGRun or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/steps/{stepName}/approve:
    post:
      summary: "Approve a waiting step in a sub DAG-run"
      description: "Approves a step that is in Waiting status within a sub DAG-run, optionally providing input parameters that will be available as environment variables in subsequent steps"
      operationId: "approveSubDAGRunStep"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run containing the step to approve"
        - $ref: "#/components/parameters/StepName"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApproveStepRequest"
      responses:
        "200":
          description: "Step approved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApproveStepResponse"
        "400":
          description: "Step is not in Waiting status or required inputs missing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Sub DAG-run or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/steps/{stepName}/reject:
    post:
      summary: "Reject a waiting step in a sub DAG-run"
      description: "Rejects a step that is in Waiting status within a sub DAG-run, optionally providing a reason for rejection"
      operationId: "rejectSubDAGRunStep"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run containing the step to reject"
        - $ref: "#/components/parameters/StepName"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RejectStepRequest"
      responses:
        "200":
          description: "Step rejected successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RejectStepResponse"
        "400":
          description: "Step is not in Waiting status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Sub DAG-run or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dag-runs/{name}/{dagRunId}/sub-dag-runs/{subDAGRunId}/steps/{stepName}/push-back:
    post:
      summary: "Push back a waiting step in a sub DAG-run for re-execution with feedback"
      description: "Pushes back a step that is in Waiting status within a sub DAG-run, providing input parameters that will be injected as environment variables when the step re-executes. The step must have an approval configuration."
      operationId: "pushBackSubDAGRunStep"
      tags:
        - "dag-runs"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGName"
        - $ref: "#/components/parameters/DAGRunId"
        - name: "subDAGRunId"
          in: "path"
          required: true
          schema:
            type: "string"
          description: "ID of the sub DAG-run containing the step to push back"
        - $ref: "#/components/parameters/StepName"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PushBackStepRequest"
      responses:
        "200":
          description: "Step pushed back successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PushBackStepResponse"
        "400":
          description: "Step is not in Waiting status, missing required inputs, or step does not have approval config"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Sub DAG-run or step not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /queues:
    get:
      summary: "List all execution queues with summary statistics"
      description: "Returns queue list with running and queued counts. Use /queues/{name} for queue details and /queues/{name}/items for queued backlog browsing."
      operationId: "listQueues"
      tags:
        - "queues"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueuesResponse"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /queues/{name}:
    get:
      summary: "Get summary information for a specific queue"
      description: "Returns queue metadata, running items, and queued counts for the specified queue."
      operationId: "getQueue"
      tags:
        - "queues"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: name
          in: path
          description: "Queue name"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Queue"
        "404":
          description: "Queue not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /queues/{name}/items:
    get:
      summary: "Get queued items for a specific queue"
      description: "Returns one forward-only page of queued DAG-runs for the specified queue, ordered from the queue head toward the tail. The opaque cursor resumes after the last scanned queue entry."
      operationId: "listQueueItems"
      tags:
        - "queues"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/QueueListLimit"
        - $ref: "#/components/parameters/QueueListCursor"
        - name: name
          in: path
          description: "Queue name"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueuedDAGRunsPageResponse"
        "400":
          description: "Invalid cursor"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /services/resources/history:
    get:
      summary: "Get resource usage history"
      description: "Returns historical data for system resources. Developer, manager, or admin only."
      operationId: "getResourceHistory"
      tags:
        - "system"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: duration
          in: query
          description: "Duration of history to retrieve (e.g., 30m, 1h)"
          required: false
          schema:
            type: string
            default: "1h"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceHistory"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /services/scheduler:
    get:
      summary: "Get scheduler service status"
      description: "Returns status information about all registered scheduler instances. Developer, manager, or admin only."
      operationId: "getSchedulerStatus"
      tags:
        - "system"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SchedulerStatusResponse"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /services/coordinator:
    get:
      summary: "Get coordinator service status"
      description: "Returns status information about all registered coordinator instances. Developer, manager, or admin only."
      operationId: "getCoordinatorStatus"
      tags:
        - "system"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CoordinatorStatusResponse"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /services/tunnel:
    get:
      summary: "Get tunnel service status"
      description: "Returns status information about the tunnel service (Tailscale). Developer, manager, or admin only."
      operationId: "getTunnelStatus"
      tags:
        - "system"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "A successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TunnelStatusResponse"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /metrics:
    get:
      summary: "Get Prometheus metrics"
      description: "Returns Prometheus-compatible metrics for monitoring Dagu operations"
      operationId: "getMetrics"
      tags:
        - "monitoring"
      responses:
        "200":
          description: "Prometheus metrics in text format"
          content:
            text/plain:
              schema:
                type: string
                example: |
                  # HELP dagu_info Dagu build information
                  # TYPE dagu_info gauge
                  dagu_info{version="1.14.0",build_date="2024-01-01T12:00:00Z",go_version="1.21"} 1

                  # HELP dagu_uptime_seconds Time since server start
                  # TYPE dagu_uptime_seconds gauge
                  dagu_uptime_seconds 3600

                  # HELP dagu_dag_runs_currently_running Number of currently running DAG runs
                  # TYPE dagu_dag_runs_currently_running gauge
                  dagu_dag_runs_currently_running 5

                  # HELP dagu_dag_runs_queued_total Total number of DAG runs in queue
                  # TYPE dagu_dag_runs_queued_total gauge
                  dagu_dag_runs_queued_total 8

                  # HELP dagu_dag_runs_total Total number of DAG runs by status
                  # TYPE dagu_dag_runs_total counter
                  dagu_dag_runs_total{status="success"} 2493
                  dagu_dag_runs_total{status="error"} 15
                  dagu_dag_runs_total{status="aborted"} 7

                  # HELP dagu_dags_total Total number of DAGs
                  # TYPE dagu_dags_total gauge
                  dagu_dags_total 45

                  # HELP dagu_scheduler_running Whether the scheduler is running
                  # TYPE dagu_scheduler_running gauge
                  dagu_scheduler_running 1
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /webhooks/{fileName}:
    post:
      summary: "Trigger DAG execution via webhook"
      description: |
        Triggers a DAG execution via webhook. The DAG must have a webhook configured
        and enabled. Authentication depends on the webhook auth mode:
        bearer token only, bearer token plus HMAC, or HMAC only.

        The request body is passed to the DAG as the WEBHOOK_PAYLOAD environment
        variable. If the DAG configures `webhook.forward_headers`, selected
        request headers are passed as the WEBHOOK_HEADERS environment variable.
        For safety, the `Authorization` header is never forwarded.
        The DAG run is enqueued and the endpoint returns immediately with the
        dag-run ID.
      operationId: "triggerWebhook"
      tags:
        - "webhooks"
      security: []
      parameters:
        - $ref: "#/components/parameters/DAGFileName"
        - $ref: "#/components/parameters/RemoteNode"
        - name: Authorization
          in: header
          required: false
          schema:
            type: string
          description: "Bearer token for webhook authentication (e.g., 'Bearer dagu_wh_...'). Required only when the webhook auth mode includes token authentication."
        - name: X-Dagu-Signature
          in: header
          required: false
          schema:
            type: string
            pattern: '^sha256=[0-9a-fA-F]{64}$'
            example: "sha256=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
          description: "HMAC webhook signature in the format 'sha256=<hex>'. Required only when the webhook auth mode includes HMAC authentication with strict enforcement."
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookRequest"
      responses:
        "200":
          description: "DAG run triggered successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookResponse"
        "400":
          description: "Invalid request body"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Unauthorized - missing or invalid token, or invalid/missing X-Dagu-Signature when strict HMAC enforcement is active"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - webhook disabled or not configured"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG or webhook not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict - DAG run with the specified dagRunId already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /webhooks:
    get:
      summary: "List all webhooks"
      description: "Returns a list of all webhooks across all DAGs. Developer, manager, or admin only."
      operationId: "listWebhooks"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "List of webhooks"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookListResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /notification-settings:
    get:
      summary: "Get notification settings"
      description: "Returns workspace-level notification settings such as email delivery transport. Developer, manager, or admin only."
      operationId: "getNotificationSettings"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Workspace notification settings"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationWorkspaceSettings"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update notification settings"
      description: |
        Updates workspace-level notification settings. SMTP passwords are accepted
        in the request but are never returned. Omit password on updates to preserve
        the existing password, or set clearPassword to remove it. Developer,
        manager, or admin only.
      operationId: "updateNotificationSettings"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationWorkspaceSettingsInput"
      responses:
        "200":
          description: "Workspace notification settings updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationWorkspaceSettings"
        "400":
          description: "Invalid notification settings"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /notification-routes:
    get:
      summary: "List notification routes"
      description: "Returns global and workspace notification channel routes. Developer, manager, or admin only."
      operationId: "listNotificationRoutes"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "List of notification route sets"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationRouteSetListResponse"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /notification-routes/global:
    get:
      summary: "Get global notification routes"
      description: "Returns global default notification channel routes. Default DAGs use global routes; named workspaces can inherit or opt out. Developer, manager, or admin only."
      operationId: "getGlobalNotificationRoutes"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Global notification route set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationRouteSet"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update global notification routes"
      description: "Replaces global default notification channel routes. Route channel IDs must reference notification channels. Developer, manager, or admin only."
      operationId: "updateGlobalNotificationRoutes"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationRouteSetInput"
      responses:
        "200":
          description: "Global notification route set updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationRouteSet"
        "400":
          description: "Invalid notification route set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Referenced notification channel was not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /notification-routes/workspaces/{workspaceName}:
    get:
      summary: "Get workspace notification routes"
      description: "Returns notification channel routes for one named workspace. Workspace routes can inherit global defaults. Developer, manager, or admin only."
      operationId: "getWorkspaceNotificationRoutes"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
      responses:
        "200":
          description: "Workspace notification route set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationRouteSet"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace was not found or is not visible"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update workspace notification routes"
      description: "Replaces notification channel routes for one named workspace. Route channel IDs must reference notification channels. Developer, manager, or admin only."
      operationId: "updateWorkspaceNotificationRoutes"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationRouteSetInput"
      responses:
        "200":
          description: "Workspace notification route set updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationRouteSet"
        "400":
          description: "Invalid notification route set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace or referenced notification channel was not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /notification-channels:
    get:
      summary: "List notification channels"
      description: "Returns notification channels. Channels are delivery endpoints; routing is configured separately. Developer, manager, or admin only."
      operationId: "listNotificationChannels"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "List of notification channels"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannelListResponse"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: "Create notification channel"
      description: |
        Creates a notification channel. Secret values are accepted
        in the request but are never returned. Developer, manager, or admin only.
      operationId: "createNotificationChannel"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationChannelInput"
      responses:
        "201":
          description: "Notification channel created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannel"
        "400":
          description: "Invalid notification channel"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /notification-channels/{channelId}:
    get:
      summary: "Get notification channel"
      description: "Returns one notification channel. Developer, manager, or admin only."
      operationId: "getNotificationChannel"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: channelId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Notification channel"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannel"
        "404":
          description: "Notification channel not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update notification channel"
      description: |
        Replaces a notification channel. Existing secret values
        are preserved when omitted. Developer, manager, or admin only.
      operationId: "updateNotificationChannel"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: channelId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NotificationChannelInput"
      responses:
        "200":
          description: "Notification channel updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotificationChannel"
        "400":
          description: "Invalid notification channel"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Notification channel not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete notification channel"
      description: "Deletes a notification channel. Channels referenced by DAG notification settings or notification routes cannot be deleted."
      operationId: "deleteNotificationChannel"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: channelId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: "Notification channel deleted"
        "404":
          description: "Notification channel not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Notification channel is used by a DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /incident-providers:
    get:
      summary: "List incident providers"
      description: "Returns configured incident providers such as PagerDuty and SolarWinds Incident Response. Incident management requires an active Dagu license or trial. Developer, manager, or admin only."
      operationId: "listIncidentProviders"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "List of incident providers"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentProviderListResponse"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: "Create incident provider"
      description: "Creates an incident provider. Secret values are accepted in the request but are never returned. Developer, manager, or admin only."
      operationId: "createIncidentProvider"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentProviderInput"
      responses:
        "201":
          description: "Incident provider created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentProvider"
        "400":
          description: "Invalid incident provider"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /incident-providers/{providerId}:
    get:
      summary: "Get incident provider"
      description: "Returns one incident provider. Developer, manager, or admin only."
      operationId: "getIncidentProvider"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: providerId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Incident provider"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentProvider"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Incident provider not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update incident provider"
      description: "Replaces an incident provider. Existing secret values are preserved when omitted. Developer, manager, or admin only."
      operationId: "updateIncidentProvider"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: providerId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentProviderInput"
      responses:
        "200":
          description: "Incident provider updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentProvider"
        "400":
          description: "Invalid incident provider"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Incident provider not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete incident provider"
      description: "Deletes an incident provider. Providers referenced by incident routing cannot be deleted."
      operationId: "deleteIncidentProvider"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: providerId
          in: path
          required: true
          schema:
            type: string
      responses:
        "204":
          description: "Incident provider deleted"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Incident provider not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Incident provider is used by routing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /incident-providers/{providerId}/test:
    post:
      summary: "Send a test incident"
      description: "Sends a test trigger and resolve event to one incident provider. Developer, manager, or admin only."
      operationId: "testIncidentProvider"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: providerId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Test incident delivery attempted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestIncidentProviderResponse"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Incident provider not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /incident-policies:
    get:
      summary: "List incident routing"
      description: "Returns global, workspace, and DAG incident routing. Developer, manager, or admin only."
      operationId: "listIncidentPolicies"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "List of incident routing scopes"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPolicySetListResponse"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /incident-policies/global:
    get:
      summary: "Get global incident routing"
      description: "Returns global incident routing. Global routing is used unless a workspace or DAG override is configured. Developer, manager, or admin only."
      operationId: "getGlobalIncidentPolicies"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Global incident routing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPolicySet"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update global incident routing"
      description: "Replaces global incident routing. Route provider IDs must reference incident providers. Developer, manager, or admin only."
      operationId: "updateGlobalIncidentPolicies"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPolicySetInput"
      responses:
        "200":
          description: "Global incident routing updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPolicySet"
        "400":
          description: "Invalid incident routing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Referenced incident provider was not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /incident-policies/workspaces/{workspaceName}:
    get:
      summary: "Get workspace incident routing"
      description: "Returns incident routing for one named workspace. Workspace routing can inherit global routing. Developer, manager, or admin only."
      operationId: "getWorkspaceIncidentPolicies"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
      responses:
        "200":
          description: "Workspace incident routing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPolicySet"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace was not found or is not visible"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update workspace incident routing"
      description: "Replaces incident routing for one named workspace. Route provider IDs must reference incident providers. Developer, manager, or admin only."
      operationId: "updateWorkspaceIncidentPolicies"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPolicySetInput"
      responses:
        "200":
          description: "Workspace incident routing updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPolicySet"
        "400":
          description: "Invalid incident routing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace or referenced incident provider was not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/webhook:
    get:
      summary: "Get webhook for DAG"
      description: "Returns the webhook configuration for a specific DAG, if one exists."
      operationId: "getDAGWebhook"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "Webhook configuration"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDetails"
        "404":
          description: "No webhook configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    post:
      summary: "Create webhook for DAG"
      description: |
        Creates a new webhook for the specified DAG. Returns the full webhook token,
        which is only shown once. Store it securely.
        Developer, manager, or admin only.
      operationId: "createDAGWebhook"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "201":
          description: "Webhook created successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookCreateResponse"
        "409":
          description: "Webhook already exists for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete webhook for DAG"
      description: "Removes the webhook configuration for the specified DAG. Developer, manager, or admin only."
      operationId: "deleteDAGWebhook"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "204":
          description: "Webhook deleted successfully"
        "404":
          description: "No webhook configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/webhook/regenerate:
    post:
      summary: "Regenerate webhook token"
      description: |
        Generates a new token for the existing webhook. The old token becomes
        invalid immediately. Returns the new token, which is only shown once.
        Developer, manager, or admin only.
      operationId: "regenerateDAGWebhookToken"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "Token regenerated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookCreateResponse"
        "404":
          description: "No webhook configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/webhook/toggle:
    post:
      summary: "Toggle webhook enabled state"
      description: "Enables or disables the webhook without changing the token. Developer, manager, or admin only."
      operationId: "toggleDAGWebhook"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookToggleRequest"
      responses:
        "200":
          description: "Webhook toggled successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDetails"
        "404":
          description: "No webhook configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/webhook/hmac/enable:
    post:
      summary: "Enable webhook HMAC"
      description: |
        Enables HMAC authentication for the existing webhook and returns the generated
        HMAC secret exactly once. If enforcementMode is omitted, it defaults to
        strict. Developer, manager, or admin only.
      operationId: "enableDAGWebhookHMAC"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookHMACConfigureRequest"
            examples:
              token_and_hmac_strict:
                value:
                  authMode: token_and_hmac
                  enforcementMode: strict
              token_and_hmac_observe:
                value:
                  authMode: token_and_hmac
                  enforcementMode: observe
              hmac_only:
                value:
                  authMode: hmac_only
      responses:
        "200":
          description: "Webhook HMAC enabled successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookHMACSecretResponse"
        "400":
          description: "Invalid request or invalid HMAC configuration"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "501":
          description: "Webhook HMAC is not supported on this node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "No webhook configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/webhook/hmac/configure:
    post:
      summary: "Configure webhook HMAC"
      description: |
        Updates the webhook HMAC auth mode or enforcement mode without rotating
        the secret. If enforcementMode is omitted, the current enforcement mode
        is preserved for token_and_hmac, while hmac_only always uses strict.
        Developer, manager, or admin only.
      operationId: "configureDAGWebhookHMAC"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookHMACConfigureRequest"
            examples:
              token_and_hmac_strict:
                value:
                  authMode: token_and_hmac
                  enforcementMode: strict
              token_and_hmac_observe:
                value:
                  authMode: token_and_hmac
                  enforcementMode: observe
              hmac_only:
                value:
                  authMode: hmac_only
      responses:
        "200":
          description: "Webhook HMAC updated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDetails"
        "400":
          description: "Invalid request or invalid HMAC configuration"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "501":
          description: "Webhook HMAC is not supported on this node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "No webhook configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/webhook/hmac/regenerate:
    post:
      summary: "Regenerate webhook HMAC secret"
      description: |
        Generates a new HMAC secret for the existing webhook. The old secret becomes
        invalid immediately. Returns the new secret exactly once.
        Developer, manager, or admin only.
      operationId: "regenerateDAGWebhookHMACSecret"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "Webhook HMAC secret regenerated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookHMACSecretResponse"
        "400":
          description: "Webhook HMAC is not configured"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "501":
          description: "Webhook HMAC is not supported on this node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "No webhook configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/webhook/hmac/disable:
    post:
      summary: "Disable webhook HMAC"
      description: "Disables HMAC authentication and returns the webhook to token-only mode. Developer, manager, or admin only."
      operationId: "disableDAGWebhookHMAC"
      tags:
        - "webhooks"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "Webhook HMAC disabled successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDetails"
        "501":
          description: "Webhook HMAC is not supported on this node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "No webhook configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/settings:
    get:
      summary: "Get DAG settings"
      description: "Returns server-side settings for a specific DAG."
      operationId: "getDAGSettings"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "DAG settings"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DAGSettings"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update DAG settings"
      description: "Creates or replaces server-side settings for a specific DAG. Manager or admin only; protected profiles require admin."
      operationId: "updateDAGSettings"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateDAGSettingsRequest"
      responses:
        "200":
          description: "DAG settings updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DAGSettings"
        "400":
          description: "Invalid DAG settings"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG or runtime profile not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete DAG settings"
      description: "Removes server-side settings for the specified DAG. Manager or admin only."
      operationId: "deleteDAGSettings"
      tags:
        - "dags"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "204":
          description: "DAG settings deleted"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/notifications:
    get:
      summary: "Get DAG notification settings"
      description: "Returns server-side notification settings for a specific DAG. Developer, manager, or admin only."
      operationId: "getDAGNotifications"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "DAG notification settings"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DAGNotificationSettings"
        "404":
          description: "No notification settings configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update DAG notification settings"
      description: |
        Creates or replaces server-side notification settings for a DAG.
        Secret values are accepted in the request but are never returned.
        Existing secret values are preserved when omitted for an existing target.
        Developer, manager, or admin only.
      operationId: "updateDAGNotifications"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateDAGNotificationsRequest"
      responses:
        "200":
          description: "DAG notification settings updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DAGNotificationSettings"
        "400":
          description: "Invalid notification settings"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete DAG notification settings"
      description: "Removes all server-side notification settings for the specified DAG. Developer, manager, or admin only."
      operationId: "deleteDAGNotifications"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "204":
          description: "DAG notification settings deleted"
        "404":
          description: "No notification settings configured for this DAG"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/notifications/test:
    post:
      summary: "Send a test DAG notification"
      description: "Sends a test notification to one target or every enabled target for a DAG. Developer, manager, or admin only."
      operationId: "testDAGNotifications"
      tags:
        - "notifications"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TestDAGNotificationRequest"
      responses:
        "200":
          description: "Test notification delivery attempted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestDAGNotificationResponse"
        "400":
          description: "Invalid test notification request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG or target not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /dags/{fileName}/incidents:
    get:
      summary: "Get DAG incident routing"
      description: "Returns DAG-level incident routing override settings. Missing settings mean this DAG inherits workspace or global routing. Developer, manager, or admin only."
      operationId: "getDAGIncidents"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "200":
          description: "DAG incident routing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPolicySet"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update DAG incident routing"
      description: "Creates or replaces DAG-level incident routing override settings. Route provider IDs must reference incident providers. Developer, manager, or admin only."
      operationId: "updateDAGIncidents"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/IncidentPolicySetInput"
      responses:
        "200":
          description: "DAG incident routing updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/IncidentPolicySet"
        "400":
          description: "Invalid incident routing"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG or referenced incident provider was not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    delete:
      summary: "Delete DAG incident routing"
      description: "Removes DAG-level incident routing override settings so the DAG inherits workspace or global routing. Developer, manager, or admin only."
      operationId: "deleteDAGIncidents"
      tags:
        - "incidents"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - $ref: "#/components/parameters/DAGFileName"
      responses:
        "204":
          description: "DAG incident routing deleted"
        "403":
          description: "Forbidden - requires an active Dagu license or trial"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG incident policies not configured"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /audit:
    get:
      summary: "List audit log entries"
      description: "Returns audit log entries matching the filter criteria. Manager or admin only."
      operationId: "listAuditLogs"
      tags:
        - "audit"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: category
          in: query
          description: "Filter by audit category (e.g., terminal, user, dag)"
          required: false
          schema:
            type: string
        - name: action
          in: query
          description: "Filter by audit action"
          required: false
          schema:
            type: string
        - name: source
          in: query
          description: "Filter by audit source (e.g., mcp, ui, rest, cli)"
          required: false
          schema:
            type: string
        - name: surface
          in: query
          description: "Filter by accepted credential surface (e.g., mcp, rest_api)"
          required: false
          schema:
            type: string
        - name: result
          in: query
          description: "Filter by result (succeeded, failed, denied)"
          required: false
          schema:
            type: string
        - name: correlationId
          in: query
          description: "Filter by correlation ID"
          required: false
          schema:
            type: string
        - name: resourceType
          in: query
          description: "Filter by resource type"
          required: false
          schema:
            type: string
        - name: resourceId
          in: query
          description: "Filter by resource ID"
          required: false
          schema:
            type: string
        - name: workspace
          in: query
          description: "Filter by canonical workspace"
          required: false
          schema:
            type: string
        - name: credentialId
          in: query
          description: "Filter by credential ID"
          required: false
          schema:
            type: string
        - name: credentialType
          in: query
          description: "Filter by credential type"
          required: false
          schema:
            type: string
        - name: mcpTool
          in: query
          description: "Filter by MCP tool name"
          required: false
          schema:
            type: string
        - name: ipAddress
          in: query
          description: "Filter by client IP address"
          required: false
          schema:
            type: string
        - name: userId
          in: query
          description: "Filter by user ID"
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/LogStartTime"
        - $ref: "#/components/parameters/LogEndTime"
        - $ref: "#/components/parameters/AuditLogLimit"
        - $ref: "#/components/parameters/LogOffset"
      responses:
        "200":
          description: "List of audit log entries"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuditLogsResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires manager or admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /event-logs:
    get:
      summary: "List centralized event log entries"
      description: "Returns centralized event log entries matching the filter criteria. Manager or admin only."
      operationId: "listEventLogs"
      tags:
        - "events"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: kind
          in: query
          description: "Filter by event kind (e.g., dag_run, llm_usage)"
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: "Filter by event type (e.g., dag.run.failed, llm.usage.recorded)"
          required: false
          schema:
            type: string
        - name: dagName
          in: query
          description: "Filter by DAG name"
          required: false
          schema:
            type: string
        - name: dagRunId
          in: query
          description: "Filter by DAG run ID"
          required: false
          schema:
            type: string
        - name: attemptId
          in: query
          description: "Filter by attempt ID"
          required: false
          schema:
            type: string
        - name: sessionId
          in: query
          description: "Filter by session ID"
          required: false
          schema:
            type: string
        - name: userId
          in: query
          description: "Filter by user ID"
          required: false
          schema:
            type: string
        - name: model
          in: query
          description: "Filter by model name"
          required: false
          schema:
            type: string
        - $ref: "#/components/parameters/LogStartTime"
        - $ref: "#/components/parameters/LogEndTime"
        - $ref: "#/components/parameters/EventLogLimit"
        - $ref: "#/components/parameters/EventLogPaginationMode"
        - $ref: "#/components/parameters/LogOffset"
        - $ref: "#/components/parameters/EventLogCursor"
      responses:
        "200":
          description: "List of event log entries"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EventLogsResponse"
        "400":
          description: "Malformed cursor or invalid pagination parameters"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Forbidden - requires manager or admin role"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  # Git Sync endpoints
  /sync/status:
    get:
      summary: "Get Git sync status"
      description: "Returns the overall Git sync status including status of all DAGs"
      operationId: "getSyncStatus"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Sync status retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncStatusResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/pull:
    post:
      summary: "Pull changes from remote repository"
      description: "Fetches and syncs changes from the remote Git repository"
      operationId: "syncPull"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Pull completed successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncResultResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/publish-all:
    post:
      summary: "Publish selected DAGs"
      description: "Commits and pushes the specified DAG IDs. If itemIds is omitted, publishes all modified or untracked DAGs."
      operationId: "syncPublishAll"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyncPublishAllRequest"
      responses:
        "200":
          description: "Publish completed successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncResultResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/test-connection:
    post:
      summary: "Test connection to remote repository"
      description: "Tests authentication and connectivity to the configured Git repository"
      operationId: "syncTestConnection"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Connection test result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncConnectionTestResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/config:
    get:
      summary: "Get Git sync configuration"
      description: "Returns the current Git sync configuration"
      operationId: "getSyncConfig"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Configuration retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncConfigResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: "Update Git sync configuration"
      description: "Updates the Git sync configuration"
      operationId: "updateSyncConfig"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyncConfigUpdateRequest"
      responses:
        "200":
          description: "Configuration updated successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncConfigResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/items/{itemId}/diff:
    get:
      summary: "Get diff for a DAG"
      description: "Returns the diff between local and remote versions of a DAG"
      operationId: "getSyncItemDiff"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: itemId
          in: path
          description: "The DAG identifier (file path without extension)"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Diff retrieved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncItemDiffResponse"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/items/{itemId}/publish:
    post:
      summary: "Publish a single DAG"
      description: "Commits and pushes a single DAG to the remote repository"
      operationId: "publishSyncItem"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: itemId
          in: path
          description: "The DAG identifier (file path without extension)"
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyncPublishRequest"
      responses:
        "200":
          description: "DAG published successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncResultResponse"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict detected"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncConflictResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/items/{itemId}/discard:
    post:
      summary: "Discard local changes for a DAG"
      description: "Discards local changes and reverts to the version in the remote repository"
      operationId: "discardSyncItemChanges"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: itemId
          in: path
          description: "The DAG identifier (file path without extension)"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "Changes discarded successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/items/{itemId}/forget:
    post:
      summary: "Forget a DAG"
      description: "Removes the state entry for a missing, untracked, or conflicting DAG. Synced and modified DAGs are rejected."
      operationId: "forgetSyncItem"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: itemId
          in: path
          description: "The DAG identifier (file path without extension)"
          required: true
          schema:
            type: string
      responses:
        "200":
          description: "DAG forgotten successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: "DAG cannot be forgotten"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/items/{itemId}/delete:
    post:
      summary: "Delete a DAG"
      description: "Removes a DAG from the remote repository (git rm + commit + push), local disk, and sync state"
      operationId: "deleteSyncItem"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: itemId
          in: path
          description: "The DAG identifier (file path without extension)"
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: "Commit message for the deletion"
                force:
                  type: boolean
                  description: "Force delete even if the DAG has local modifications"
      responses:
        "200":
          description: "DAG deleted successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: "DAG cannot be deleted"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/items/{itemId}/move:
    post:
      summary: "Move a DAG"
      description: "Atomically renames a DAG across local filesystem, remote repository, and sync state"
      operationId: "moveSyncItem"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: itemId
          in: path
          description: "The current DAG identifier (file path without extension)"
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                newItemId:
                  type: string
                  description: "The new DAG identifier"
                message:
                  type: string
                  description: "Commit message for the move"
                force:
                  type: boolean
                  description: "Force move even if the DAG has conflicts"
              required:
                - newItemId
      responses:
        "200":
          description: "DAG moved successfully"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessResponse"
        "400":
          description: "DAG cannot be moved"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Conflict detected"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SyncConflictResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/delete-missing:
    post:
      summary: "Delete all missing DAGs"
      description: "Removes all missing DAGs from the remote repository, local disk, and sync state"
      operationId: "syncDeleteMissing"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                message:
                  type: string
                  description: "Commit message for the deletion"
      responses:
        "200":
          description: "Missing DAGs deleted successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: array
                    items:
                      type: string
                    description: "List of deleted DAG IDs"
                  message:
                    type: string
                    description: "Summary message"
                required:
                  - deleted
                  - message
        "400":
          description: "Cannot delete"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/delete-batch:
    post:
      summary: "Delete selected DAGs"
      description: "Removes the specified DAGs from the remote repository, local disk, and sync state in a single commit."
      operationId: "syncDeleteBatch"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SyncDeleteBatchRequest"
      responses:
        "200":
          description: "DAGs deleted successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: array
                    items:
                      type: string
                    description: "List of deleted DAG IDs"
                  message:
                    type: string
                    description: "Summary message"
                required:
                  - deleted
                  - message
        "400":
          description: "Cannot delete (push disabled, untracked DAGs, validation error)"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "DAG not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /sync/cleanup:
    post:
      summary: "Cleanup missing DAGs"
      description: "Removes all missing entries from sync state"
      operationId: "syncCleanup"
      tags:
        - "sync"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Cleanup completed successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  forgotten:
                    type: array
                    items:
                      type: string
                    description: "List of forgotten DAG IDs"
                  message:
                    type: string
                    description: "Summary message"
                required:
                  - forgotten
                  - message
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /settings/base-config:
    get:
      summary: "Get base configuration"
      description: "Returns the base DAG configuration YAML. Requires developer role or above."
      operationId: "getBaseConfig"
      tags:
        - "settings"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Base configuration"
          content:
            application/json:
              schema:
                type: object
                properties:
                  spec:
                    type: string
                    description: "The base configuration in YAML format"
                  errors:
                    type: array
                    items:
                      type: string
                    description: "List of validation errors in the configuration"
                required:
                  - spec
                  - errors
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Requires developer role or above"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update base configuration"
      description: "Updates the base DAG configuration YAML. Validates before saving. Requires developer role or above."
      operationId: "updateBaseConfig"
      tags:
        - "settings"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spec:
                  type: string
                  description: "The base configuration in YAML format"
              required:
                - spec
      responses:
        "200":
          description: "Base configuration updated successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
                    description: "List of validation warnings"
                required:
                  - errors
        "400":
          description: "Invalid configuration"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Requires developer role or above"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /settings/workspaces/{workspaceName}/base-config:
    get:
      summary: "Get workspace base configuration"
      description: "Returns the workspace-scoped base DAG configuration YAML. Requires access to the workspace."
      operationId: "getWorkspaceBaseConfig"
      tags:
        - "settings"
      parameters:
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Workspace base configuration"
          content:
            application/json:
              schema:
                type: object
                properties:
                  spec:
                    type: string
                    description: "The workspace base configuration in YAML format"
                  errors:
                    type: array
                    items:
                      type: string
                    description: "List of validation errors in the configuration"
                required:
                  - spec
                  - errors
        "400":
          description: "Invalid workspace"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

    put:
      summary: "Update workspace base configuration"
      description: "Updates the workspace-scoped base DAG configuration YAML. Validates before saving. Requires write access to the workspace."
      operationId: "updateWorkspaceBaseConfig"
      tags:
        - "settings"
      parameters:
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                spec:
                  type: string
                  description: "The workspace base configuration in YAML format"
              required:
                - spec
      responses:
        "200":
          description: "Workspace base configuration updated successfully"
          content:
            application/json:
              schema:
                type: object
                properties:
                  errors:
                    type: array
                    items:
                      type: string
                    description: "List of validation warnings"
                required:
                  - errors
        "400":
          description: "Invalid configuration"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /license/status:
    get:
      summary: "Get license status"
      description: "Returns the current public license status without exposing license credentials."
      operationId: "getLicenseStatus"
      tags:
        - "system"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Current license status"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseStatusResponse"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /license/activate:
    post:
      summary: "Activate a license key"
      description: "Exchanges a license key for a signed JWT token. Admin only."
      operationId: "activateLicense"
      tags:
        - "system"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - key
              properties:
                key:
                  type: string
                  description: "License key (e.g. DAGU-XXXX-XXXX-XXXX-XXXX)"
      responses:
        "200":
          description: "Activation successful"
          content:
            application/json:
              schema:
                type: object
                properties:
                  plan:
                    type: string
                  features:
                    type: array
                    items:
                      type: string
                  expiry:
                    type: string
        "400":
          description: "Invalid key or activation failed"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /license/deactivate:
    post:
      summary: "Deactivate the current license"
      description: "Removes local activation data and returns to community mode. Admin only."
      operationId: "deactivateLicense"
      tags:
        - "system"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "License deactivated"
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
        "400":
          description: "No active license or license configured via env var"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Insufficient permissions"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Unexpected error"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /remote-nodes:
    get:
      summary: "List all remote nodes"
      description: "Returns remote nodes from both config file and store"
      operationId: "listRemoteNodes"
      tags:
        - "remote-nodes"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "List of remote nodes"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoteNodeListResponse"
        "403":
          description: "Forbidden"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: "Create a new remote node"
      description: "Creates a store-managed remote node"
      operationId: "createRemoteNode"
      tags:
        - "remote-nodes"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRemoteNodeRequest"
      responses:
        "201":
          description: "Remote node created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoteNodeResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Name already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /remote-nodes/{remoteNodeId}:
    get:
      summary: "Get a remote node"
      description: "Returns a single remote node by ID"
      operationId: "getRemoteNode"
      tags:
        - "remote-nodes"
      parameters:
        - $ref: "#/components/parameters/RemoteNodeId"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Remote node details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoteNodeResponse"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: "Update a remote node"
      description: "Updates a store-managed remote node"
      operationId: "updateRemoteNode"
      tags:
        - "remote-nodes"
      parameters:
        - $ref: "#/components/parameters/RemoteNodeId"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRemoteNodeRequest"
      responses:
        "200":
          description: "Remote node updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemoteNodeResponse"
        "403":
          description: "Cannot modify config-sourced node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Name already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: "Delete a remote node"
      description: "Deletes a store-managed remote node"
      operationId: "deleteRemoteNode"
      tags:
        - "remote-nodes"
      parameters:
        - $ref: "#/components/parameters/RemoteNodeId"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "204":
          description: "Remote node deleted"
        "403":
          description: "Cannot delete config-sourced node"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /remote-nodes/{remoteNodeId}/test-connection:
    post:
      summary: "Test remote node connection"
      description: "Tests connectivity to a remote node by making a health check request"
      operationId: "testRemoteNodeConnection"
      tags:
        - "remote-nodes"
      parameters:
        - $ref: "#/components/parameters/RemoteNodeId"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Connection test result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TestRemoteNodeConnectionResponse"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles:
    get:
      summary: "List runtime profiles"
      description: "Lists runtime profile metadata and entries. Secret values are never returned."
      operationId: "listRuntimeProfiles"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Runtime profiles"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeProfileListResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: "Create runtime profile"
      description: "Creates a runtime profile for managed environment variables and secrets."
      operationId: "createRuntimeProfile"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRuntimeProfileRequest"
      responses:
        "201":
          description: "Runtime profile created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Runtime profile already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/_global:
    get:
      summary: "Get global runtime profile defaults"
      description: "Returns the global inherited runtime profile layer. Secret values are never returned."
      operationId: "getGlobalRuntimeProfileDefaults"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Global runtime profile defaults"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InheritedRuntimeProfileResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: "Update global runtime profile defaults"
      operationId: "updateGlobalRuntimeProfileDefaults"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateInheritedRuntimeProfileRequest"
      responses:
        "200":
          description: "Global runtime profile defaults updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InheritedRuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/_global/variables/{key}:
    put:
      summary: "Set global runtime profile default variable"
      description: "Creates or updates a non-secret environment variable in the global inherited runtime profile layer."
      operationId: "setGlobalRuntimeProfileDefaultVariable"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetRuntimeProfileVariableRequest"
      responses:
        "200":
          description: "Global runtime profile default variable set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InheritedRuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/_global/secrets/{key}:
    put:
      summary: "Set global runtime profile default secret"
      description: "Creates or rotates a Dagu-managed secret value in the global inherited runtime profile layer. Plaintext values are write-only."
      operationId: "setGlobalRuntimeProfileDefaultSecret"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetRuntimeProfileSecretRequest"
      responses:
        "200":
          description: "Global runtime profile default secret set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InheritedRuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/_global/entries/{key}:
    delete:
      summary: "Delete global runtime profile default entry"
      operationId: "deleteGlobalRuntimeProfileDefaultEntry"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "204":
          description: "Global runtime profile default entry deleted"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Runtime profile default entry not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/_workspaces/{workspaceName}:
    get:
      summary: "Get workspace runtime profile defaults"
      description: "Returns the workspace inherited runtime profile layer. Secret values are never returned."
      operationId: "getWorkspaceRuntimeProfileDefaults"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Workspace runtime profile defaults"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InheritedRuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: "Update workspace runtime profile defaults"
      operationId: "updateWorkspaceRuntimeProfileDefaults"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateInheritedRuntimeProfileRequest"
      responses:
        "200":
          description: "Workspace runtime profile defaults updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InheritedRuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/_workspaces/{workspaceName}/variables/{key}:
    put:
      summary: "Set workspace runtime profile default variable"
      description: "Creates or updates a non-secret environment variable in the workspace inherited runtime profile layer."
      operationId: "setWorkspaceRuntimeProfileDefaultVariable"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetRuntimeProfileVariableRequest"
      responses:
        "200":
          description: "Workspace runtime profile default variable set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InheritedRuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/_workspaces/{workspaceName}/secrets/{key}:
    put:
      summary: "Set workspace runtime profile default secret"
      description: "Creates or rotates a Dagu-managed secret value in the workspace inherited runtime profile layer. Plaintext values are write-only."
      operationId: "setWorkspaceRuntimeProfileDefaultSecret"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetRuntimeProfileSecretRequest"
      responses:
        "200":
          description: "Workspace runtime profile default secret set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InheritedRuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/_workspaces/{workspaceName}/entries/{key}:
    delete:
      summary: "Delete workspace runtime profile default entry"
      operationId: "deleteWorkspaceRuntimeProfileDefaultEntry"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: workspaceName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/WorkspaceName"
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "204":
          description: "Workspace runtime profile default entry deleted"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Workspace or runtime profile default entry not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/{profileName}:
    get:
      summary: "Get runtime profile"
      operationId: "getRuntimeProfile"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: profileName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileName"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Runtime profile"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeProfileResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Runtime profile not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: "Update runtime profile metadata"
      operationId: "updateRuntimeProfile"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: profileName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileName"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateRuntimeProfileRequest"
      responses:
        "200":
          description: "Runtime profile updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Runtime profile not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: "Delete runtime profile"
      operationId: "deleteRuntimeProfile"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: profileName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileName"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "204":
          description: "Runtime profile deleted"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Runtime profile not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/{profileName}/variables/{key}:
    put:
      summary: "Set runtime profile variable"
      description: "Creates or updates a non-secret environment variable in a runtime profile."
      operationId: "setRuntimeProfileVariable"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: profileName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileName"
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetRuntimeProfileVariableRequest"
      responses:
        "200":
          description: "Runtime profile variable set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Runtime profile not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/{profileName}/secrets/{key}:
    put:
      summary: "Set runtime profile secret"
      description: "Creates or rotates a Dagu-managed secret value and maps it to a runtime profile key. Plaintext values are write-only."
      operationId: "setRuntimeProfileSecret"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: profileName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileName"
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SetRuntimeProfileSecretRequest"
      responses:
        "200":
          description: "Runtime profile secret set"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RuntimeProfileResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Runtime profile not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /profiles/{profileName}/entries/{key}:
    delete:
      summary: "Delete runtime profile entry"
      operationId: "deleteRuntimeProfileEntry"
      tags:
        - "profiles"
      security:
        - apiToken: []
        - basicAuth: []
      parameters:
        - name: profileName
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileName"
        - name: key
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/RuntimeProfileKey"
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "204":
          description: "Runtime profile entry deleted"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Runtime profile or entry not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /views:
    get:
      summary: "List saved views"
      description: "Lists all saved Overview view configurations, ordered by creation time."
      operationId: "listViews"
      tags:
        - "views"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "List of views"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ViewListResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: "Create a view"
      description: "Creates a saved Overview view configuration. Views are global and shared across users."
      operationId: "createView"
      tags:
        - "views"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ViewSpec"
      responses:
        "201":
          description: "View created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/View"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /views/{viewId}:
    get:
      summary: "Get a view"
      operationId: "getView"
      tags:
        - "views"
      parameters:
        - name: viewId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "View"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/View"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    put:
      summary: "Update a view"
      operationId: "updateView"
      tags:
        - "views"
      parameters:
        - name: viewId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ViewSpec"
      responses:
        "200":
          description: "View updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/View"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: "Delete a view"
      operationId: "deleteView"
      tags:
        - "views"
      parameters:
        - name: viewId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "204":
          description: "View deleted"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /secrets:
    get:
      summary: "List secrets"
      description: "Lists secret registry metadata. Plaintext values are never returned."
      operationId: "listSecrets"
      tags:
        - "secrets"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
        - name: workspace
          in: query
          description: "Single secret scope. Use global for workspace-less secrets or a workspace name. Omit for global. all and default are not supported for secrets."
          required: false
          schema:
            type: string
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            default: 0
      responses:
        "200":
          description: "List of secrets"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SecretListResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: "Create a secret"
      description: "Creates Dagu-managed secret metadata in global scope or a named workspace and optionally writes an initial value. Plaintext values are write-only."
      operationId: "createSecret"
      tags:
        - "secrets"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateSecretRequest"
      responses:
        "201":
          description: "Secret created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SecretResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Secret already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /secrets/{secretId}:
    get:
      summary: "Get secret"
      operationId: "getSecret"
      tags:
        - "secrets"
      parameters:
        - name: secretId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Secret metadata"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SecretResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: "Update secret metadata"
      operationId: "updateSecret"
      tags:
        - "secrets"
      parameters:
        - name: secretId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateSecretRequest"
      responses:
        "200":
          description: "Secret updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SecretResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: "Delete secret"
      operationId: "deleteSecret"
      tags:
        - "secrets"
      parameters:
        - name: secretId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "204":
          description: "Secret deleted"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /secrets/{secretId}/versions:
    post:
      summary: "Write a new secret value version"
      description: "Writes a new Dagu-managed value version. The value is write-only and is not returned."
      operationId: "writeSecretVersion"
      tags:
        - "secrets"
      parameters:
        - name: secretId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WriteSecretVersionRequest"
      responses:
        "200":
          description: "Secret value written"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SecretResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /secrets/{secretId}/disable:
    post:
      summary: "Disable secret"
      operationId: "disableSecret"
      tags:
        - "secrets"
      parameters:
        - name: secretId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Secret disabled"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SecretResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /secrets/{secretId}/enable:
    post:
      summary: "Enable secret"
      operationId: "enableSecret"
      tags:
        - "secrets"
      parameters:
        - name: secretId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Secret enabled"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SecretResponse"
        "401":
          description: "Not authenticated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: "Not authorized"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /workspaces:
    get:
      summary: "List all workspaces"
      operationId: "listWorkspaces"
      tags:
        - "workspaces"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "List of workspaces"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceListResponse"
        default:
          description: "Generic error response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: "Create a workspace"
      operationId: "createWorkspace"
      tags:
        - "workspaces"
      parameters:
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateWorkspaceRequest"
      responses:
        "201":
          description: "Workspace created"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceResponse"
        "400":
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Name already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /workspaces/{workspaceId}:
    get:
      summary: "Get workspace by ID"
      operationId: "getWorkspace"
      tags:
        - "workspaces"
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "200":
          description: "Workspace details"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceResponse"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    patch:
      summary: "Update a workspace"
      operationId: "updateWorkspace"
      tags:
        - "workspaces"
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateWorkspaceRequest"
      responses:
        "200":
          description: "Workspace updated"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WorkspaceResponse"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: "Name already exists"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    delete:
      summary: "Delete a workspace"
      operationId: "deleteWorkspace"
      tags:
        - "workspaces"
      parameters:
        - name: workspaceId
          in: path
          required: true
          schema:
            type: string
        - $ref: "#/components/parameters/RemoteNode"
      responses:
        "204":
          description: "Workspace deleted"
        "404":
          description: "Not found"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    apiToken:
      type: http
      scheme: bearer
      bearerFormat: opaque

  parameters:
    Page:
      name: page
      in: query
      description: page number of items to fetch (default is 1)
      required: false
      schema:
        type: integer
        minimum: 1
        default: 1

    UserId:
      name: userId
      in: path
      description: unique identifier of the user
      required: true
      schema:
        type: string
        minLength: 1

    APIKeyId:
      name: keyId
      in: path
      description: unique identifier of the API key
      required: true
      schema:
        type: string
        minLength: 1

    PerPage:
      name: perPage
      in: query
      description: number of items per page (default is 30, max is 100)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 50

    Workspace:
      name: workspace
      in: query
      description: "Workspace selector. For list and search APIs, use all, default, or a workspace name. Omitted means all."
      required: false
      schema:
        type: string
        minLength: 1
        maxLength: 64
        pattern: "^[A-Za-z0-9_-]+$"

    SearchCursor:
      name: cursor
      in: query
      description: "Opaque cursor returned by the previous search response"
      required: false
      schema:
        type: string

    SearchLimit:
      name: limit
      in: query
      description: "Number of search results to return (default 20, max 50)"
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20

    SearchMatchLimit:
      name: limit
      in: query
      description: "Number of search match snippets to return (default 5, max 50)"
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 5

    DAGFileName:
      name: fileName
      in: path
      description: the name of the DAG file
      required: true
      schema:
        $ref: "#/components/schemas/DAGFileName"

    DAGName:
      name: name
      in: path
      description: name of the DAG
      required: true
      schema:
        $ref: "#/components/schemas/DAGName"

    StepName:
      name: stepName
      in: path
      description: name of the step
      required: true
      schema:
        type: string

    HumanTaskStepId:
      name: stepId
      in: path
      description: explicit ID of the human-task step
      required: true
      schema:
        type: string
        pattern: "^[A-Za-z][A-Za-z0-9_]*$"
        maxLength: 40

    ArtifactPath:
      name: path
      in: query
      description: "Relative artifact file path within the DAG-run artifact directory. Must not start with '/' or '\\' or contain '..'."
      required: true
      schema:
        allOf:
          - type: string
            minLength: 1
            pattern: "^[^/\\\\].*$"
          - not:
              pattern: "\\\\"
          - not:
              pattern: "(^|[\\\\/])\\.\\.([\\\\/]|$)"
          - not:
              pattern: "^[A-Za-z]:"

    ArtifactRecursive:
      name: recursive
      in: query
      description: "Whether to recursively expand nested artifact directories"
      required: false
      schema:
        type: boolean
        default: false

    RemoteNode:
      name: remoteNode
      in: query
      description: name of the remote node
      required: false
      schema:
        type: string
        default: "local"

    LogStartTime:
      name: startTime
      in: query
      description: "Filter entries after this time (ISO 8601 format)"
      required: false
      schema:
        type: string
        format: date-time

    LogEndTime:
      name: endTime
      in: query
      description: "Filter entries before this time (ISO 8601 format)"
      required: false
      schema:
        type: string
        format: date-time

    AuditLogLimit:
      name: limit
      in: query
      description: "Maximum number of entries to return (default 100)"
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 1000

    EventLogLimit:
      name: limit
      in: query
      description: "Maximum number of entries to return (default 50)"
      required: false
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 500

    EventLogCursor:
      name: cursor
      in: query
      description: "Opaque cursor for loading older event log entries"
      required: false
      schema:
        type: string

    DAGRunListLimit:
      name: limit
      in: query
      description: "Maximum number of DAG-runs to return (default 100)"
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 500

    DAGRunListCursor:
      name: cursor
      in: query
      description: "Opaque cursor for loading the next page of older DAG-runs"
      required: false
      schema:
        type: string

    QueueListLimit:
      name: limit
      in: query
      description: "Maximum number of queued DAG-runs to return (default 100)"
      required: false
      schema:
        type: integer
        default: 100
        minimum: 1
        maximum: 500

    QueueListCursor:
      name: cursor
      in: query
      description: "Opaque cursor for loading the next page of queued DAG-runs"
      required: false
      schema:
        type: string

    EventLogPaginationMode:
      name: paginationMode
      in: query
      description: "Pagination mode. Use `cursor` for the event feed infinite-loading flow; omit or use `offset` for compatibility pagination."
      required: false
      schema:
        type: string
        enum:
          - offset
          - cursor
        default: offset

    LogOffset:
      name: offset
      in: query
      description: "Number of entries to skip (for pagination)"
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0

    DAGRunId:
      name: dagRunId
      in: path
      description: ID of the DAG-run or 'latest' to get the most recent DAG-run
      required: true
      schema:
        $ref: "#/components/schemas/DAGRunId"

    DAGRunConcreteId:
      name: dagRunId
      in: path
      description: ID of the DAG-run; must not be the special 'latest' alias
      required: true
      schema:
        allOf:
          - type: string
            description: "Unique identifier for the DAG-run."
            example: "20240101_120000"
            pattern: "^[a-zA-Z0-9_-]+$"
          - not:
              enum:
                - latest

    DAGRunIdSearch:
      name: dagRunId
      in: query
      description: ID of the DAG-run or 'latest' to get the most recent DAG-run
      required: false
      schema:
        $ref: "#/components/schemas/DAGRunId"

    DAGRunName:
      name: name
      in: path
      description: name of the DAG-run
      required: true
      schema:
        type: string

    StatusList:
      name: status
      in: query
      description: status of the DAG-run. Repeat the parameter to match multiple statuses.
      required: false
      explode: true
      schema:
        type: array
        items:
          $ref: "#/components/schemas/Status"

    DateTimeFrom:
      name: fromDate
      in: query
      description: start datetime for filtering DAG-runs in ISO 8601 format with timezone
      required: false
      schema:
        $ref: "#/components/schemas/UnixTimestamp"

    DateTimeTo:
      name: toDate
      in: query
      description: end datetime for filtering DAG-runs in ISO 8601 format with timezone
      required: false
      schema:
        $ref: "#/components/schemas/UnixTimestamp"

    Tail:
      name: tail
      in: query
      description: Number of lines to return from the end of the file
      required: false
      schema:
        type: integer
        minimum: 1

    Head:
      name: head
      in: query
      description: Number of lines to return from the beginning of the file
      required: false
      schema:
        type: integer
        minimum: 1

    Offset:
      name: offset
      in: query
      description: Line number to start reading from (1-based)
      required: false
      schema:
        type: integer
        minimum: 1

    Limit:
      name: limit
      in: query
      description: Maximum number of lines to return
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 10000

    Stream:
      name: stream
      in: query
      description: "Whether to return stdout or stderr logs"
      required: false
      schema:
        $ref: "#/components/schemas/Stream"

    RemoteNodeId:
      name: remoteNodeId
      in: path
      required: true
      description: "The unique identifier of the remote node"
      schema:
        type: string

  schemas:
    Tags:
      type: array
      items:
        type: string
      deprecated: true
      description: "Deprecated alias for Labels. Additional labels to apply to the DAG-run (format: key=value or key-only). Merged with labels defined in the DAG spec. Mutually exclusive with `labels`; the server returns HTTP 400 if both are set."

    Labels:
      type: array
      items:
        type: string
      description: "Additional labels to apply to the DAG-run (format: key=value or key-only). Merged with labels defined in the DAG spec. Mutually exclusive with deprecated `tags`; the server returns HTTP 400 if both are set."

    AuditEntry:
      type: object
      description: "A single audit log entry"
      properties:
        id:
          type: string
          description: "Unique identifier for this entry"
        timestamp:
          type: string
          format: date-time
          description: "When the event occurred"
        category:
          type: string
          description: "Category of the audit event (e.g., terminal, user, dag)"
        action:
          type: string
          description: "The action that was performed (e.g., session_start, command, login)"
        source:
          type: string
          description: "Source surface that produced the event"
        surface:
          type: string
          description: "Externally accepted credential surface"
        result:
          type: string
          description: "Event result such as succeeded, failed, or denied"
        correlationId:
          type: string
          description: "Correlation ID linking related audit events"
        resourceType:
          type: string
          description: "Affected resource type"
        resourceId:
          type: string
          description: "Affected resource ID"
        workspace:
          type: string
          description: "Canonical workspace for filtering"
        credentialId:
          type: string
          description: "Credential ID used for the request"
        credentialType:
          type: string
          description: "Credential type used for the request"
        mcpTool:
          type: string
          description: "MCP tool name when source is MCP"
        userId:
          type: string
          description: "ID of the user who performed the action"
        username:
          type: string
          description: "Username of the user who performed the action"
        details:
          type: string
          description: "JSON-encoded action-specific details"
        ipAddress:
          type: string
          description: "Client IP address if available"
      required:
        - id
        - timestamp
        - category
        - action
        - userId
        - username

    AuditLogsResponse:
      type: object
      description: "Response containing audit log entries"
      properties:
        entries:
          type: array
          items:
            $ref: "#/components/schemas/AuditEntry"
          description: "List of audit log entries"
        total:
          type: integer
          description: "Total number of entries matching the filter (before pagination)"
      required:
        - entries
        - total

    EventLogEntry:
      type: object
      description: "A single centralized operational event log entry"
      properties:
        id:
          type: string
          description: "Unique identifier for this event"
        schemaVersion:
          type: integer
          description: "Schema version of the event envelope"
        occurredAt:
          type: string
          format: date-time
          description: "When the event occurred"
        recordedAt:
          type: string
          format: date-time
          description: "When the event was recorded by the producer"
        kind:
          type: string
          description: "High-level event kind (e.g., dag_run, llm_usage)"
        type:
          type: string
          description: "Specific event type (e.g., dag.run.failed)"
        sourceService:
          type: string
          description: "Service that produced the event"
        sourceInstance:
          type: string
          description: "Specific producer instance identifier"
        dagName:
          type: string
          description: "DAG name for DAG-run events"
        dagRunId:
          type: string
          description: "DAG run ID for DAG-run events"
        attemptId:
          type: string
          description: "Attempt ID for DAG-run events"
        sessionId:
          type: string
          description: "Session ID for LLM usage events"
        userId:
          type: string
          description: "User ID associated with the event"
        model:
          type: string
          description: "Model name associated with the event"
        status:
          type: string
          description: "Status associated with the event when applicable"
        data:
          type: object
          additionalProperties: true
          description: "Small event-specific payload"
      required:
        - id
        - schemaVersion
        - occurredAt
        - recordedAt
        - kind
        - type
        - sourceService

    EventLogsResponse:
      type: object
      description: "Response containing centralized event log entries"
      properties:
        entries:
          type: array
          items:
            $ref: "#/components/schemas/EventLogEntry"
          description: "List of event log entries"
        total:
          type: integer
          description: "Total number of entries matching the filter when using compatibility offset pagination"
        nextCursor:
          type: string
          description: "Opaque cursor for loading the next page of older entries when using cursor pagination"
      required:
        - entries

    DAGRunsPageResponse:
      type: object
      description: "Forward-only paginated DAG-run list response"
      properties:
        dagRuns:
          type: array
          description: "List of DAG-runs with their status and metadata"
          items:
            $ref: "#/components/schemas/DAGRunSummary"
        nextCursor:
          type: string
          description: "Opaque cursor for loading the next page of older DAG-runs"
      required:
        - dagRuns

    ApproveStepRequest:
      type: object
      description: "Request body for approving a waiting step"
      properties:
        inputs:
          type: object
          additionalProperties:
            type: string
          description: "Key-value parameters to provide. These will be available as environment variables in subsequent steps."

    ApproveStepResponse:
      type: object
      description: "Response after approving a waiting step"
      properties:
        dagRunId:
          type: string
          description: "The DAG run ID"
        stepName:
          type: string
          description: "The approved step name"
        resumed:
          type: boolean
          description: "Whether the DAG run was re-enqueued for execution"
      required:
        - dagRunId
        - stepName
        - resumed

    ChatMessage:
      type: object
      description: "A single chat message in an LLM session"
      properties:
        role:
          type: string
          enum: [system, user, assistant, tool]
          description: "Message role in the session"
        content:
          type: string
          description: "Message content"
        toolCalls:
          type: array
          items:
            $ref: "#/components/schemas/ChatToolCall"
          description: "Tool calls made by the assistant (only for assistant messages)"
        metadata:
          $ref: "#/components/schemas/ChatMessageMetadata"
      required:
        - role
        - content

    ChatToolCall:
      type: object
      description: "A tool call requested by the LLM"
      properties:
        id:
          type: string
          description: "Unique identifier for this tool call"
        name:
          type: string
          description: "Name of the tool being called"
        arguments:
          type: string
          description: "JSON string of tool arguments"
      required:
        - id
        - name

    ChatMessageMetadata:
      type: object
      description: "Metadata about an LLM API call"
      properties:
        provider:
          type: string
          description: "LLM provider (openai, anthropic, gemini, etc.)"
        model:
          type: string
          description: "Model identifier used"
        promptTokens:
          type: integer
          minimum: 0
          description: "Number of tokens in the prompt"
        completionTokens:
          type: integer
          minimum: 0
          description: "Number of tokens in the completion"
        totalTokens:
          type: integer
          minimum: 0
          description: "Total tokens (prompt + completion)"

    ChatMessagesResponse:
      type: object
      description: "Response containing chat messages for a step"
      properties:
        messages:
          type: array
          items:
            $ref: "#/components/schemas/ChatMessage"
          description: "List of chat messages"
        toolDefinitions:
          type: array
          items:
            $ref: "#/components/schemas/ToolDefinition"
          description: "Tool definitions that were available to the LLM"
        stepStatus:
          $ref: "#/components/schemas/NodeStatus"
        stepStatusLabel:
          $ref: "#/components/schemas/NodeStatusLabel"
        hasMore:
          type: boolean
          description: "True if step is still running and more messages may arrive"
      required:
        - messages
        - stepStatus
        - stepStatusLabel
        - hasMore

    ToolDefinition:
      type: object
      description: "A tool definition that was available to the LLM"
      properties:
        name:
          type: string
          description: "Name of the tool"
        description:
          type: string
          description: "Description of what the tool does"
        parameters:
          type: object
          additionalProperties: true
          description: "JSON Schema describing the tool's parameters"
      required:
        - name

    RejectStepRequest:
      type: object
      description: "Request body for rejecting a waiting step"
      properties:
        reason:
          type: string
          description: "Optional reason for rejecting the step"

    RejectStepResponse:
      type: object
      description: "Response after rejecting a waiting step"
      properties:
        dagRunId:
          type: string
          description: "The DAG run ID"
        stepName:
          type: string
          description: "The rejected step name"
      required:
        - dagRunId
        - stepName

    PushBackStepRequest:
      type: object
      description: "Request body for pushing back a waiting step for re-execution with feedback"
      properties:
        inputs:
          type: object
          additionalProperties:
            type: string
          description: "Key-value parameters to provide as feedback. These will be injected as environment variables when the step re-executes."

    PushBackStepResponse:
      type: object
      description: "Response after pushing back a waiting step"
      properties:
        dagRunId:
          type: string
          description: "The DAG run ID"
        stepName:
          type: string
          description: "The pushed-back step name"
        approvalIteration:
          type: integer
          description: "The current approval iteration count after push-back"
        resumed:
          type: boolean
          description: "Whether the DAG run was re-enqueued for execution"
        subDAGRunId:
          type: string
          description: "The sub-DAG run ID, present only for sub-DAG push-back operations"
      required:
        - dagRunId
        - stepName
        - approvalIteration
        - resumed

    ApprovalConfig:
      type: object
      description: "Configuration for a human approval gate on a step"
      properties:
        prompt:
          type: string
          description: "Message displayed to the approver"
        input:
          type: array
          items:
            type: string
          description: "List of expected input field names from the approver"
        required:
          type: array
          items:
            type: string
          description: "Subset of input fields that must be provided"
        rewindTo:
          type: string
          description: "Optional step name to restart from when the approver pushes the step back. Must reference the step itself or an upstream dependency."

    HumanTaskConfig:
      type: object
      description: "Resolved human-task instructions and optional normalized input form"
      properties:
        prompt:
          type: string
          description: "Instructions displayed to the operator. Run details contain the resolved, secret-masked snapshot."
        form:
          type: object
          additionalProperties: true
          description: "Normalized flat JSON Schema for typed completion input"
      required:
        - prompt

    HumanTaskInput:
      description: "Typed human-task completion input. An empty object acknowledges a task without a form."
      type: object
      additionalProperties: true

    HumanTaskCompletionResponse:
      type: object
      description: "Result of completing or confirming one human task"
      properties:
        dagName:
          $ref: "#/components/schemas/DAGName"
        dagRunId:
          $ref: "#/components/schemas/DAGRunId"
        stepId:
          type: string
        alreadyCompleted:
          type: boolean
        queued:
          type: boolean
          description: "Whether this request durably queued the DAG-run retry"
        remainingWaitingSteps:
          type: integer
          minimum: 0
      required:
        - dagName
        - dagRunId
        - stepId
        - alreadyCompleted
        - queued
        - remainingWaitingSteps

    HumanTaskResumeResponse:
      type: object
      description: "Result of queueing a completed human-task retry"
      properties:
        dagName:
          $ref: "#/components/schemas/DAGName"
        dagRunId:
          $ref: "#/components/schemas/DAGRunId"
        queued:
          type: boolean
          description: "Whether this request durably queued the DAG-run retry"
      required:
        - dagName
        - dagRunId
        - queued

    Error:
      type: object
      description: "Generic error response object"
      properties:
        code:
          $ref: "#/components/schemas/ErrorCode"
        message:
          type: string
          description: "Short error message"
        details:
          type: object
          description: "Additional error details"
      required:
        - code
        - message

    TimeoutError:
      type: object
      description: "Timeout error response with DAG run tracking information"
      allOf:
        - $ref: "#/components/schemas/Error"
        - type: object
          properties:
            dagRunId:
              allOf:
                - $ref: "#/components/schemas/DAGRunId"
                - description: "ID of the DAG run that continues executing in background"
          required:
            - dagRunId

    ErrorCode:
      type: string
      description: "Error code indicating the type of error"
      enum:
        - "forbidden"
        - "bad_request"
        - "not_found"
        - "internal_error"
        - "unauthorized"
        - "bad_gateway"
        - "remote_node_error"
        - "max_run_reached"
        - "not_running"
        - "already_exists"
        - "auth.unauthorized"
        - "auth.token_invalid"
        - "auth.forbidden"
        - "timeout"
        - "rate_limited"
        - "conflict"
        - "human_task_resume_failed"
        - "payload_too_large"

    WebhookRequest:
      type: object
      description: "Request body for webhook trigger endpoint"
      properties:
        dagRunId:
          allOf:
            - $ref: "#/components/schemas/DAGRunId"
            - description: |
                Optional idempotency key. If provided and a DAG run with this ID already exists,
                the endpoint returns 409 Conflict. If not provided, a new UUID is generated.
        payload:
          type: object
          additionalProperties: true
          description: "Arbitrary JSON payload to pass to the DAG as WEBHOOK_PAYLOAD"

    WebhookResponse:
      type: object
      description: "Response from webhook trigger endpoint"
      required:
        - dagRunId
        - dagName
      properties:
        dagRunId:
          $ref: "#/components/schemas/DAGRunId"
        dagName:
          type: string
          description: "Name of the triggered DAG"

    WebhookAuthMode:
      type: string
      description: "Authentication mode for a webhook trigger endpoint"
      enum:
        - token_only
        - token_and_hmac
        - hmac_only

    WebhookHMACEnforcementMode:
      type: string
      description: "How HMAC validation is enforced when HMAC is enabled"
      enum:
        - strict
        - observe

    WebhookHMACDetails:
      type: object
      description: "Public webhook HMAC configuration details"
      required:
        - enabled
        - secretConfigured
      properties:
        enabled:
          type: boolean
          description: "Whether HMAC authentication is currently enabled"
        enforcementMode:
          $ref: "#/components/schemas/WebhookHMACEnforcementMode"
        algorithm:
          type: string
          description: "Fixed HMAC algorithm for v1"
        headerName:
          type: string
          description: "Header containing the HMAC signature"
        format:
          type: string
          description: "Expected signature header value format"
        secretConfigured:
          type: boolean
          description: "Whether an HMAC secret is configured for the webhook"
        updatedAt:
          type: string
          format: date-time
          description: "When the HMAC secret was last generated"

    WebhookDetails:
      type: object
      description: "Webhook configuration details (token not included)"
      required:
        - id
        - dagName
        - tokenPrefix
        - enabled
        - authMode
        - hmac
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          format: uuid
          description: "Unique identifier for the webhook"
        dagName:
          type: string
          description: "Name of the DAG this webhook triggers"
        tokenPrefix:
          type: string
          description: "First 8 characters of the token for identification"
        enabled:
          type: boolean
          description: "Whether the webhook is active"
        authMode:
          $ref: "#/components/schemas/WebhookAuthMode"
        hmac:
          $ref: "#/components/schemas/WebhookHMACDetails"
        createdAt:
          type: string
          format: date-time
          description: "When the webhook was created"
        updatedAt:
          type: string
          format: date-time
          description: "When the webhook was last modified"
        createdBy:
          type: string
          description: "User ID who created the webhook"
        lastUsedAt:
          type: string
          format: date-time
          description: "When the webhook was last triggered"

    WebhookCreateResponse:
      type: object
      description: "Response when creating or regenerating a webhook (includes full token)"
      required:
        - webhook
        - token
      properties:
        webhook:
          $ref: "#/components/schemas/WebhookDetails"
        token:
          type: string
          description: "Full webhook token (only shown once, store securely!)"

    WebhookListResponse:
      type: object
      description: "List of all webhooks"
      required:
        - webhooks
      properties:
        webhooks:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDetails"

    WebhookToggleRequest:
      type: object
      description: "Request to toggle webhook enabled state"
      required:
        - enabled
      properties:
        enabled:
          type: boolean
          description: "Whether to enable or disable the webhook"

    WebhookHMACConfigureRequest:
      type: object
      description: |
        Request to configure webhook HMAC auth mode and enforcement.
        If enforcementMode is omitted when enabling HMAC, it defaults to strict.
        If omitted when configuring an existing webhook, the current enforcement
        mode is preserved for token_and_hmac, while hmac_only always uses strict.
        Clients should omit enforcementMode when authMode is hmac_only; the
        server enforces strict mode and rejects observe.
      required:
        - authMode
      properties:
        authMode:
          type: string
          enum:
            - token_and_hmac
            - hmac_only
        enforcementMode:
          $ref: "#/components/schemas/WebhookHMACEnforcementMode"

    WebhookHMACSecretResponse:
      type: object
      description: "Response when enabling or regenerating webhook HMAC (includes full secret)"
      required:
        - webhook
        - hmacSecret
      properties:
        webhook:
          $ref: "#/components/schemas/WebhookDetails"
        hmacSecret:
          type: string
          description: "Full HMAC secret (only shown once, store securely!)"

    NotificationProviderType:
      type: string
      description: "Notification delivery provider"
      enum:
        - email
        - webhook
        - slack
        - telegram

    NotificationEventType:
      type: string
      description: "DAG run event that can trigger server-side notifications. Rules configured for dag.run.succeeded also match dag.run.partially_succeeded; rules configured only for dag.run.partially_succeeded do not match clean successes."
      enum:
        - dag.run.waiting
        - dag.run.succeeded
        - dag.run.partially_succeeded
        - dag.run.failed
        - dag.run.aborted
        - dag.run.rejected

    NotificationEmailTarget:
      type: object
      description: "Email notification target. SMTP transport is configured in workspace notification settings."
      required:
        - to
      properties:
        from:
          type: string
          description: "Sender address. Defaults to the workspace SMTP sender."
        to:
          type: array
          items:
            type: string
          description: "Primary recipients"
        cc:
          type: array
          items:
            type: string
          description: "CC recipients"
        bcc:
          type: array
          items:
            type: string
          description: "BCC recipients"
        subjectPrefix:
          type: string
          description: "Subject prefix. Defaults to [DAGU]."
        subjectTemplate:
          type: string
          description: "Optional email subject template. When set, it replaces the generated subject."
        bodyTemplate:
          type: string
          description: "Optional email body template. When omitted, Dagu sends the default notification body."
        attachLogs:
          type: boolean
          description: "Attach DAG and step logs when available"

    NotificationSMTPSettingsInput:
      type: object
      description: "Workspace SMTP transport input for notification email delivery. Values are encrypted at rest where applicable."
      properties:
        host:
          type: string
          description: "SMTP server host"
        port:
          type: string
          description: "SMTP server port"
        username:
          type: string
          description: "SMTP username"
        password:
          type: string
          description: "SMTP password. Omit on updates to preserve the existing password."
        clearPassword:
          type: boolean
          description: "Clear the stored SMTP password."
        from:
          type: string
          description: "Default sender address for notification email channels"

    NotificationSMTPSettings:
      type: object
      description: "Public workspace SMTP transport settings. The SMTP password is never returned."
      required:
        - passwordConfigured
      properties:
        host:
          type: string
          description: "SMTP server host"
        port:
          type: string
          description: "SMTP server port"
        username:
          type: string
          description: "SMTP username"
        from:
          type: string
          description: "Default sender address for notification email channels"
        passwordConfigured:
          type: boolean
          description: "Whether an SMTP password is configured"

    NotificationWorkspaceSettingsInput:
      type: object
      description: "Workspace-level notification settings input"
      properties:
        smtp:
          nullable: true
          allOf:
            - $ref: "#/components/schemas/NotificationSMTPSettingsInput"

    NotificationWorkspaceSettings:
      type: object
      description: "Workspace-level notification settings"
      properties:
        smtp:
          $ref: "#/components/schemas/NotificationSMTPSettings"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
          description: "User ID that last updated the workspace notification settings"

    NotificationRouteScope:
      type: string
      description: "Notification route scope"
      enum:
        - global
        - workspace

    NotificationRouteInput:
      type: object
      description: "Route from notification events to a notification channel"
      required:
        - channelId
        - enabled
      properties:
        id:
          type: string
          description: "Stable route ID. Omit when adding a route."
        channelId:
          type: string
          description: "Notification channel ID"
        enabled:
          type: boolean
          description: "Whether this route receives notifications"
        events:
          type: array
          items:
            $ref: "#/components/schemas/NotificationEventType"
          description: "Events delivered by this route. Omit only for backward compatibility; new clients should send an explicit event list."

    NotificationRoute:
      type: object
      description: "Route from notification events to a notification channel"
      required:
        - id
        - channelId
        - enabled
      properties:
        id:
          type: string
          description: "Stable route ID"
        channelId:
          type: string
          description: "Notification channel ID"
        enabled:
          type: boolean
          description: "Whether this route receives notifications"
        events:
          type: array
          items:
            $ref: "#/components/schemas/NotificationEventType"
          description: "Events delivered by this route. Empty is treated as operational defaults for backward compatibility."

    NotificationRouteSetInput:
      type: object
      description: "Replacement route set for a global or workspace notification scope"
      required:
        - enabled
        - inheritGlobal
        - routes
      properties:
        enabled:
          type: boolean
          description: "Whether this route set can deliver notifications"
        inheritGlobal:
          type: boolean
          description: "For workspace route sets, true means inherit Global instead of using workspace routes. Ignored for global route sets."
        routes:
          type: array
          items:
            $ref: "#/components/schemas/NotificationRouteInput"

    NotificationRouteSet:
      type: object
      description: "Notification routes for a global or workspace scope"
      required:
        - scope
        - enabled
        - inheritGlobal
        - routes
      properties:
        id:
          type: string
          description: "Stable route set ID, present after the route set is saved"
        scope:
          $ref: "#/components/schemas/NotificationRouteScope"
        workspace:
          type: string
          description: "Workspace name for workspace-scoped route sets"
        enabled:
          type: boolean
          description: "Whether this route set can deliver notifications"
        inheritGlobal:
          type: boolean
          description: "For workspace route sets, true means inherit Global instead of using workspace routes"
        routes:
          type: array
          items:
            $ref: "#/components/schemas/NotificationRoute"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
          description: "User ID that last updated the route set"

    NotificationRouteSetListResponse:
      type: object
      description: "Notification route sets"
      required:
        - routeSets
      properties:
        routeSets:
          type: array
          items:
            $ref: "#/components/schemas/NotificationRouteSet"

    NotificationWebhookTargetInput:
      type: object
      description: "Outbound webhook target input. Values are encrypted at rest."
      properties:
        url:
          type: string
          format: uri
          description: "HTTP or HTTPS endpoint to POST notification payloads to. Omit on updates to preserve the existing URL."
        headers:
          type: object
          additionalProperties:
            type: string
          description: "Additional request headers. Values are encrypted at rest. When provided, this replaces the stored header set."
        clearHeaders:
          type: boolean
          description: "Clear all stored webhook headers."
        hmacSecret:
          type: string
          description: "Optional HMAC secret for X-Dagu-Signature. Omit on updates to preserve the existing secret."
        clearHmacSecret:
          type: boolean
          description: "Clear the stored HMAC secret."
        messageTemplate:
          type: string
          description: "Optional rendered message added to the webhook JSON payload as message."
        allowInsecureHttp:
          type: boolean
          description: "Allow plain HTTP webhook URLs. Disabled by default."
        allowPrivateNetwork:
          type: boolean
          description: "Allow loopback or private network webhook targets. Disabled by default."

    NotificationWebhookTarget:
      type: object
      description: "Public outbound webhook target details"
      required:
        - urlConfigured
        - hmacSecretConfigured
      properties:
        urlConfigured:
          type: boolean
          description: "Whether a webhook URL is configured"
        urlPreview:
          type: string
          description: "Redacted URL preview"
        headers:
          type: object
          additionalProperties:
            type: string
          description: "Header names with redacted values"
        hmacSecretConfigured:
          type: boolean
          description: "Whether an HMAC secret is configured"
        messageTemplate:
          type: string
          description: "Optional rendered message added to the webhook JSON payload as message."
        allowInsecureHttp:
          type: boolean
          description: "Whether this target allows plain HTTP webhook URLs"
        allowPrivateNetwork:
          type: boolean
          description: "Whether this target allows loopback or private network webhook targets"

    NotificationSlackTargetInput:
      type: object
      description: "Slack incoming webhook target input. Values are encrypted at rest."
      properties:
        webhookUrl:
          type: string
          format: uri
          description: "Slack incoming webhook URL. Omit on updates to preserve the existing URL."
        messageTemplate:
          type: string
          description: "Optional Slack message template. When omitted, Dagu sends the default notification text."

    NotificationSlackTarget:
      type: object
      description: "Public Slack target details"
      required:
        - webhookUrlConfigured
      properties:
        webhookUrlConfigured:
          type: boolean
          description: "Whether a Slack incoming webhook URL is configured"
        webhookUrlPreview:
          type: string
          description: "Redacted Slack webhook URL preview"
        messageTemplate:
          type: string
          description: "Optional Slack message template. When omitted, Dagu sends the default notification text."

    NotificationTelegramTargetInput:
      type: object
      description: "Telegram Bot API target input. Bot token is encrypted at rest."
      properties:
        botToken:
          type: string
          description: "Telegram bot token. Omit on updates to preserve the existing token."
        chatId:
          type: string
          description: "Telegram chat ID"
        topicId:
          type: string
          description: "Optional Telegram topic ID (message thread ID) for forum groups"
        messageTemplate:
          type: string
          description: "Optional Telegram message template. When omitted, Dagu sends the default notification text."

    NotificationTelegramTarget:
      type: object
      description: "Public Telegram target details"
      required:
        - botTokenConfigured
      properties:
        botTokenConfigured:
          type: boolean
          description: "Whether a Telegram bot token is configured"
        botTokenPreview:
          type: string
          description: "Redacted Telegram bot token preview"
        chatId:
          type: string
          description: "Telegram chat ID"
        topicId:
          type: string
          description: "Optional Telegram topic ID (message thread ID) for forum groups"
        messageTemplate:
          type: string
          description: "Optional Telegram message template. When omitted, Dagu sends the default notification text."

    NotificationTargetInput:
      type: object
      description: "Notification target input"
      required:
        - type
        - enabled
      properties:
        id:
          type: string
          description: "Stable target ID. Omit when creating a new target."
        name:
          type: string
          description: "Human-readable target name"
        type:
          $ref: "#/components/schemas/NotificationProviderType"
        enabled:
          type: boolean
          description: "Whether this target receives notifications"
        events:
          type: array
          items:
            $ref: "#/components/schemas/NotificationEventType"
          description: "Optional target-level event filter. When omitted or empty, the target inherits DAG-level events."
        email:
          $ref: "#/components/schemas/NotificationEmailTarget"
        webhook:
          $ref: "#/components/schemas/NotificationWebhookTargetInput"
        slack:
          $ref: "#/components/schemas/NotificationSlackTargetInput"
        telegram:
          $ref: "#/components/schemas/NotificationTelegramTargetInput"

    NotificationTarget:
      type: object
      description: "Public notification target details. Secrets are never returned."
      required:
        - id
        - type
        - enabled
      properties:
        id:
          type: string
          description: "Stable target ID"
        name:
          type: string
          description: "Human-readable target name"
        type:
          $ref: "#/components/schemas/NotificationProviderType"
        enabled:
          type: boolean
          description: "Whether this target receives notifications"
        events:
          type: array
          items:
            $ref: "#/components/schemas/NotificationEventType"
          description: "Target-level event filter. Empty means the target inherits DAG-level events."
        email:
          $ref: "#/components/schemas/NotificationEmailTarget"
        webhook:
          $ref: "#/components/schemas/NotificationWebhookTarget"
        slack:
          $ref: "#/components/schemas/NotificationSlackTarget"
        telegram:
          $ref: "#/components/schemas/NotificationTelegramTarget"

    NotificationChannelInput:
      type: object
      description: "Notification channel input"
      required:
        - name
        - type
        - enabled
      properties:
        name:
          type: string
          description: "Human-readable channel name"
        type:
          $ref: "#/components/schemas/NotificationProviderType"
        enabled:
          type: boolean
          description: "Whether this channel can receive notifications"
        email:
          $ref: "#/components/schemas/NotificationEmailTarget"
        webhook:
          $ref: "#/components/schemas/NotificationWebhookTargetInput"
        slack:
          $ref: "#/components/schemas/NotificationSlackTargetInput"
        telegram:
          $ref: "#/components/schemas/NotificationTelegramTargetInput"

    NotificationChannel:
      type: object
      description: "Notification channel. Secrets are never returned."
      required:
        - id
        - name
        - type
        - enabled
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: "Stable channel ID"
        name:
          type: string
          description: "Human-readable channel name"
        type:
          $ref: "#/components/schemas/NotificationProviderType"
        enabled:
          type: boolean
          description: "Whether this channel can receive notifications"
        email:
          $ref: "#/components/schemas/NotificationEmailTarget"
        webhook:
          $ref: "#/components/schemas/NotificationWebhookTarget"
        slack:
          $ref: "#/components/schemas/NotificationSlackTarget"
        telegram:
          $ref: "#/components/schemas/NotificationTelegramTarget"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
          description: "User ID that last updated the channel"

    NotificationChannelListResponse:
      type: object
      description: "Notification channels"
      required:
        - channels
      properties:
        channels:
          type: array
          items:
            $ref: "#/components/schemas/NotificationChannel"

    NotificationSubscriptionInput:
      type: object
      description: "DAG subscription to a notification channel"
      required:
        - channelId
        - enabled
      properties:
        id:
          type: string
          description: "Stable subscription ID. Omit when creating a new subscription."
        channelId:
          type: string
          description: "Notification channel ID"
        enabled:
          type: boolean
          description: "Whether this DAG subscription receives notifications"
        events:
          type: array
          items:
            $ref: "#/components/schemas/NotificationEventType"
          description: "Optional subscription-level event filter. When omitted or empty, the subscription inherits DAG-level events."

    NotificationSubscription:
      type: object
      description: "DAG subscription to a notification channel"
      required:
        - id
        - channelId
        - enabled
      properties:
        id:
          type: string
          description: "Stable subscription ID"
        channelId:
          type: string
          description: "Notification channel ID"
        enabled:
          type: boolean
          description: "Whether this DAG subscription receives notifications"
        events:
          type: array
          items:
            $ref: "#/components/schemas/NotificationEventType"
          description: "Subscription-level event filter. Empty means the subscription inherits DAG-level events."

    DAGSettings:
      type: object
      description: "Server-side DAG settings"
      required:
        - dagName
      properties:
        dagName:
          type: string
          description: "DAG file identifier these settings apply to"
        profile:
          $ref: "#/components/schemas/RuntimeProfileName"
          description: "Default runtime profile used when a DAG run does not provide an explicit profile override"
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
          description: "User ID that last updated the settings"

    UpdateDAGSettingsRequest:
      type: object
      description: "Request to replace DAG settings. Omit `profile` to clear the DAG default profile."
      properties:
        profile:
          $ref: "#/components/schemas/RuntimeProfileName"
          description: "Default runtime profile used when a DAG run does not provide an explicit profile override"

    DAGNotificationSettings:
      type: object
      description: "Server-side DAG notification settings"
      required:
        - id
        - dagName
        - enabled
        - events
        - targets
        - subscriptions
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: "Stable settings ID"
        dagName:
          type: string
          description: "Name of the DAG these settings apply to"
        enabled:
          type: boolean
          description: "Whether notification delivery is enabled for this DAG"
        events:
          type: array
          items:
            $ref: "#/components/schemas/NotificationEventType"
          description: "DAG run events that trigger notifications"
        targets:
          type: array
          items:
            $ref: "#/components/schemas/NotificationTarget"
          description: "DAG-local notification targets kept for backward compatibility"
        subscriptions:
          type: array
          items:
            $ref: "#/components/schemas/NotificationSubscription"
          description: "Notification channels subscribed by this DAG"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
          description: "User ID that last updated the settings"

    UpdateDAGNotificationsRequest:
      type: object
      description: "Request to replace DAG notification settings"
      required:
        - enabled
        - events
        - targets
      properties:
        enabled:
          type: boolean
          description: "Whether notification delivery is enabled for this DAG"
        events:
          type: array
          items:
            $ref: "#/components/schemas/NotificationEventType"
        targets:
          type: array
          items:
            $ref: "#/components/schemas/NotificationTargetInput"
        subscriptions:
          type: array
          items:
            $ref: "#/components/schemas/NotificationSubscriptionInput"

    TestDAGNotificationRequest:
      type: object
      description: "Request to send a test notification"
      properties:
        targetId:
          type: string
          description: "Optional DAG-local target ID, subscription ID, or channel ID. When omitted, every enabled target and subscription is tested."
        eventType:
          $ref: "#/components/schemas/NotificationEventType"

    TestDAGNotificationResult:
      type: object
      description: "Delivery result for one notification target"
      required:
        - targetId
        - targetName
        - provider
        - delivered
      properties:
        targetId:
          type: string
        targetName:
          type: string
        provider:
          $ref: "#/components/schemas/NotificationProviderType"
        delivered:
          type: boolean
        error:
          type: string

    TestDAGNotificationResponse:
      type: object
      description: "Result of test notification delivery"
      required:
        - results
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/TestDAGNotificationResult"

    IncidentProviderType:
      type: string
      description: "Incident provider type"
      enum:
        - pagerduty
        - solarwinds_incident_response

    IncidentSeverity:
      type: string
      description: "Incident severity"
      enum:
        - critical
        - error
        - warning
        - info

    IncidentPolicyScope:
      type: string
      description: "Incident routing scope"
      enum:
        - global
        - workspace
        - dag

    IncidentPagerDutyProviderInput:
      type: object
      description: "PagerDuty Events API v2 provider input. The routing key is encrypted at rest."
      properties:
        routingKey:
          type: string
          description: "PagerDuty Events API v2 routing key. Omit on updates to preserve the existing key."
        clearRoutingKey:
          type: boolean
          description: "Clear the stored routing key."

    IncidentPagerDutyProvider:
      type: object
      description: "Public PagerDuty provider details"
      required:
        - routingKeyConfigured
      properties:
        routingKeyConfigured:
          type: boolean
          description: "Whether a PagerDuty routing key is configured"
        routingKeyPreview:
          type: string
          description: "Redacted routing key preview"

    IncidentSolarWindsProviderInput:
      type: object
      description: "SolarWinds Incident Response incoming webhook provider input. The webhook URL is encrypted at rest."
      properties:
        webhookUrl:
          type: string
          format: uri
          description: "Incoming webhook URL. Omit on updates to preserve the existing URL."
        clearWebhookUrl:
          type: boolean
          description: "Clear the stored webhook URL."
        allowInsecureHttp:
          type: boolean
          description: "Allow plain HTTP webhook URLs. Disabled by default."
        allowPrivateNetwork:
          type: boolean
          description: "Allow loopback or private network webhook targets. Disabled by default."

    IncidentSolarWindsProvider:
      type: object
      description: "Public SolarWinds Incident Response provider details"
      required:
        - webhookUrlConfigured
      properties:
        webhookUrlConfigured:
          type: boolean
          description: "Whether an incoming webhook URL is configured"
        webhookUrlPreview:
          type: string
          description: "Redacted webhook URL preview"
        allowInsecureHttp:
          type: boolean
          description: "Whether this provider allows plain HTTP webhook URLs"
        allowPrivateNetwork:
          type: boolean
          description: "Whether this provider allows loopback or private network webhook targets"

    IncidentPagerDutyProviderInputEnvelope:
      type: object
      description: "PagerDuty incident provider input"
      required:
        - name
        - type
        - enabled
        - pagerDuty
      properties:
        name:
          type: string
          description: "Human-readable provider name"
        type:
          type: string
          enum:
            - pagerduty
        enabled:
          type: boolean
          description: "Whether this provider can receive incident events"
        pagerDuty:
          $ref: "#/components/schemas/IncidentPagerDutyProviderInput"

    IncidentSolarWindsProviderInputEnvelope:
      type: object
      description: "SolarWinds Incident Response provider input"
      required:
        - name
        - type
        - enabled
        - solarWinds
      properties:
        name:
          type: string
          description: "Human-readable provider name"
        type:
          type: string
          enum:
            - solarwinds_incident_response
        enabled:
          type: boolean
          description: "Whether this provider can receive incident events"
        solarWinds:
          $ref: "#/components/schemas/IncidentSolarWindsProviderInput"

    IncidentProviderInput:
      description: "Incident provider input"
      oneOf:
        - $ref: "#/components/schemas/IncidentPagerDutyProviderInputEnvelope"
        - $ref: "#/components/schemas/IncidentSolarWindsProviderInputEnvelope"
      discriminator:
        propertyName: type
        mapping:
          pagerduty: "#/components/schemas/IncidentPagerDutyProviderInputEnvelope"
          solarwinds_incident_response: "#/components/schemas/IncidentSolarWindsProviderInputEnvelope"

    IncidentProvider:
      type: object
      description: "Incident provider. Secrets are never returned."
      required:
        - id
        - name
        - type
        - enabled
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: "Stable provider ID"
        name:
          type: string
          description: "Human-readable provider name"
        type:
          $ref: "#/components/schemas/IncidentProviderType"
        enabled:
          type: boolean
          description: "Whether this provider can receive incident events"
        pagerDuty:
          $ref: "#/components/schemas/IncidentPagerDutyProvider"
        solarWinds:
          $ref: "#/components/schemas/IncidentSolarWindsProvider"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
          description: "User ID that last updated the provider"

    IncidentProviderListResponse:
      type: object
      description: "Incident providers"
      required:
        - providers
      properties:
        providers:
          type: array
          items:
            $ref: "#/components/schemas/IncidentProvider"

    IncidentPolicyInput:
      type: object
      description: "Incident route input. A route opens an incident on final DAG failure and Dagu resolves the saved open incident on later success."
      required:
        - providerId
        - enabled
        - severity
      properties:
        id:
          type: string
          description: "Stable route ID. Omit when adding a route."
        providerId:
          type: string
          description: "Incident provider ID"
        enabled:
          type: boolean
          description: "Whether this route is enabled. Normal incident routing sends true when the route exists."
        severity:
          $ref: "#/components/schemas/IncidentSeverity"
        resolveOnRecovery:
          type: boolean
          description: "Deprecated. Dagu resolves saved open incidents on recovery."
        dedupKeyTemplate:
          type: string
          description: "Deprecated and ignored. Dagu generates stable provider incident keys."
        messageTemplate:
          type: string
          description: "Template for the provider incident summary/message."
        descriptionTemplate:
          type: string
          description: "Template for the provider incident description/details."

    IncidentPolicy:
      type: object
      description: "Incident route"
      required:
        - id
        - providerId
        - enabled
        - severity
        - resolveOnRecovery
        - dedupKeyTemplate
        - messageTemplate
        - descriptionTemplate
      properties:
        id:
          type: string
          description: "Stable route ID"
        providerId:
          type: string
          description: "Incident provider ID"
        enabled:
          type: boolean
          description: "Whether this route is enabled"
        severity:
          $ref: "#/components/schemas/IncidentSeverity"
        resolveOnRecovery:
          type: boolean
          description: "Deprecated. Dagu resolves saved open incidents on recovery."
        dedupKeyTemplate:
          type: string
          description: "Deprecated and ignored. Dagu generates stable provider incident keys."
        messageTemplate:
          type: string
          description: "Template for the provider incident summary/message"
        descriptionTemplate:
          type: string
          description: "Template for the provider incident description/details"

    IncidentPolicySetInput:
      type: object
      description: "Replacement incident routing for a global, workspace, or DAG scope"
      required:
        - enabled
        - inheritParent
        - policies
      properties:
        enabled:
          type: boolean
          description: "Whether this scope can open new incidents"
        inheritParent:
          type: boolean
          description: "For workspace and DAG routing, true means inherit the parent scope instead of using local routes. Ignored for global routing."
        policies:
          type: array
          items:
            $ref: "#/components/schemas/IncidentPolicyInput"

    IncidentPolicySet:
      type: object
      description: "Incident routing for a global, workspace, or DAG scope"
      required:
        - scope
        - enabled
        - inheritParent
        - policies
      properties:
        id:
          type: string
          description: "Stable routing ID, present after routing is saved"
        scope:
          $ref: "#/components/schemas/IncidentPolicyScope"
        workspace:
          type: string
          description: "Workspace name for workspace-scoped routing"
        dagName:
          type: string
          description: "DAG name for DAG-scoped routing"
        enabled:
          type: boolean
          description: "Whether this scope can open new incidents"
        inheritParent:
          type: boolean
          description: "For workspace and DAG routing, true means inherit the parent scope instead of using local routes"
        policies:
          type: array
          items:
            $ref: "#/components/schemas/IncidentPolicy"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        updatedBy:
          type: string
          description: "User ID that last updated routing"

    IncidentPolicySetListResponse:
      type: object
      description: "Incident routing scopes"
      required:
        - policySets
      properties:
        policySets:
          type: array
          items:
            $ref: "#/components/schemas/IncidentPolicySet"

    TestIncidentProviderResult:
      type: object
      description: "Delivery result for one incident provider"
      required:
        - providerId
        - providerName
        - providerType
        - delivered
      properties:
        providerId:
          type: string
        providerName:
          type: string
        providerType:
          $ref: "#/components/schemas/IncidentProviderType"
        delivered:
          type: boolean
        error:
          type: string

    TestIncidentProviderResponse:
      type: object
      description: "Result of test incident delivery"
      required:
        - result
      properties:
        result:
          $ref: "#/components/schemas/TestIncidentProviderResult"

    Stream:
      type: string
      format: string
      enum:
        - stdout
        - stderr

    UnixTimestamp:
      type: integer
      format: "int64"
      description: "Unix timestamp in seconds"
      example: 1672531199

    DAGFileName:
      type: string
      # only allows alphanumeric characters, underscores, and hyphens
      format: "regex"
      pattern: "^[a-zA-Z0-9_-]+$"
      description: "Name of the DAG file"

    DAGName:
      type: string
      # only allows alphanumeric characters, underscores, and hyphens
      format: "regex"
      pattern: "^[a-zA-Z0-9_-]+$"
      description: "Name of the DAG"

    Pagination:
      type: object
      properties:
        totalRecords:
          type: integer
          description: total number of records
        currentPage:
          type: integer
          description: current page number
        totalPages:
          type: integer
          description: total number of pages
        nextPage:
          type: integer
          description: next page number
        prevPage:
          type: integer
          description: previous page number
      required:
        - totalRecords
        - currentPage
        - totalPages
        - nextPage
        - prevPage

    DAGRunId:
      type: string
      description: "Unique identifier for the DAG-run. The special value 'latest' can be used to reference the most recent DAG-run."
      example: "latest"
      pattern: "^[a-zA-Z0-9_-]+$"

    DAGRunCreateId:
      type: string
      description: "Unique identifier for a newly-created DAG-run. The special value 'latest' is not allowed."
      example: "20240101_120000"
      pattern: "^[a-zA-Z0-9_-]+$"
      not:
        enum:
          - latest

    HealthResponse:
      type: object
      description: "Response object for the health check endpoint"
      properties:
        status:
          type: string
          enum: ["healthy", "unhealthy"]
          description: "Overall health status of the server"
        version:
          type: string
          description: "Current version of the server"
        uptime:
          type: integer
          description: "Server uptime in seconds"
        timestamp:
          type: string
          description: "Current server time"
      required:
        - status
        - version
        - uptime
        - timestamp

    DAGFile:
      type: object
      description: "DAG file with its status information"
      properties:
        fileName:
          type: string
          description: "File ID of the DAG file"
        filePath:
          type: string
          description: "Absolute file path of the DAG file on disk"
        dag:
          $ref: "#/components/schemas/DAG"
        latestDAGRun:
          $ref: "#/components/schemas/DAGRunSummary"
        nextRun:
          type: string
          format: date-time
          description: "Scheduler-aware next planned run time. Pending overdue one-offs remain visible until consumed."
        suspended:
          type: boolean
          description: "Whether the DAG is suspended"
        errors:
          type: array
          description: "List of errors encountered during the request"
          items:
            type: string
      required:
        - fileName
        - dag
        - latestDAGRun
        - suspended
        - errors

    DAG:
      type: object
      description: "Core DAG configuration containing definition and metadata"
      properties:
        group:
          type: string
          description: "Logical grouping of related DAGs for organizational purposes"
        name:
          type: string
          description: "Logical name of the DAG"
        workspace:
          type: string
          description: "Workspace label value for the DAG. Omitted for default DAGs and invalid workspace labels."
        schedule:
          type: array
          description: "List of scheduling expressions defining when DAG-runs should be created from this DAG"
          items:
            $ref: "#/components/schemas/Schedule"
        description:
          type: string
          description: "Human-readable description of the DAG's purpose and behavior"
        params:
          type: array
          description: "List of parameter names that can be passed to DAG-runs created from this DAG"
          items:
            type: string
        defaultParams:
          type: string
          description: "Default parameter values in JSON format if not specified at DAG-run creation"
        labels:
          type: array
          description: "List of labels for categorizing and filtering DAGs"
          items:
            type: string
        tags:
          type: array
          description: "Deprecated alias for labels. List of labels for categorizing and filtering DAGs"
          deprecated: true
          items:
            type: string
        queue:
          type: string
          description: "Name of the queue this DAG is assigned to. If not specified, the DAG name itself becomes the queue name"
        maxActiveRuns:
          type: integer
          description: "DEPRECATED: This field is ignored for local (DAG-based) queues. For concurrency control, use global queues"
          deprecated: true
          x-deprecated-reason: "For concurrency control, configure global queues in config.yaml instead"
        runConfig:
          $ref: "#/components/schemas/RunConfig"
        resources:
          $ref: "#/components/schemas/DAGResources"
      required:
        - name

    Schedule:
      type: object
      description: "Schedule configuration for DAG-run creation"
      additionalProperties: false
      minProperties: 1
      not:
        required:
          - expression
          - at
      properties:
        kind:
          type: string
          enum: ["cron", "at"]
          description: "Schedule type. When omitted alongside expression, the schedule is treated as cron for backward compatibility."
        expression:
          type: string
          description: "Cron expression for recurring schedules"
          x-go-type-skip-optional-pointer: true
        at:
          type: string
          format: date-time
          description: "RFC 3339 timestamp with explicit offset for one-off schedules"
        profile:
          $ref: "#/components/schemas/RuntimeProfileName"
          description: "Runtime profile name that activates this schedule entry"

    Status:
      type: integer
      enum: [0, 1, 2, 3, 4, 5, 6, 7, 8]
      x-enum-varnames:
        - "NotStarted"
        - "Running"
        - "Failed"
        - "Aborted"
        - "Success"
        - "Queued"
        - "PartialSuccess"
        - "Waiting"
        - "Rejected"
      description: |
        Numeric status code indicating current DAG-run state:
        0: "Not started"
        1: "Running"
        2: "Failed"
        3: "Aborted"
        4: "Success"
        5: "Queued"
        6: "Partial Success"
        7: "Waiting for manual action"
        8: "Rejected"

    StatusLabel:
      type: string
      description: "Human-readable status description for the DAG-run"
      enum:
        - "not_started"
        - "running"
        - "failed"
        - "aborted"
        - "succeeded"
        - "queued"
        - "partially_succeeded"
        - "waiting"
        - "rejected"

    TriggerType:
      type: string
      description: "How the DAG-run was initiated"
      enum:
        - "unknown"
        - "scheduler"
        - "manual"
        - "webhook"
        - "subdag"
        - "retry"
        - "catchup"

    NodeStatus:
      type: integer
      enum: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
      x-enum-varnames:
        - "NotStarted"
        - "Running"
        - "Failed"
        - "Aborted"
        - "Success"
        - "Skipped"
        - "PartialSuccess"
        - "Waiting"
        - "Rejected"
        - "Retrying"
      description: |
        Numeric status code indicating current node state:
        0: "Not started"
        1: "Running"
        2: "Failed"
        3: "Aborted"
        4: "Success"
        5: "Skipped"
        6: "Partial Success"
        7: "Waiting for manual action"
        8: "Rejected"
        9: "Retrying"

    NodeStatusLabel:
      type: string
      description: "Human-readable status description for the node"
      enum:
        - "not_started"
        - "running"
        - "failed"
        - "aborted"
        - "succeeded"
        - "skipped"
        - "partially_succeeded"
        - "waiting"
        - "rejected"
        - "retrying"

    SchedulerStatusResponse:
      type: object
      description: "Response containing status of all scheduler instances"
      properties:
        schedulers:
          type: array
          description: "List of all registered scheduler instances"
          items:
            $ref: "#/components/schemas/SchedulerInstance"
      required:
        - schedulers

    SchedulerInstance:
      type: object
      description: "Scheduler instance status information"
      properties:
        instanceId:
          type: string
          description: "Unique identifier of the scheduler instance"
        host:
          type: string
          description: "Hostname where scheduler is running"
        status:
          type: string
          enum: ["active", "inactive", "unknown"]
          description: "Scheduler status (active = holds lock and scheduling)"
        startedAt:
          type: string
          description: "RFC3339 timestamp when scheduler started"
      required:
        - instanceId
        - host
        - status
        - startedAt

    CoordinatorStatusResponse:
      type: object
      description: "Response containing status of all coordinator instances"
      properties:
        coordinators:
          type: array
          description: "List of all registered coordinator instances"
          items:
            $ref: "#/components/schemas/CoordinatorInstance"
      required:
        - coordinators

    CoordinatorInstance:
      type: object
      description: "Coordinator instance status information"
      properties:
        instanceId:
          type: string
          description: "Unique identifier of the coordinator instance"
        host:
          type: string
          description: "Hostname where coordinator is running"
        status:
          type: string
          enum: ["active", "inactive", "unknown"]
          description: "Coordinator status"
        startedAt:
          type: string
          description: "RFC3339 timestamp when coordinator started"
        port:
          type: integer
          description: "Port number the coordinator is listening on"
      required:
        - instanceId
        - host
        - status
        - startedAt
        - port

    TunnelStatusResponse:
      type: object
      description: "Response containing tunnel service status"
      properties:
        enabled:
          type: boolean
          description: "Whether tunneling is enabled in configuration"
        provider:
          type: string
          enum: ["tailscale"]
          description: "The tunnel provider in use"
        status:
          type: string
          enum: ["disabled", "connecting", "connected", "reconnecting", "error"]
          description: "Current status of the tunnel"
        publicUrl:
          type: string
          format: uri
          description: "The public URL provided by the tunnel"
        error:
          type: string
          description: "Error message if tunnel failed"
        startedAt:
          type: string
          format: date-time
          description: "RFC3339 timestamp when tunnel connected"
        mode:
          type: string
          description: "Tunnel mode (e.g., 'direct' or 'funnel' for Tailscale)"
        isPublic:
          type: boolean
          description: "Whether the tunnel provides public internet access"
      required:
        - enabled
        - status

    WorkerHealthStatus:
      type: string
      description: "Health status of the worker based on heartbeat recency"
      enum:
        - "healthy"
        - "warning"
        - "unhealthy"

    DAGDetails:
      type: object
      description: "Detailed DAG configuration information"
      properties:
        type:
          type: string
          enum: [graph, chain, controller]
          description: "Execution type. 'graph' resolves dependencies, 'chain' runs steps in order, 'controller' lets an LLM choose each step."
        tasks:
          type: array
          description: "Goals a controller DAG must satisfy. Present only for type controller."
          items:
            $ref: "#/components/schemas/ControllerTask"
        nextRun:
          type: string
          format: date-time
          description: "Scheduler-aware next planned run time. Pending overdue one-offs remain visible until consumed."
        group:
          type: string
          description: "Logical grouping of related DAGs for organizational purposes"
        name:
          type: string
          description: "Unique identifier for the DAG within its group"
        schedule:
          type: array
          description: "List of scheduling expressions defining when DAG-runs should be created from this DAG"
          items:
            $ref: "#/components/schemas/Schedule"
        description:
          type: string
          description: "Human-readable description of the DAG's purpose and behavior"
        env:
          type: array
          description: "List of environment variables to set before executing a DAG-run"
          items:
            type: string
        logDir:
          type: string
          description: "Directory path for storing log files"
        artifacts:
          $ref: "#/components/schemas/DAGArtifactsConfig"
        handlerOn:
          $ref: "#/components/schemas/HandlerOn"
        steps:
          type: array
          description: "List of steps to execute in DAG-runs created from this DAG"
          items:
            $ref: "#/components/schemas/Step"
        delay:
          type: integer
          description: "Time in seconds to wait before starting a DAG-run"
        histRetentionDays:
          type: integer
          description: "Number of days to retain historical logs"
        histRetentionRuns:
          type: integer
          description: "Number of DAG runs to retain historical logs. Mutually exclusive with histRetentionDays."
        preconditions:
          type: array
          description: "Conditions that must be met before a DAG-run can start"
          items:
            $ref: "#/components/schemas/Condition"
        maxActiveRuns:
          type: integer
          description: "DEPRECATED: This field is ignored for local (DAG-based) queues. For concurrency control, use global queues"
          deprecated: true
          x-deprecated-reason: "For concurrency control, configure global queues in config.yaml instead"
        queue:
          type: string
          description: "Name of the queue this DAG is assigned to. If not specified, the DAG name itself becomes the queue name"
        maxActiveSteps:
          type: integer
          description: "Maximum number of concurrent steps allowed in a DAG run"
        params:
          type: array
          description: "List of parameter names that can be passed to DAG-runs created from this DAG"
          items:
            type: string
        paramDefs:
          type: array
          description: "Ordered parameter definitions derived from DAG params for typed UI rendering and validation"
          items:
            $ref: "#/components/schemas/ParamDef"
        paramSchema:
          type: object
          description: "Resolved JSON Schema for schema-backed DAG params when safe for direct UI form rendering"
          additionalProperties: true
        defaultParams:
          type: string
          description: "Default parameter values in JSON format if not specified at DAG-run creation"
        labels:
          type: array
          description: "List of labels for categorizing and filtering DAGs"
          items:
            type: string
        tags:
          type: array
          description: "Deprecated alias for labels. List of labels for categorizing and filtering DAGs"
          deprecated: true
          items:
            type: string
        runConfig:
          $ref: "#/components/schemas/RunConfig"
        resources:
          $ref: "#/components/schemas/DAGResources"
      required:
        - name

    ValueReferenceNotice:
      type: object
      description: "A passive notice for a supported value reference left unresolved while loading a spec."
      properties:
        message:
          type: string
          description: "Human-readable explanation of the unresolved reference."
        fieldPath:
          type: string
          description: "DAG field path associated with the unresolved reference."
        token:
          type: string
          description: "Original value-reference token that was preserved."
        reason:
          type: string
          description: "Machine-readable reason why the reference was preserved."
          enum:
            - unknown_step_id
            - unknown_output_name
            - missing_dependency
            - self_reference
            - namespace_unavailable
            - unknown_context_field
            - unknown_env_binding
            - unknown_const_name
        class:
          type: string
          description: >-
            Whether the reference is a defect in the spec or its availability
            depends on runtime values or lifecycle scope.
          enum:
            - defect
            - runtime_only
      required:
        - message

    DAGEditorHints:
      type: object
      description: "Editor-only metadata used to synthesize per-document schema hints"
      properties:
        inheritedLegacyDefinitions:
          type: array
          description: "Deprecated legacy execution definitions inherited from base config and available to the current DAG"
          items:
            $ref: "#/components/schemas/InheritedLegacyDefinitionHint"
        inheritedCustomActions:
          type: array
          description: "Custom actions inherited from base config and available to the current DAG"
          items:
            $ref: "#/components/schemas/InheritedCustomActionHint"
      required:
        - inheritedLegacyDefinitions

    InheritedCustomActionHint:
      type: object
      description: "Resolved editor hint for an inherited custom action"
      properties:
        name:
          type: string
          description: "Custom action name"
        description:
          type: string
          description: "Optional custom action description"
        inputSchema:
          type: object
          additionalProperties: true
          description: "Resolved JSON Schema object used to validate and document with input"
        outputSchema:
          type: object
          additionalProperties: true
          description: "Resolved JSON Schema object used to validate stdout JSON output"
      required:
        - name
        - inputSchema

    InheritedLegacyDefinitionHint:
      type: object
      description: "Resolved editor hint for an inherited deprecated legacy execution definition"
      properties:
        name:
          type: string
          description: "Deprecated legacy execution definition name"
        targetType:
          type: string
          description: "Builtin executor type that the deprecated legacy execution definition expands to"
        description:
          type: string
          description: "Optional deprecated legacy execution definition description"
        inputSchema:
          type: object
          additionalProperties: true
          description: "Resolved JSON Schema object used to validate and document with input"
        outputSchema:
          type: object
          additionalProperties: true
          description: "Resolved JSON Schema object used to validate stdout JSON output"
      required:
        - name
        - targetType
        - inputSchema

    ParamScalar:
      anyOf:
        - type: string
        - type: integer
        - type: number
          format: double
        - type: boolean
      description: "Scalar parameter value"

    ParamDef:
      type: object
      description: "Typed metadata for a single DAG parameter"
      properties:
        name:
          type: string
          description: "Parameter name. Omitted for positional parameters."
        type:
          type: string
          description: "Parameter type"
          enum:
            - string
            - integer
            - number
            - boolean
        default:
          $ref: "#/components/schemas/ParamScalar"
        description:
          type: string
        required:
          type: boolean
          default: false
        enum:
          type: array
          items:
            $ref: "#/components/schemas/ParamScalar"
        minimum:
          type: number
          format: double
        maximum:
          type: number
          format: double
        minLength:
          type: integer
        maxLength:
          type: integer
        pattern:
          type: string
      required:
        - type

    RunConfig:
      type: object
      description: "Configuration for controlling user interactions when starting DAG runs"
      properties:
        disableParamEdit:
          type: boolean
          description: "Disable parameter editing when starting the DAG"
          default: false
        disableRunIdEdit:
          type: boolean
          description: "Disable custom run ID specification"
          default: false
      required:
        - disableParamEdit
        - disableRunIdEdit

    DAGResources:
      type: object
      additionalProperties: false
      description: "Resource limits requested for a DAG run"
      properties:
        limits:
          $ref: "#/components/schemas/DAGResourceLimits"

    DAGResourceLimits:
      type: object
      additionalProperties: false
      description: "CPU and memory limits requested for a DAG run"
      properties:
        cpu:
          type: string
          description: "CPU limit as cores (for example, \"2\" or \"0.5\") or millicores (for example, \"500m\")"
        memory:
          type: string
          description: "Memory limit in bytes or with a unit suffix (for example, \"512Mi\", \"1Gi\", or \"2G\")"

    DAGArtifactsConfig:
      type: object
      description: "Configuration for DAG run artifact storage"
      properties:
        enabled:
          type: boolean
          description: "Whether artifact storage is enabled for this DAG"
        dir:
          type: string
          description: "Base directory for storing artifacts for this DAG when explicitly configured"
      required:
        - enabled

    LocalDag:
      type: object
      properties:
        name:
          type: string
          description: "Name of the local DAG"
        dag:
          $ref: "#/components/schemas/DAGDetails"
        errors:
          type: array
          description: "List of errors encountered while processing the local DAG"
          items:
            type: string
      required:
        - name
        - errors

    HandlerOn:
      type: object
      description: "Configuration for event handlers in a DAG-run"
      properties:
        failure:
          $ref: "#/components/schemas/Step"
        success:
          $ref: "#/components/schemas/Step"
        abort:
          $ref: "#/components/schemas/Step"
        exit:
          $ref: "#/components/schemas/Step"

    DAGRunCondition:
      type: object
      description: "Type-keyed current-state runtime condition for a DAG-run. Each condition is the latest observation for its type, not a historical event."
      properties:
        type:
          type: string
          description: "Condition type"
        status:
          type: string
          enum: ["True", "False", "Unknown"]
          description: "Observed status of the condition"
        reason:
          type: string
          description: "Machine-readable reason for the condition status"
        message:
          type: string
          description: "Human-readable detail for the condition status"
        checkedAt:
          type: string
          format: date-time
          description: "RFC 3339 timestamp when the condition was observed"
      required:
        - type
        - status
        - reason
        - message
        - checkedAt

    DAGRunSummary:
      type: object
      description: "Current status of a DAG-run"
      properties:
        dagRunId:
          $ref: "#/components/schemas/DAGRunId"
        name:
          $ref: "#/components/schemas/DAGName"
        workspace:
          type: string
          description: "Workspace label value for the DAG-run. Omitted for default DAG-runs and invalid workspace labels."
        status:
          $ref: "#/components/schemas/Status"
        statusLabel:
          $ref: "#/components/schemas/StatusLabel"
        queuedAt:
          type: string
          description: "RFC 3339 timestamp when the DAG-run was queued"
        autoRetryCount:
          type: integer
          description: "Number of scheduler-issued DAG auto-retries already consumed for this DAG-run"
        autoRetryLimit:
          type: integer
          nullable: true
          description: "Configured DAG-level automatic retry limit captured for this DAG-run; null when DAG-level automatic retry is not configured"
        scheduleTime:
          type: string
          description: "RFC 3339 timestamp of when the DAG-run was scheduled to run"
        startedAt:
          type: string
          description: "RFC 3339 timestamp when the DAG-run started"
        finishedAt:
          type: string
          description: "RFC 3339 timestamp when the DAG-run finished"
        artifactsAvailable:
          type: boolean
          description: "Whether artifact files are available for this DAG-run"
        params:
          type: string
          description: "Runtime parameters passed to the DAG-run in JSON format"
        profileName:
          $ref: "#/components/schemas/RuntimeProfileName"
          description: "Runtime profile selected for this DAG-run."
        workerId:
          type: string
          description: "ID of the worker that executed this DAG-run ('local' for local execution)"
        triggerType:
          $ref: "#/components/schemas/TriggerType"
        triggerActor:
          type: string
          description: "Authenticated actor that initiated the DAG-run, when attribution is available"
        conditions:
          type: array
          description: "Type-keyed current-state runtime conditions for the DAG-run. This list reports the latest condition for each type, not a history of queued reasons."
          items:
            $ref: "#/components/schemas/DAGRunCondition"
        labels:
          type: array
          items:
            type: string
          description: "List of labels for categorizing and filtering DAG runs"
        tags:
          type: array
          items:
            type: string
          description: "Deprecated alias for labels. List of labels for categorizing and filtering DAG runs"
          deprecated: true
      required:
        - dagRunId
        - name
        - status
        - statusLabel
        - startedAt
        - finishedAt
        - artifactsAvailable
        - autoRetryCount

    DAGRunDetails:
      type: object
      description: "Detailed status of a DAG-run including sub DAG-run nodes"
      allOf:
        - $ref: "#/components/schemas/DAGRunSummary"
        - type: object
          description: "Detailed status information for the steps within a DAG-run."
          properties:
            rootDAGRunName:
              type: string
              description: "Name of the root DAG-run"
            rootDAGRunId:
              allOf:
                - $ref: "#/components/schemas/DAGRunId"
                - description: "ID of the root DAG-run"
            parentDAGRunName:
              type: string
              description: "Name of the parent DAG-run"
            parentDAGRunId:
              allOf:
                - $ref: "#/components/schemas/DAGRunId"
                - description: "ID of the parent DAG-run"
            log:
              type: string
              description: "Path to the log file"
            nodes:
              type: array
              description: "Status of individual steps within the DAG-run"
              items:
                $ref: "#/components/schemas/Node"
            onInit:
              $ref: "#/components/schemas/Node"
            onExit:
              $ref: "#/components/schemas/Node"
            onSuccess:
              $ref: "#/components/schemas/Node"
            onFailure:
              $ref: "#/components/schemas/Node"
            onAbort:
              $ref: "#/components/schemas/Node"
            onWait:
              $ref: "#/components/schemas/Node"
            preconditions:
              type: array
              description: "List of preconditions that must be met before the DAG-run can start"
              items:
                $ref: "#/components/schemas/Condition"
            controllerTasks:
              type: array
              description: "Goal progress of a controller DAG-run. Absent for other DAG types."
              items:
                $ref: "#/components/schemas/ControllerTask"
            controllerEvents:
              type: array
              description: "Ordered decision timeline of a controller DAG-run: what the controller ran, in what order, and when each task was satisfied. Absent for other DAG types."
              items:
                $ref: "#/components/schemas/ControllerEvent"
            specFromFile:
              type: boolean
              description: "Whether this DAG-run still has a usable source file on disk, so reschedule can load the current spec from that file instead of the stored historical YAML snapshot."
            sourceFileName:
              $ref: "#/components/schemas/DAGFileName"
              description: "File name of the source DAG definition, derived from the DAG-run's source file path. Only set when the source file still exists on disk. Can be used to navigate to the DAG definition page."
            humanTaskResumePending:
              type: boolean
              description: "Whether completed human-task input is durable but the same DAG-run still needs its retry queued"
          required:
            - rootDAGRunName
            - rootDAGRunId
            - log
            - nodes

    ArtifactNodeType:
      type: string
      description: "Artifact tree node type"
      enum:
        - "directory"
        - "file"

    ArtifactTreeNode:
      type: object
      description: "A single file or directory in a DAG-run artifact tree"
      properties:
        name:
          type: string
          description: "Display name of the artifact entry"
        path:
          type: string
          description: "Relative path of the artifact entry within the artifact directory"
        type:
          $ref: "#/components/schemas/ArtifactNodeType"
        size:
          type: integer
          format: int64
          description: "Size of the artifact file in bytes"
        children:
          type: array
          description: "Nested artifact entries when this node is a directory"
          items:
            $ref: "#/components/schemas/ArtifactTreeNode"
      required:
        - name
        - path
        - type

    ArtifactTreeResponse:
      type: object
      description: "Artifact tree for a DAG-run"
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/ArtifactTreeNode"
      required:
        - items

    ArtifactPreviewKind:
      type: string
      description: "Preview mode for an artifact file"
      enum:
        - "markdown"
        - "html"
        - "text"
        - "image"
        - "binary"

    ArtifactPreviewResponse:
      type: object
      description: "Preview metadata and optional inline content for a DAG-run artifact file"
      properties:
        name:
          type: string
          description: "Artifact file name"
        path:
          type: string
          description: "Relative artifact file path"
        kind:
          $ref: "#/components/schemas/ArtifactPreviewKind"
        mimeType:
          type: string
          description: "Detected MIME type for the artifact file"
        size:
          type: integer
          format: int64
          description: "Artifact file size in bytes"
        tooLarge:
          type: boolean
          description: "Whether the artifact exceeds the inline preview size limit"
        truncated:
          type: boolean
          description: "Whether inline text content was truncated for preview"
        content:
          type: string
          description: "Inline preview content for markdown, HTML, or text artifacts"
      required:
        - name
        - path
        - kind
        - mimeType
        - size
        - tooLarge
        - truncated

    DAGRunOutputs:
      type: object
      description: "Collected outputs from step executions in a DAG-run, including execution metadata. Outputs are populated from string-form output, stdout.outputs, and outputs.write. If the DAG-run completed but no outputs were captured, the outputs object will be empty and metadata fields may be empty strings."
      required:
        - metadata
        - outputs
      properties:
        metadata:
          $ref: "#/components/schemas/OutputsMetadata"
        outputs:
          type: object
          description: "Collected step outputs as key-value pairs. String-form output names are converted from UPPER_CASE to camelCase; stdout.outputs and outputs.write keys are preserved. Values are strings in this API response. Empty object if no outputs were captured."
          additionalProperties:
            type: string
          example:
            totalCount: "42"
            resultFile: "/path/to/result.txt"
            config: '{"key": "value"}'

    OutputsMetadata:
      type: object
      description: "Execution context metadata for the outputs"
      required:
        - dagName
        - dagRunId
        - attemptId
        - status
        - completedAt
      properties:
        dagName:
          $ref: "#/components/schemas/DAGName"
        dagRunId:
          $ref: "#/components/schemas/DAGRunId"
        attemptId:
          type: string
          description: "Attempt identifier within the run"
        status:
          $ref: "#/components/schemas/StatusLabel"
        completedAt:
          type: string
          format: date-time
          description: "RFC3339 timestamp when execution completed"
        params:
          type: string
          description: "JSON-serialized parameters passed to the DAG"

    ControllerEvent:
      type: object
      description: "One entry on a controller DAG-run's decision timeline"
      required:
        - turn
        - kind
      properties:
        turn:
          type: integer
          description: "Controller turn this event belongs to, starting at 1"
        kind:
          type: string
          enum: [action, task_status, ask_user, rejected, stalled]
          description: "What the controller did on this turn"
        name:
          type: string
          description: "Step or task the event concerns"
        status:
          type: string
          description: "Resulting step status for an action event, or the new task status for a task_status event"
        attempt:
          type: integer
          description: "Which run of this step it was, starting at 1"
        reason:
          type: string
          description: "Controller's justification, or why the call was rejected"
        startedAt:
          type: string
          description: "RFC3339 timestamp when the step started"
        finishedAt:
          type: string
          description: "RFC3339 timestamp when the step finished"
        childDagRunId:
          type: string
          description: "Child DAG-run this action produced, for linking to its run page. Absent for steps that run no child DAG."
        childDagName:
          type: string
          description: "Name of the child DAG that ran"

    ControllerTask:
      type: object
      description: "A goal a controller DAG must satisfy before the run concludes"
      required:
        - name
        - status
      properties:
        name:
          type: string
          description: "Unique task name"
        description:
          type: string
          description: "Completion criteria the controller decides against"
        status:
          type: string
          enum: [open, completed, skipped, failed]
          description: "Where the task stands. The run ends once none is open, and fails if any is failed. A skipped task does not fail the run."
        reason:
          type: string
          description: "Justification the controller gave for the current status"

    Node:
      type: object
      description: "Status of an individual step within a DAG-run"
      properties:
        step:
          $ref: "#/components/schemas/Step"
        stdout:
          type: string
          description: "Path to the standard output log file for this step"
        stderr:
          type: string
          description: "Path to the standard error log file for this step"
        startedAt:
          type: string
          description: "RFC3339 timestamp when the step started"
        finishedAt:
          type: string
          description: "RFC3339 timestamp when the step finished"
        status:
          $ref: "#/components/schemas/NodeStatus"
        statusLabel:
          $ref: "#/components/schemas/NodeStatusLabel"
        retryCount:
          type: integer
          description: "Number of retry attempts made for this step"
        doneCount:
          type: integer
          description: "Number of successful completions for repeating steps"
        subRuns:
          type: array
          description: "List of sub DAG-runs associated with this step"
          items:
            $ref: "#/components/schemas/SubDAGRun"
        subRunsRepeated:
          type: array
          description: "List of repeated sub DAG-runs when using repeatPolicy"
          items:
            $ref: "#/components/schemas/SubDAGRun"
        error:
          type: string
          description: "Error message if the step failed"
        humanTaskCompletedBy:
          type: string
          description: "Name of the subject that completed the human task"
        humanTaskCompletedById:
          type: string
          description: "ID of the subject that completed the human task; local CLI IDs use the os:<uid> form"
        approvedAt:
          type: string
          description: "RFC3339 timestamp when the step was approved"
        approvedBy:
          type: string
          description: "Username of who approved the step"
        approvedById:
          type: string
          description: "ID of the subject that approved the step"
        approvalInputs:
          type: object
          additionalProperties:
            type: string
          description: "Key-value inputs provided during approval"
        rejectedAt:
          type: string
          description: "RFC3339 timestamp when the step was rejected"
        rejectedBy:
          type: string
          description: "Username of who rejected the step"
        rejectedById:
          type: string
          description: "ID of the subject that rejected the step"
        rejectionReason:
          type: string
          description: "Optional reason for rejection"
        approvalIteration:
          type: integer
          description: "Number of times this step has been pushed back for re-execution"
        pushBackInputs:
          type: object
          additionalProperties:
            type: string
          description: "Key-value inputs from the last push-back, injected as environment variables during re-execution"
        pushBackHistory:
          type: array
          description: "Chronological push-back history for this step"
          items:
            $ref: "#/components/schemas/PushBackHistoryEntry"
      required:
        - step
        - stdout
        - stderr
        - startedAt
        - finishedAt
        - status
        - statusLabel
        - retryCount
        - doneCount

    PushBackHistoryEntry:
      type: object
      description: "One push-back event recorded for an approval step"
      properties:
        iteration:
          type: integer
          minimum: 1
          description: "Push-back iteration number"
        by:
          type: string
          description: "Authenticated user who pushed the step back"
        byId:
          type: string
          description: "ID of the subject that pushed the step back"
        at:
          type: string
          format: date-time
          description: "RFC3339 timestamp when the push-back was recorded"
        inputs:
          type: object
          additionalProperties:
            type: string
          description: "Inputs provided for this push-back event"
      required:
        - iteration

    SubDAGRun:
      type: object
      description: "Metadata for a sub DAG-run"
      properties:
        dagRunId:
          $ref: "#/components/schemas/DAGRunId"
        params:
          type: string
          description: "Parameters passed to the sub DAG-run in JSON format"
        dagName:
          type: string
          description: "Name of the executed sub-DAG. For chat tool calls, this is the tool DAG name."
      required:
        - dagRunId

    SubDAGRunDetail:
      type: object
      description: "Detailed information for a sub DAG-run including timing and status"
      properties:
        dagRunId:
          $ref: "#/components/schemas/DAGRunId"
        params:
          type: string
          description: "Parameters passed to the sub DAG-run in JSON format"
        dagName:
          type: string
          description: "Name of the executed sub-DAG. For chat tool calls, this is the tool DAG name."
        status:
          $ref: "#/components/schemas/Status"
        statusLabel:
          $ref: "#/components/schemas/StatusLabel"
        startedAt:
          type: string
          description: "RFC 3339 timestamp when the sub DAG-run started"
        finishedAt:
          type: string
          description: "RFC 3339 timestamp when the sub DAG-run finished"
      required:
        - dagRunId
        - status
        - statusLabel
        - startedAt

    StepOutputDeclaration:
      type: object
      description: "One file-based step output declaration published through DAGU_OUTPUT_FILE"
      additionalProperties: false
      required:
        - name
      properties:
        name:
          type: string
          pattern: "^[A-Za-z][A-Za-z0-9_]*$"
          description: "Published output name scoped to the declaring step"
        type:
          type: string
          enum:
            - string
            - json
          description: "Output value type. JSON outputs must contain valid JSON text."

    Step:
      type: object
      description: "Individual task definition that performs a specific operation in a DAG-run"
      x-dagu-required-with:
        outputs:
          - id
      properties:
        name:
          type: string
          description: "Unique identifier for the step within the DAG-run"
        id:
          type: string
          description: "Optional short identifier for the step. Can be used in variable references like ${id.stdout} to access step properties. Must be unique within the DAG if specified"
        description:
          type: string
          description: "Human-readable description of what the step does"
        dir:
          type: string
          description: "Working directory for executing the step's command"
        commands:
          type: array
          description: "List of commands to execute sequentially"
          items:
            $ref: "#/components/schemas/CommandEntry"
        script:
          type: string
          description: "Script content if the step executes a script file"
        stdout:
          type: string
          description: "File path for capturing standard output"
        stderr:
          type: string
          description: "File path for capturing standard error"
        output:
          type: string
          description: "Variable name to store the step's output"
        outputs:
          type: array
          minItems: 1
          description: "Declared file-based step outputs published through DAGU_OUTPUT_FILE for ${steps.<id>.outputs.<name>} references. Steps that declare outputs must also define id."
          items:
            $ref: "#/components/schemas/StepOutputDeclaration"
        call:
          type: string
          description: "The name of the DAG to execute as a sub DAG-run"
        params:
          type: string
          description: "Parameters to pass to the sub DAG-run in JSON format"
        parallel:
          type: object
          description: "Configuration for parallel execution of the step"
          properties:
            items:
              description: "Array of items to process in parallel. Can be a static array or a reference to a variable containing an array"
              oneOf:
                - type: array
                  items:
                    type: string
                - type: string
            maxConcurrent:
              type: integer
              description: "Maximum number of parallel executions. Default is 10 if not specified"
              minimum: 1
        depends:
          type: array
          description: "List of step names that must complete before this step can start"
          items:
            type: string
        repeatPolicy:
          $ref: "#/components/schemas/RepeatPolicy"
        mailOnError:
          type: boolean
          description: "Whether to send email notifications on step failure"
        preconditions:
          type: array
          description: "Conditions that must be met before the step can start"
          items:
            $ref: "#/components/schemas/Condition"
        timeoutSec:
          type: integer
          description: "Maximum execution time for the step in seconds. If set, this timeout takes precedence over the DAG-level timeout for this step."
          minimum: 0
        executorConfig:
          type: object
          description: "Executor configuration for this step"
          properties:
            type:
              type: string
              description: "Type of executor (e.g., 'wait', 'http', 'docker', 'command')"
            config:
              type: object
              description: "Executor-specific configuration"
              additionalProperties: true
        router:
          type: object
          description: "Router configuration for switch/case routing"
          required:
            - value
            - routes
          properties:
            value:
              type: string
              minLength: 1
              description: "Expression to evaluate (e.g., '${STATUS}')"
            routes:
              type: array
              minItems: 1
              items:
                type: object
                required:
                  - pattern
                  - targets
                properties:
                  pattern:
                    type: string
                    minLength: 1
                    description: "Match pattern (exact or 're:regex')"
                  targets:
                    type: array
                    minItems: 1
                    items:
                      type: string
                      minLength: 1
                    description: "Step names to route to"
        approval:
          $ref: "#/components/schemas/ApprovalConfig"
        humanTask:
          $ref: "#/components/schemas/HumanTaskConfig"
      required:
        - name

    SearchResultItem:
      type: object
      description: "Individual search result item for a DAG"
      properties:
        name:
          type: string
          description: "Name of the matching DAG"
        dag:
          $ref: "#/components/schemas/DAG"
        matches:
          type: array
          description: "Details of where matches were found"
          items:
            $ref: "#/components/schemas/SearchMatchItem"
      required:
        - name
        - dag
        - matches

    DAGSearchPageItem:
      type: object
      description: "Lightweight cursor-based search result item for a DAG"
      properties:
        fileName:
          type: string
          description: "DAG file name without extension"
        name:
          type: string
          description: "Display label for the DAG result; file-backed search currently mirrors fileName"
        workspace:
          type: string
          description: "Workspace label value for the matching DAG. Omitted for default DAGs and invalid workspace labels."
        hasMoreMatches:
          type: boolean
          description: "Whether additional snippets are available beyond the preview"
        nextMatchesCursor:
          type: string
          description: "Opaque cursor for loading more snippets for this DAG result"
        matches:
          type: array
          description: "Preview snippets for the result"
          items:
            $ref: "#/components/schemas/SearchMatchItem"
      required:
        - fileName
        - name
        - hasMoreMatches
        - matches

    DAGSearchFeedResponse:
      type: object
      description: "Cursor-based DAG search results"
      properties:
        results:
          type: array
          items:
            $ref: "#/components/schemas/DAGSearchPageItem"
        hasMore:
          type: boolean
        nextCursor:
          type: string
      required:
        - results
        - hasMore

    SearchMatchItem:
      type: object
      description: "Details of a search match within a search result"
      properties:
        line:
          type: string
          description: "Matching line content"
        lineNumber:
          type: integer
          description: "Line number where match was found"
        startLine:
          type: integer
          description: "Start line for context"
      required:
        - line
        - lineNumber
        - startLine

    SearchMatchesResponse:
      type: object
      description: "Cursor-based search match snippets"
      properties:
        matches:
          type: array
          items:
            $ref: "#/components/schemas/SearchMatchItem"
        hasMore:
          type: boolean
        nextCursor:
          type: string
      required:
        - matches
        - hasMore

    Log:
      type: object
      description: "Log information for the execution"
      properties:
        content:
          type: string
          description: "Log content"
        lineCount:
          type: integer
          description: "Number of lines returned"
        totalLines:
          type: integer
          description: "Total number of lines in the log file"
        hasMore:
          type: boolean
          description: "Whether there are more lines available"
        isEstimate:
          type: boolean
          description: "Whether the line count is an estimate"
      required:
        - content

    DAGGridItem:
      type: object
      description: "Grid item for visualizing DAG-run execution history"
      properties:
        name:
          type: string
          description: "Name of the step"
        history:
          type: array
          description: "Status of the step ordered by time"
          items:
            $ref: "#/components/schemas/NodeStatus"
      required:
        - name
        - history

    Condition:
      type: object
      description: "Precondition that must be satisfied before running a step or DAG-run"
      not:
        required:
          - condition
          - eval
      properties:
        condition:
          type: string
          description: "Value or command text to evaluate. When `expected` is omitted, this runs as a command check. When `expected` is set, this is value-resolved and compared as data."
        eval:
          type: string
          description: "Dynamic value expression to evaluate and compare with `expected`. Valid only when `expected` is set and `condition` is omitted."
        expected:
          type: string
          description: "Expected result for a value-match precondition. When set, Dagu compares the actual value from `condition` or `eval` instead of using command exit status."
        negate:
          type: boolean
          description: "If true, inverts the condition result (run when condition does NOT match)"
        error:
          type: string
          description: "Error message if the condition is not met"
        matched:
          type: boolean
          description: "Whether the condition was met"
    RepeatMode:
      type: string
      description: "Repeat execution mode for steps"
      enum:
        - "while"
        - "until"
      x-enum-varnames:
        - "While"
        - "Until"

    RepeatPolicy:
      type: object
      description: "Configuration for step repeat behavior"
      properties:
        repeat:
          $ref: "#/components/schemas/RepeatMode"
        interval:
          type: integer
          description: "Time in seconds to wait between repeat attempts"
        limit:
          type: integer
          description: "Maximum number of times to repeat the step"
        backoff:
          oneOf:
            - type: boolean
              description: "When true, uses default multiplier of 2.0"
            - type: number
              format: float
              description: "Custom exponential backoff multiplier"
        maxIntervalSec:
          type: integer
          description: "Maximum interval in seconds (caps exponential growth)"
        condition:
          $ref: "#/components/schemas/Condition"
        exitCode:
          type: array
          description: "List of exit codes that trigger repeat behavior"
          items:
            type: integer

    CommandEntry:
      type: object
      description: "A command with its arguments"
      properties:
        command:
          type: string
          description: "The command to execute"
        args:
          type: array
          description: "Arguments for the command"
          items:
            type: string
      required:
        - command

    ListLabelResponse:
      type: object
      description: "Response object for listing all labels"
      properties:
        labels:
          type: array
          description: "List of unique labels"
          items:
            type: string
        errors:
          type: array
          description: "List of errors encountered during the request"
          items:
            type: string
      required:
        - labels
        - errors

    ListTagResponse:
      type: object
      description: "Deprecated response object for listing all labels"
      deprecated: true
      properties:
        tags:
          type: array
          description: "List of unique labels"
          items:
            type: string
        errors:
          type: array
          description: "List of errors encountered during the request"
          items:
            type: string
      required:
        - tags
        - errors

    WorkersListResponse:
      type: object
      description: "Response object for listing distributed workers"
      properties:
        workers:
          type: array
          description: "List of distributed workers"
          items:
            $ref: "#/components/schemas/Worker"
        errors:
          type: array
          description: "List of errors encountered during the request"
          items:
            type: string
      required:
        - workers
        - errors

    Worker:
      type: object
      description: "Information about a distributed worker"
      properties:
        id:
          type: string
          description: "Unique identifier for the worker"
        labels:
          type: object
          description: "Key-value pairs of labels assigned to the worker"
          additionalProperties:
            type: string
        totalPollers:
          type: integer
          description: "Total number of pollers configured for this worker"
        busyPollers:
          type: integer
          description: "Number of pollers currently executing tasks"
        runningTasks:
          type: array
          description: "List of tasks currently being executed by this worker"
          items:
            $ref: "#/components/schemas/RunningTask"
        lastHeartbeatAt:
          type: string
          description: "RFC3339 timestamp of the last heartbeat received from this worker"
        healthStatus:
          $ref: "#/components/schemas/WorkerHealthStatus"
      required:
        - id
        - labels
        - totalPollers
        - busyPollers
        - runningTasks
        - lastHeartbeatAt
        - healthStatus

    RunningTask:
      type: object
      description: "Information about a task currently being executed"
      properties:
        dagRunId:
          $ref: "#/components/schemas/DAGRunId"
        dagName:
          $ref: "#/components/schemas/DAGName"
        startedAt:
          type: string
          description: "RFC3339 timestamp when the task started"
        rootDagRunName:
          $ref: "#/components/schemas/DAGName"
        rootDagRunId:
          $ref: "#/components/schemas/DAGRunId"
        parentDagRunName:
          $ref: "#/components/schemas/DAGName"
        parentDagRunId:
          $ref: "#/components/schemas/DAGRunId"
      required:
        - dagRunId
        - dagName
        - startedAt

    QueuesResponse:
      type: object
      description: "Response containing all queues with their active DAG-runs"
      properties:
        queues:
          type: array
          description: "List of all queues with their running and queued DAG-runs"
          items:
            $ref: "#/components/schemas/Queue"
        summary:
          $ref: "#/components/schemas/QueuesSummary"
      required:
        - queues
        - summary

    Queue:
      type: object
      description: "A queue/process group with summary statistics"
      properties:
        name:
          type: string
          description: "Name of the queue (global queue name or DAG name if no queue specified)"
        type:
          type: string
          enum: ["global", "dag-based"]
          description: "Type of queue - 'global' if explicitly defined, 'dag-based' if using DAG name"
        maxConcurrency:
          type: integer
          description: "Maximum number of concurrent runs allowed. For 'global' queues, this is the configured maxConcurrency. For 'dag-based' queues, this is always 1 (FIFO execution)"
          minimum: 1
        runningCount:
          type: integer
          description: "Number of currently running DAG-runs"
          minimum: 0
        queuedCount:
          type: integer
          description: "Number of queued DAG-runs waiting to execute"
          minimum: 0
        running:
          type: array
          description: "List of currently running DAG-runs (bounded by maxConcurrency)"
          items:
            $ref: "#/components/schemas/DAGRunSummary"
      required:
        - name
        - type
        - runningCount
        - queuedCount
        - running

    QueuedDAGRunsPageResponse:
      type: object
      description: "Forward-only paginated queued DAG-run response"
      properties:
        items:
          type: array
          description: "List of queued DAG-run summaries"
          items:
            $ref: "#/components/schemas/DAGRunSummary"
        nextCursor:
          type: string
          description: "Opaque cursor for loading the next page of queued DAG-runs"
      required:
        - items

    QueuesSummary:
      type: object
      description: "Summary statistics across all queues"
      properties:
        totalQueues:
          type: integer
          description: "Total number of active queues"
          minimum: 0
        totalRunning:
          type: integer
          description: "Total DAG-runs currently executing"
          minimum: 0
        totalQueued:
          type: integer
          description: "Total DAG-runs waiting in queues"
          minimum: 0
        totalCapacity:
          type: integer
          description: "Sum of all queue maxConcurrency values"
          minimum: 0
        utilizationPercentage:
          type: number
          format: float
          description: "System-wide utilization (totalRunning / totalCapacity * 100)"
          minimum: 0.0
          maximum: 100.0
      required:
        - totalQueues
        - totalRunning
        - totalQueued
        - totalCapacity
        - utilizationPercentage

    ResourceHistory:
      type: object
      properties:
        cpu:
          type: array
          items:
            $ref: "#/components/schemas/MetricPoint"
        memory:
          type: array
          items:
            $ref: "#/components/schemas/MetricPoint"
        disk:
          type: array
          items:
            $ref: "#/components/schemas/MetricPoint"
        load:
          type: array
          items:
            $ref: "#/components/schemas/MetricPoint"
        memoryTotalBytes:
          type: integer
          format: int64
          description: Total physical memory in bytes
        memoryUsedBytes:
          type: integer
          format: int64
          description: Used physical memory in bytes
        diskTotalBytes:
          type: integer
          format: int64
          description: Total disk space in bytes
        diskUsedBytes:
          type: integer
          format: int64
          description: Used disk space in bytes

    MetricPoint:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          description: Unix timestamp
        value:
          type: number
          format: double
      required:
        - timestamp
        - value

    UserRole:
      type: string
      description: "User role determining access permissions. admin: full access including user management, manager: DAG CRUD and execution with audit log access, developer: DAG CRUD and execution, operator: DAG execution only, viewer: read-only"
      enum:
        - admin
        - manager
        - developer
        - operator
        - viewer

    UserAuthProvider:
      type: string
      description: "Authentication provider for a user account"
      enum:
        - builtin
        - oidc
        - proxy

    WorkspaceName:
      type: string
      description: "Workspace name. The reserved names all, default, and global are not allowed."
      minLength: 1
      maxLength: 64
      pattern: "^[A-Za-z0-9_-]+$"
      not:
        enum:
          - all
          - default
          - global

    WorkspaceGrant:
      type: object
      description: "Role granted for a specific workspace"
      properties:
        workspace:
          $ref: "#/components/schemas/WorkspaceName"
        role:
          $ref: "#/components/schemas/UserRole"
      required:
        - workspace
        - role

    WorkspaceAccess:
      type: object
      description: "Workspace access policy. all=true grants the top-level role in every workspace. all=false requires explicit workspace grants and a top-level viewer role."
      properties:
        all:
          type: boolean
          description: "Whether this identity can access all workspaces"
        grants:
          type: array
          description: "Workspace-specific grants used when all=false"
          items:
            $ref: "#/components/schemas/WorkspaceGrant"
      required:
        - all
        - grants

    SetupRequest:
      type: object
      description: "Request body for initial admin account setup"
      properties:
        username:
          type: string
          description: "Admin username"
          minLength: 1
        password:
          type: string
          description: "Admin password"
          minLength: 8
      required:
        - username
        - password

    LoginRequest:
      type: object
      description: "Request body for user login"
      properties:
        username:
          type: string
          description: "User's username"
          minLength: 1
        password:
          type: string
          description: "User's password"
          minLength: 1
      required:
        - username
        - password

    LoginResponse:
      type: object
      description: "Response containing authentication token"
      properties:
        token:
          type: string
          description: "JWT authentication token"
        expiresAt:
          type: string
          format: date-time
          description: "Token expiration timestamp"
        user:
          $ref: "#/components/schemas/User"
      required:
        - token
        - expiresAt
        - user

    LicenseStatusResponse:
      type: object
      description: "Public status of the current Dagu license"
      properties:
        valid:
          type: boolean
          description: "Whether the loaded license token has not expired"
        plan:
          type: string
          description: "License plan name"
        expiry:
          type: string
          description: "License expiration timestamp, or empty for a perpetual or absent license"
        features:
          type: array
          items:
            type: string
          description: "Feature claims included in the license"
        gracePeriod:
          type: boolean
          description: "Whether the license is expired but still inside its grace period"
        graceEndsAt:
          type: string
          description: "Grace-period end timestamp, or empty when the license has no expiration"
        community:
          type: boolean
          description: "Whether no license claims are loaded"
        source:
          type: string
          description: "Public license source category"
        warningCode:
          type: string
          description: "Warning code included in the license token"
        error:
          type: string
          description: "User-facing explanation when a configured license is unusable"
      required:
        - valid
        - plan
        - expiry
        - features
        - gracePeriod
        - graceEndsAt
        - community
        - source
        - warningCode
        - error

    ChangePasswordRequest:
      type: object
      description: "Request body for changing password"
      properties:
        currentPassword:
          type: string
          description: "Current password for verification"
          minLength: 1
        newPassword:
          type: string
          description: "New password to set"
          minLength: 8
      required:
        - currentPassword
        - newPassword

    ResetPasswordRequest:
      type: object
      description: "Request body for admin password reset"
      properties:
        newPassword:
          type: string
          description: "New password to set for the user"
          minLength: 8
      required:
        - newPassword

    CreateUserRequest:
      type: object
      description: "Request body for creating a new user"
      properties:
        username:
          type: string
          description: "Unique username"
          minLength: 1
          maxLength: 64
        password:
          type: string
          description: "User's password"
          minLength: 8
        role:
          $ref: "#/components/schemas/UserRole"
        workspaceAccess:
          $ref: "#/components/schemas/WorkspaceAccess"
      required:
        - username
        - password
        - role

    UpdateUserRequest:
      type: object
      description: "Request body for updating a user"
      properties:
        username:
          type: string
          description: "New username (must be unique)"
          minLength: 1
          maxLength: 64
        role:
          $ref: "#/components/schemas/UserRole"
        workspaceAccess:
          $ref: "#/components/schemas/WorkspaceAccess"
        isDisabled:
          type: boolean
          description: "Whether to disable the user account"

    User:
      type: object
      description: "User information"
      properties:
        id:
          type: string
          description: "Unique user identifier"
        username:
          type: string
          description: "User's username"
        role:
          $ref: "#/components/schemas/UserRole"
        workspaceAccess:
          $ref: "#/components/schemas/WorkspaceAccess"
        authProvider:
          $ref: "#/components/schemas/UserAuthProvider"
        isDisabled:
          type: boolean
          description: "Whether the user account is disabled"
        createdAt:
          type: string
          format: date-time
          description: "Account creation timestamp"
        updatedAt:
          type: string
          format: date-time
          description: "Last update timestamp"
      required:
        - id
        - username
        - role
        - workspaceAccess
        - createdAt
        - updatedAt

    UserResponse:
      type: object
      description: "Response containing user information"
      properties:
        user:
          $ref: "#/components/schemas/User"
      required:
        - user

    UsersListResponse:
      type: object
      description: "Response containing list of users"
      properties:
        users:
          type: array
          items:
            $ref: "#/components/schemas/User"
        oidcWorkspaceAccessSyncEnabled:
          type: boolean
          description: "Whether OIDC workspace access is synchronized by this node"
        managedRoleProviders:
          type: array
          description: "Authentication providers that synchronize user roles at login on this node"
          uniqueItems: true
          items:
            $ref: "#/components/schemas/UserAuthProvider"
        managedWorkspaceAccessProviders:
          type: array
          description: "Authentication providers that synchronize workspace access at login on this node"
          uniqueItems: true
          items:
            $ref: "#/components/schemas/UserAuthProvider"
      required:
        - users
        - managedRoleProviders
        - managedWorkspaceAccessProviders

    APIKey:
      type: object
      description: "API key information"
      properties:
        id:
          type: string
          description: "Unique identifier"
        name:
          type: string
          description: "Human-readable name"
        description:
          type: string
          description: "Purpose description"
        role:
          $ref: "#/components/schemas/UserRole"
        workspaceAccess:
          $ref: "#/components/schemas/WorkspaceAccess"
        allowedSurfaces:
          type: array
          minItems: 1
          uniqueItems: true
          description: "Interfaces where this API key may be accepted"
          items:
            type: string
            enum: [rest_api, mcp]
        attributionClass:
          type: string
          enum: [user_owned, service_account]
          description: "Whether this key is owned by a user or represents a service account"
        ownerUserId:
          type: string
          description: "Owner user ID when attributionClass is user_owned"
        ownerUsername:
          type: string
          description: "Owner username when attributionClass is user_owned"
        serviceAccountId:
          type: string
          description: "Service-account identifier when attributionClass is service_account"
        serviceAccountName:
          type: string
          description: "Service-account display name when attributionClass is service_account"
        migratedAsServiceAccount:
          type: boolean
          description: "True when a legacy key missing attributionClass was defaulted to service_account"
        keyPrefix:
          type: string
          description: "First 8 characters for identification"
        createdAt:
          type: string
          format: date-time
          description: "Creation timestamp"
        updatedAt:
          type: string
          format: date-time
          description: "Last update timestamp"
        createdBy:
          type: string
          description: "Creator user ID"
        lastUsedAt:
          type: string
          format: date-time
          nullable: true
          description: "Last authentication timestamp"
      required:
        - id
        - name
        - role
        - workspaceAccess
        - allowedSurfaces
        - attributionClass
        - keyPrefix
        - createdAt
        - updatedAt
        - createdBy

    APIKeyResponse:
      type: object
      description: "API key response"
      properties:
        apiKey:
          $ref: "#/components/schemas/APIKey"
      required:
        - apiKey

    APIKeysListResponse:
      type: object
      description: "List of API keys"
      properties:
        apiKeys:
          type: array
          items:
            $ref: "#/components/schemas/APIKey"
      required:
        - apiKeys

    CreateAPIKeyRequest:
      type: object
      description: "Create API key request"
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: "Human-readable name"
        description:
          type: string
          maxLength: 500
          description: "Purpose description"
        role:
          $ref: "#/components/schemas/UserRole"
        workspaceAccess:
          $ref: "#/components/schemas/WorkspaceAccess"
        allowedSurfaces:
          type: array
          minItems: 1
          uniqueItems: true
          description: "Interfaces where this API key may be accepted"
          items:
            type: string
            enum: [rest_api, mcp]
        attributionClass:
          type: string
          enum: [user_owned, service_account]
          description: "Whether this key is owned by a user or represents a service account"
        ownerUserId:
          type: string
          description: "Owner user ID when attributionClass is user_owned"
        serviceAccountName:
          type: string
          description: "Service-account display name when attributionClass is service_account"
      required:
        - name
        - role
        - allowedSurfaces
        - attributionClass

    CreateAPIKeyResponse:
      type: object
      description: "Create API key response"
      properties:
        apiKey:
          $ref: "#/components/schemas/APIKey"
        key:
          type: string
          description: "Full key secret, only returned once"
      required:
        - apiKey
        - key

    UpdateAPIKeyRequest:
      type: object
      description: "Update API key request"
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: "New name"
        description:
          type: string
          maxLength: 500
          description: "New description"
        role:
          $ref: "#/components/schemas/UserRole"
        workspaceAccess:
          $ref: "#/components/schemas/WorkspaceAccess"
        allowedSurfaces:
          type: array
          minItems: 1
          uniqueItems: true
          description: "Interfaces where this API key may be accepted"
          items:
            type: string
            enum: [rest_api, mcp]
        attributionClass:
          type: string
          enum: [user_owned, service_account]
          description: "Whether this key is owned by a user or represents a service account"
        ownerUserId:
          type: string
          description: "Owner user ID when attributionClass is user_owned"
        serviceAccountName:
          type: string
          description: "Service-account display name when attributionClass is service_account"

    SuccessResponse:
      type: object
      description: "Generic success response"
      properties:
        message:
          type: string
          description: "Success message"
      required:
        - message

    # Git Sync schemas
    SyncStatus:
      type: string
      description: "Sync status of a DAG"
      enum:
        - synced
        - modified
        - untracked
        - conflict
        - missing

    SyncSummary:
      type: string
      description: "Summary status for the sync badge"
      enum:
        - synced
        - pending
        - conflict
        - missing
        - error

    SyncItem:
      type: object
      description: "Sync state for a single DAG"
      properties:
        itemId:
          type: string
          description: "Stable DAG identifier (file path without extension)"
        filePath:
          type: string
          description: "Relative file path with extension"
        displayName:
          type: string
          description: "Display-friendly DAG name"
        status:
          $ref: "#/components/schemas/SyncStatus"
        baseCommit:
          type: string
          description: "Commit hash when last synced"
        lastSyncedHash:
          type: string
          description: "Content hash when last synced"
        lastSyncedAt:
          type: string
          format: date-time
          description: "When the DAG was last synced"
        modifiedAt:
          type: string
          format: date-time
          description: "When the DAG was last modified locally"
        localHash:
          type: string
          description: "Current local content hash"
        remoteCommit:
          type: string
          description: "Remote commit hash (for conflicts)"
        remoteAuthor:
          type: string
          description: "Author of the remote commit (for conflicts)"
        remoteMessage:
          type: string
          description: "Message of the remote commit (for conflicts)"
        conflictDetectedAt:
          type: string
          format: date-time
          description: "When the conflict was detected"
        previousStatus:
          $ref: "#/components/schemas/SyncStatus"
          description: "Status before transitioning to missing"
        missingAt:
          type: string
          format: date-time
          description: "When the file was first detected as missing"
      required:
        - itemId
        - filePath
        - displayName
        - status

    SyncStatusCounts:
      type: object
      description: "Counts of DAGs in each sync status"
      properties:
        synced:
          type: integer
        modified:
          type: integer
        untracked:
          type: integer
        conflict:
          type: integer
        missing:
          type: integer
      required:
        - synced
        - modified
        - untracked
        - conflict
        - missing

    SyncStatusResponse:
      type: object
      description: "Overall Git sync status"
      properties:
        enabled:
          type: boolean
          description: "Whether Git sync is enabled"
        repository:
          type: string
          description: "Repository URL"
        branch:
          type: string
          description: "Branch being synced"
        summary:
          $ref: "#/components/schemas/SyncSummary"
        lastSyncAt:
          type: string
          format: date-time
          description: "When the last sync occurred"
        lastSyncCommit:
          type: string
          description: "Commit hash of last sync"
        lastSyncStatus:
          type: string
          description: "Status of last sync (success/error)"
        lastError:
          type: string
          description: "Error message from last failed sync"
        items:
          type: array
          description: "Sync state for each DAG"
          items:
            $ref: "#/components/schemas/SyncItem"
        counts:
          $ref: "#/components/schemas/SyncStatusCounts"
      required:
        - enabled
        - summary
        - items
        - counts

    SyncError:
      type: object
      description: "Error during sync operation"
      properties:
        itemId:
          type: string
        message:
          type: string
      required:
        - message

    SyncItemDiffResponse:
      type: object
      description: "Diff between local and remote versions of a DAG"
      properties:
        itemId:
          type: string
          description: "The DAG identifier"
        filePath:
          type: string
          description: "Relative file path with extension"
        status:
          $ref: "#/components/schemas/SyncStatus"
        localContent:
          type: string
          description: "Current local file content"
        remoteContent:
          type: string
          description: "Content from remote repository"
        remoteCommit:
          type: string
          description: "Commit hash being compared against"
        remoteAuthor:
          type: string
          description: "Author of the remote commit"
        remoteMessage:
          type: string
          description: "Commit message of the remote version"
      required:
        - itemId
        - filePath
        - status
        - localContent

    SyncResultResponse:
      type: object
      description: "Result of a sync operation"
      properties:
        success:
          type: boolean
        message:
          type: string
        synced:
          type: array
          items:
            type: string
          description: "DAG IDs that were synced"
        modified:
          type: array
          items:
            type: string
          description: "DAG IDs that were modified"
        conflicts:
          type: array
          items:
            type: string
          description: "DAG IDs with conflicts"
        errors:
          type: array
          items:
            $ref: "#/components/schemas/SyncError"
        timestamp:
          type: string
          format: date-time
      required:
        - success
        - timestamp

    SyncPublishRequest:
      type: object
      description: "Request to publish a DAG"
      properties:
        message:
          type: string
          description: "Commit message"
        force:
          type: boolean
          default: false
          description: "Force publish even with conflicts"

    SyncPublishAllRequest:
      type: object
      description: "Request to publish selected DAGs"
      properties:
        message:
          type: string
          description: "Commit message"
        itemIds:
          type: array
          items:
            type: string
          description: "DAG IDs to publish. If omitted, all modified or untracked DAGs are published."

    SyncDeleteBatchRequest:
      type: object
      description: "Request to delete selected DAGs"
      properties:
        itemIds:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            type: string
            minLength: 1
          description: "DAG IDs to delete"
        message:
          type: string
          description: "Commit message for the deletion"
        force:
          type: boolean
          description: "Force delete DAGs with local modifications or conflicts"
      required:
        - itemIds

    SyncConflictResponse:
      type: object
      description: "Response when a conflict is detected"
      properties:
        itemId:
          type: string
        remoteCommit:
          type: string
        remoteAuthor:
          type: string
        remoteMessage:
          type: string
        message:
          type: string
      required:
        - itemId
        - message

    SyncConnectionTestResponse:
      type: object
      description: "Result of connection test"
      properties:
        success:
          type: boolean
        message:
          type: string
        error:
          type: string
      required:
        - success

    SyncAuthConfig:
      type: object
      description: "Git authentication configuration"
      properties:
        type:
          type: string
          enum:
            - token
            - ssh
        token:
          type: string
          description: "Personal access token (write-only)"
          writeOnly: true
        sshKeyPath:
          type: string
          description: "Path to SSH private key"
      required:
        - type

    SyncAutoSyncConfig:
      type: object
      description: "Auto-sync configuration"
      properties:
        enabled:
          type: boolean
        onStartup:
          type: boolean
        interval:
          type: integer
          description: "Sync interval in seconds"
      required:
        - enabled
        - onStartup
        - interval

    SyncCommitConfig:
      type: object
      description: "Commit configuration"
      properties:
        authorName:
          type: string
        authorEmail:
          type: string

    SyncConfigResponse:
      type: object
      description: "Git sync configuration"
      properties:
        enabled:
          type: boolean
        repository:
          type: string
        branch:
          type: string
        path:
          type: string
        auth:
          $ref: "#/components/schemas/SyncAuthConfig"
        autoSync:
          $ref: "#/components/schemas/SyncAutoSyncConfig"
        pushEnabled:
          type: boolean
        commit:
          $ref: "#/components/schemas/SyncCommitConfig"
      required:
        - enabled

    SyncConfigUpdateRequest:
      type: object
      description: "Request to update Git sync configuration"
      properties:
        enabled:
          type: boolean
        repository:
          type: string
        branch:
          type: string
        path:
          type: string
        auth:
          $ref: "#/components/schemas/SyncAuthConfig"
        autoSync:
          $ref: "#/components/schemas/SyncAutoSyncConfig"
        pushEnabled:
          type: boolean
        commit:
          $ref: "#/components/schemas/SyncCommitConfig"

    CreateRemoteNodeRequest:
      type: object
      required:
        - name
        - apiBaseUrl
      properties:
        name:
          type: string
          description: "Display name for the remote node"
        description:
          type: string
          description: "Optional description"
        apiBaseUrl:
          type: string
          description: "Base URL of the remote Dagu instance API"
        authType:
          type: string
          enum: ["none", "basic", "token"]
          default: "none"
          description: "Authentication mode"
        basicAuthUsername:
          type: string
          description: "Username for basic auth"
        basicAuthPassword:
          type: string
          description: "Password for basic auth"
        authToken:
          type: string
          description: "Bearer token for token auth"
        skipTlsVerify:
          type: boolean
          default: false
          description: "Skip TLS certificate verification"

    UpdateRemoteNodeRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        apiBaseUrl:
          type: string
        authType:
          type: string
          enum: ["none", "basic", "token"]
        basicAuthUsername:
          type: string
        basicAuthPassword:
          type: string
        authToken:
          type: string
        skipTlsVerify:
          type: boolean

    RemoteNodeResponse:
      type: object
      required:
        - id
        - name
        - apiBaseUrl
        - authType
        - source
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        apiBaseUrl:
          type: string
        authType:
          type: string
          enum: ["none", "basic", "token"]
        hasCredentials:
          type: boolean
          description: "Whether credentials are configured (values are never returned)"
        skipTlsVerify:
          type: boolean
        source:
          type: string
          enum: ["config", "store"]
          description: "Where this node is defined"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    RemoteNodeListResponse:
      type: object
      required:
        - remoteNodes
      properties:
        remoteNodes:
          type: array
          items:
            $ref: "#/components/schemas/RemoteNodeResponse"

    TestRemoteNodeConnectionResponse:
      type: object
      required:
        - success
      properties:
        success:
          type: boolean
        message:
          type: string
        error:
          type: string

    RuntimeProfileName:
      type: string
      minLength: 1
      maxLength: 128
      pattern: "^[a-z0-9][a-z0-9._-]*$"
      description: "Runtime profile name."

    RuntimeProfileOverride:
      type: string
      maxLength: 128
      pattern: "^$|^[a-z0-9][a-z0-9._-]*$"
      description: "Runtime profile override. Empty string means no profile."

    RuntimeProfileKey:
      type: string
      minLength: 1
      maxLength: 255
      pattern: "^[A-Za-z_][A-Za-z0-9_]*$"
      not:
        pattern: "^DAGU_"
      description: "Environment variable key stored in a runtime profile. Keys with the DAGU_ prefix are reserved."

    RuntimeProfileStatus:
      type: string
      enum:
        - active
        - disabled

    RuntimeProfileEntryKind:
      type: string
      enum:
        - variable
        - secret

    CreateRuntimeProfileRequest:
      type: object
      required:
        - name
      properties:
        name:
          $ref: "#/components/schemas/RuntimeProfileName"
        description:
          type: string
        protected:
          type: boolean
          default: false

    UpdateRuntimeProfileRequest:
      type: object
      properties:
        description:
          type: string
        status:
          $ref: "#/components/schemas/RuntimeProfileStatus"
        protected:
          type: boolean

    UpdateInheritedRuntimeProfileRequest:
      type: object
      properties:
        description:
          type: string
        defaultProfile:
          $ref: "#/components/schemas/RuntimeProfileOverride"
          description: "Workspace default runtime profile. Only valid for workspace defaults. Empty string clears the setting; omit to leave it unchanged."

    SetRuntimeProfileVariableRequest:
      type: object
      required:
        - value
      properties:
        value:
          type: string

    SetRuntimeProfileSecretRequest:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          writeOnly: true

    RuntimeProfileEntryResponse:
      type: object
      required:
        - key
        - kind
        - createdAt
        - updatedAt
      properties:
        key:
          $ref: "#/components/schemas/RuntimeProfileKey"
        kind:
          $ref: "#/components/schemas/RuntimeProfileEntryKind"
        value:
          type: string
          description: "Stored value for non-secret variables. Omitted for secret entries."
        secretId:
          type: string
          description: "Managed secret ID for secret entries. The secret value is never returned."
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    RuntimeProfileResponse:
      type: object
      required:
        - id
        - name
        - status
        - protected
        - entries
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        name:
          $ref: "#/components/schemas/RuntimeProfileName"
        description:
          type: string
        status:
          $ref: "#/components/schemas/RuntimeProfileStatus"
        protected:
          type: boolean
        entries:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeProfileEntryResponse"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    InheritedRuntimeProfileScope:
      type: string
      enum:
        - global
        - workspace

    InheritedRuntimeProfileName:
      type: string
      description: "Non-selectable inherited profile layer name."
      pattern: "^_global$|^_workspaces/[A-Za-z0-9_-]+$"

    InheritedRuntimeProfileResponse:
      type: object
      required:
        - name
        - scope
        - status
        - protected
        - entries
      properties:
        id:
          type: string
          description: "Persistent record ID. Omitted until the inherited layer is first saved."
        name:
          $ref: "#/components/schemas/InheritedRuntimeProfileName"
        scope:
          $ref: "#/components/schemas/InheritedRuntimeProfileScope"
        workspace:
          $ref: "#/components/schemas/WorkspaceName"
        defaultProfile:
          $ref: "#/components/schemas/RuntimeProfileName"
          description: "Workspace default runtime profile used when a run and DAG do not select a profile."
        description:
          type: string
        status:
          $ref: "#/components/schemas/RuntimeProfileStatus"
        protected:
          type: boolean
        entries:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeProfileEntryResponse"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    RuntimeProfileListResponse:
      type: object
      required:
        - profiles
      properties:
        profiles:
          type: array
          items:
            $ref: "#/components/schemas/RuntimeProfileResponse"

    SecretProviderType:
      type: string
      enum:
        - dagu-managed
        - vault
        - kubernetes
        - gcp
        - aws
        - azure
        - alibaba

    SecretStatus:
      type: string
      enum:
        - active
        - disabled

    CreateSecretRequest:
      type: object
      required:
        - ref
        - providerType
      properties:
        workspace:
          type: string
          description: "Secret scope for management. Use global for workspace-less secrets or a workspace name. Omit for global."
        ref:
          type: string
          description: "Secret ref used from DAG YAML, for example prod/db-password."
          pattern: "^[a-z0-9][a-z0-9-]*(/[a-z0-9][a-z0-9-]*)*$"
        description:
          type: string
        providerType:
          type: string
          enum:
            - dagu-managed
        value:
          type: string
          writeOnly: true
          description: "Initial Dagu-managed value. Write-only; never returned by the API."

    UpdateSecretRequest:
      type: object
      properties:
        description:
          type: string
        providerConnectionId:
          type: string
        providerRef:
          type: string

    WriteSecretVersionRequest:
      type: object
      required:
        - value
      properties:
        value:
          type: string
          writeOnly: true

    SecretResponse:
      type: object
      required:
        - id
        - workspace
        - ref
        - providerType
        - currentVersion
        - status
        - hasValue
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        workspace:
          type: string
          description: "global for workspace-less secrets, otherwise the workspace name."
        ref:
          type: string
          description: "Secret ref used from DAG YAML, for example prod/db-password."
        description:
          type: string
        providerType:
          $ref: "#/components/schemas/SecretProviderType"
        providerConnectionId:
          type: string
        providerRef:
          type: string
        providerRefFingerprint:
          type: string
        currentVersion:
          type: integer
        status:
          $ref: "#/components/schemas/SecretStatus"
        hasValue:
          type: boolean
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        lastCheckedAt:
          type: string
          format: date-time
        lastResolvedAt:
          type: string
          format: date-time
        lastRotatedAt:
          type: string
          format: date-time

    SecretListResponse:
      type: object
      required:
        - secrets
        - total
      properties:
        secrets:
          type: array
          items:
            $ref: "#/components/schemas/SecretResponse"
        total:
          type: integer

    ViewColumn:
      type: string
      enum:
        - queued
        - running
        - review
        - done
        - failed
      description: "A status column available in a Kanban view."

    ViewSpec:
      type: object
      required:
        - name
        - intervalDays
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: "Display name for the view."
        type:
          type: string
          enum:
            - kanban
          default: kanban
          description: "Render type. Currently only kanban is supported."
        workspace:
          type: string
          maxLength: 64
          pattern: "^$|^[A-Za-z0-9_-]+$"
          not:
            enum:
              - all
              - default
              - global
          description: "Workspace filter. Empty string means all workspaces; otherwise use a workspace name."
        labels:
          type: array
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 128
          description: "Label filter (AND logic), each item key or key=value."
        dagName:
          type: string
          maxLength: 255
          description: "DAG name substring filter. Empty matches any."
        intervalDays:
          type: integer
          minimum: 1
          maximum: 30
          description: "Required number of days each row (bucket) groups. Rows scroll back in time by this unit."
        columns:
          type: array
          minItems: 1
          uniqueItems: true
          items:
            $ref: "#/components/schemas/ViewColumn"
          description: "Status columns to display, in left-to-right order. Omitted values use the default order with all columns visible."
        pinned:
          type: boolean
          default: false
          description: "Whether the view is pinned to the left sidebar."

    View:
      type: object
      required:
        - id
        - name
        - type
        - intervalDays
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        name:
          type: string
        type:
          type: string
        workspace:
          type: string
        labels:
          type: array
          items:
            type: string
        dagName:
          type: string
        intervalDays:
          type: integer
        columns:
          type: array
          items:
            $ref: "#/components/schemas/ViewColumn"
          description: "Visible status columns in left-to-right display order."
        pinned:
          type: boolean
        createdBy:
          type: string
          description: "Username of the creator, for display only."
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    ViewListResponse:
      type: object
      required:
        - views
      properties:
        views:
          type: array
          items:
            $ref: "#/components/schemas/View"

    CreateWorkspaceRequest:
      type: object
      required:
        - name
      properties:
        name:
          $ref: "#/components/schemas/WorkspaceName"
        description:
          type: string

    UpdateWorkspaceRequest:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/WorkspaceName"
        description:
          type: string

    WorkspaceResponse:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          $ref: "#/components/schemas/WorkspaceName"
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time

    WorkspaceListResponse:
      type: object
      required:
        - workspaces
      properties:
        workspaces:
          type: array
          items:
            $ref: "#/components/schemas/WorkspaceResponse"

# Apply security requirements globally
security:
  - apiToken: []
  - basicAuth: []
  - {}