openapi: 3.1.0
info:
  title: Sencho API
  version: 0.23.0
  description: |
    REST API for Sencho, a self-hosted Docker Compose management dashboard.

    Sencho exposes a public API for automating stack deployments, managing webhooks,
    monitoring fleet health, and integrating with CI/CD pipelines.

    ## Authentication

    All authenticated endpoints accept a Bearer token in the `Authorization` header.
    Generate API tokens from **Settings > API Tokens** in the Sencho dashboard (requires Admiral license).

    ```
    Authorization: Bearer YOUR_API_TOKEN
    ```

    ## Node Routing

    Sencho manages multiple nodes (local and remote). To target a specific node,
    include the `x-node-id` header or `?nodeId=` query parameter. If omitted,
    the request targets the default node.

    ## License Tiers

    Some endpoints require a Pro or Admiral license. Requests to gated endpoints
    on Community Edition return `403` with `code: "PRO_REQUIRED"` or `code: "ADMIRAL_REQUIRED"`.
  contact:
    name: Sencho
    url: https://sencho.io
  license:
    name: BSL 1.1
    url: https://github.com/AnsoCode/Sencho/blob/main/LICENSE

servers:
  - url: "{protocol}://{host}:{port}"
    description: Your Sencho instance
    variables:
      protocol:
        default: https
        enum: [http, https]
      host:
        default: localhost
      port:
        default: "3000"

security:
  - bearerAuth: []

tags:
  - name: Health
    description: Instance health check
  - name: Stacks
    description: Create, read, update, delete, and operate Docker Compose stacks
  - name: Containers
    description: List and manage running containers
  - name: API Tokens
    description: Manage scoped API tokens (Admiral license required)
  - name: Webhooks
    description: Configure and trigger deployment webhooks (Pro license required)
  - name: Nodes
    description: Manage local and remote Sencho nodes
  - name: Fleet
    description: Multi-node fleet overview and snapshots (Pro license required)
  - name: Scheduled Tasks
    description: Configure recurring automated operations (Admiral license required)

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: API token generated from Settings > API Tokens. Scopes — `read-only`, `deploy-only`, or `full-admin`.
    webhookSignature:
      type: apiKey
      in: header
      name: X-Webhook-Signature
      description: HMAC-SHA256 signature for webhook trigger requests. Compute as `sha256=HMAC(request_body, webhook_secret)`.

  parameters:
    stackName:
      name: stackName
      in: path
      required: true
      description: >
        Stack directory name. Must match `^[a-zA-Z0-9_-]+$` (alphanumeric characters,
        hyphens, and underscores only). Returns `400 Invalid stack name` if the name
        contains path separators, dots, spaces, or other special characters.
      schema:
        type: string
        pattern: '^[a-zA-Z0-9_-]+$'
        example: my-stack
    nodeId:
      name: x-node-id
      in: header
      required: false
      description: Target a specific node by ID. If omitted, the default node is used. Can also be passed as `?nodeId=` query parameter.
      schema:
        type: integer
        example: 1
    nodeIdQuery:
      name: nodeId
      in: query
      required: false
      description: Target a specific node by ID (alternative to `x-node-id` header).
      schema:
        type: integer
        example: 1
    idPath:
      name: id
      in: path
      required: true
      description: Numeric resource ID.
      schema:
        type: integer

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Human-readable error message.
        code:
          type: string
          description: Machine-readable error code (e.g., `PRO_REQUIRED`, `SCOPE_DENIED`).
          enum: [PRO_REQUIRED, ADMIRAL_REQUIRED, SCOPE_DENIED]

    SuccessMessage:
      type: object
      required: [message]
      properties:
        message:
          type: string

    SuccessBoolean:
      type: object
      required: [success]
      properties:
        success:
          type: boolean
          example: true

    Container:
      type: object
      properties:
        Id:
          type: string
          description: Docker container ID.
        Names:
          type: array
          items:
            type: string
          description: Container names (prefixed with `/`).
        Service:
          type: string
          description: Compose service name (if part of a stack).
        State:
          type: string
          description: Container state.
          enum: [running, exited, paused, restarting, dead, created]
        Status:
          type: string
          description: Human-readable status string (e.g., "Up 2 hours").
        Ports:
          type: array
          items:
            type: object
            properties:
              PrivatePort:
                type: integer
              PublicPort:
                type: integer

    Node:
      type: object
      required: [id, name, type, compose_dir, is_default, created_at]
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum: [local, remote]
        compose_dir:
          type: string
          description: Base directory for Docker Compose stacks on this node.
        is_default:
          type: integer
          enum: [0, 1]
          description: Whether this is the default node (1 = true).
        api_url:
          type: string
          description: Remote node API URL (only for remote nodes).
        api_token:
          type: string
          description: Redacted API token for remote node authentication.
        created_at:
          type: integer
          description: Unix timestamp (seconds).

    Webhook:
      type: object
      required: [id, name, stack_name, action, secret, enabled, created_at]
      properties:
        id:
          type: integer
        name:
          type: string
        stack_name:
          type: string
        action:
          type: string
          enum: [deploy, restart, stop, start, pull]
        secret:
          type: string
          description: Masked secret (e.g., `****...****`). Full secret is only returned on creation.
        enabled:
          type: integer
          enum: [0, 1]
        created_at:
          type: integer
          description: Unix timestamp (seconds).

    WebhookExecution:
      type: object
      properties:
        id:
          type: integer
        webhook_id:
          type: integer
        triggered_at:
          type: integer
          description: Unix timestamp (seconds).
        status:
          type: string
        response:
          type: string
        error:
          type: ["string", "null"]

    ApiToken:
      type: object
      required: [id, name, scope, user_id, created_at]
      properties:
        id:
          type: integer
        name:
          type: string
        scope:
          type: string
          enum: [read-only, deploy-only, full-admin]
        user_id:
          type: integer
        created_at:
          type: integer
          description: Unix timestamp (seconds).
        expires_at:
          type: ["integer", "null"]
          description: Unix timestamp (seconds) or null for no expiry.
        revoked_at:
          type: ["integer", "null"]
        last_used_at:
          type: ["integer", "null"]

    FleetNodeOverview:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        type:
          type: string
          enum: [local, remote]
        status:
          type: string
          enum: [online, offline]
        stats:
          type: ["object", "null"]
          description: Container statistics for the node.
        systemStats:
          type: ["object", "null"]
          description: Host system resource statistics.
        stacks:
          type: ["integer", "null"]
          description: Number of stacks on this node.

    FleetSnapshot:
      type: object
      required: [id, description, created_by, created_at, node_count, stack_count]
      properties:
        id:
          type: integer
        description:
          type: string
        created_by:
          type: string
        created_at:
          type: integer
          description: Unix timestamp (seconds).
        node_count:
          type: integer
        stack_count:
          type: integer
        skipped_nodes:
          type: string
          description: JSON-stringified array of skipped node names.

    FleetSnapshotDetail:
      allOf:
        - $ref: "#/components/schemas/FleetSnapshot"
        - type: object
          properties:
            nodes:
              type: array
              items:
                type: object
                properties:
                  nodeId:
                    type: integer
                  nodeName:
                    type: string
                  stacks:
                    type: array
                    items:
                      type: object
                      properties:
                        stackName:
                          type: string
                        files:
                          type: array
                          items:
                            type: object
                            properties:
                              filename:
                                type: string
                              content:
                                type: string

    ScheduledTask:
      type: object
      required: [id, name, target_type, action, cron_expression, enabled, created_by, created_at, updated_at]
      properties:
        id:
          type: integer
        name:
          type: string
        target_type:
          type: string
          enum: [stack, fleet, system]
        target_id:
          type: ["string", "null"]
          description: Stack name (when target_type is `stack`).
        node_id:
          type: ["integer", "null"]
          description: Target node ID (when target_type is `stack`).
        action:
          type: string
          enum: [restart, snapshot, prune]
        cron_expression:
          type: string
          description: Standard cron expression (5 fields).
          example: "0 3 * * *"
        enabled:
          type: integer
          enum: [0, 1]
        created_by:
          type: string
        created_at:
          type: integer
          description: Unix timestamp (seconds).
        updated_at:
          type: integer
          description: Unix timestamp (seconds).
        last_run_at:
          type: ["integer", "null"]
        next_run_at:
          type: ["integer", "null"]
        last_status:
          type: ["string", "null"]
        last_error:
          type: ["string", "null"]
        prune_targets:
          type: ["string", "null"]
          description: JSON-stringified array of prune targets (containers, images, networks, volumes).
        target_services:
          type: ["string", "null"]
          description: JSON-stringified array of service names to restart.
        prune_label_filter:
          type: ["string", "null"]
          description: Docker label filter for prune operations.

    ScheduledTaskRun:
      type: object
      required: [id, task_id, started_at, status, triggered_by]
      properties:
        id:
          type: integer
        task_id:
          type: integer
        started_at:
          type: integer
          description: Unix timestamp (seconds).
        completed_at:
          type: ["integer", "null"]
        triggered_by:
          type: string
          enum: [scheduled, manual]
        status:
          type: string
          enum: [pending, running, success, failed]
        output:
          type: ["string", "null"]
        error:
          type: ["string", "null"]

  responses:
    Unauthorized:
      description: Authentication required. Provide a valid Bearer token.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "Authentication required"
    Forbidden:
      description: Insufficient permissions or license tier.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          example:
            error: "This feature requires Sencho Pro."
            code: "PRO_REQUIRED"
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    InternalError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

paths:
  # ── Health ──────────────────────────────────────────────
  /api/health:
    get:
      operationId: getHealth
      tags: [Health]
      summary: Health check
      description: Returns instance health status and uptime. No authentication required. Useful for uptime monitors and Docker HEALTHCHECK.
      security: []
      responses:
        "200":
          description: Instance is healthy.
          content:
            application/json:
              schema:
                type: object
                required: [status, uptime]
                properties:
                  status:
                    type: string
                    example: ok
                  uptime:
                    type: number
                    description: Process uptime in seconds.

  # ── Stacks ──────────────────────────────────────────────
  /api/stacks:
    get:
      operationId: listStacks
      tags: [Stacks]
      summary: List all stacks
      description: Returns an array of stack directory names on the target node.
      parameters:
        - $ref: "#/components/parameters/nodeId"
        - $ref: "#/components/parameters/nodeIdQuery"
      responses:
        "200":
          description: Array of stack names.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ["traefik", "portainer", "monitoring"]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      operationId: createStack
      tags: [Stacks]
      summary: Create a new stack
      description: Creates a new stack directory with a default `compose.yaml` file.
      parameters:
        - $ref: "#/components/parameters/nodeId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [stackName]
              properties:
                stackName:
                  type: string
                  description: Stack name. Alphanumeric characters, hyphens, and underscores only.
                  pattern: "^[a-zA-Z0-9_-]+$"
                  example: my-new-stack
      responses:
        "201":
          description: Stack created.
          content:
            application/json:
              schema:
                type: object
                required: [message, name]
                properties:
                  message:
                    type: string
                    example: Stack created successfully
                  name:
                    type: string
                    example: my-new-stack
        "400":
          description: Invalid stack name.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "409":
          description: Stack already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: Stack already exists
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}:
    get:
      operationId: getStack
      tags: [Stacks]
      summary: Get stack compose file
      description: Returns the raw `compose.yaml` content for the specified stack.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Raw compose.yaml content.
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Invalid stack name.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      operationId: updateStack
      tags: [Stacks]
      summary: Update stack compose file
      description: Overwrites the `compose.yaml` content for the specified stack. Requires `stack:edit` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
                  description: Full compose.yaml content.
      responses:
        "200":
          description: Stack saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Stack saved successfully
        "400":
          description: Invalid stack name or content.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: deleteStack
      tags: [Stacks]
      summary: Delete stack
      description: Permanently deletes the stack directory and all its files. Requires `stack:delete` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Stack deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Stack deleted successfully
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/envs:
    get:
      operationId: getStackEnvFiles
      tags: [Stacks]
      summary: List env file paths
      description: Returns the list of environment file paths referenced in the stack's compose file (`env_file` directives).
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: List of env file paths.
          content:
            application/json:
              schema:
                type: object
                required: [envFiles]
                properties:
                  envFiles:
                    type: array
                    items:
                      type: string
                    example: [".env", "config/database.env"]
        "400":
          description: Invalid stack name.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/env:
    get:
      operationId: getStackEnv
      tags: [Stacks]
      summary: Get env file content
      description: Returns the content of an environment file. Defaults to `.env` if no `file` query parameter is specified.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
        - name: file
          in: query
          required: false
          description: Path to a specific env file (must be in the resolved env files list).
          schema:
            type: string
      responses:
        "200":
          description: Raw env file content (KEY=VALUE format).
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Invalid stack name or disallowed file path.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: Env file not found.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: Env file not found
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      operationId: updateStackEnv
      tags: [Stacks]
      summary: Update env file
      description: Overwrites an environment file's content. Requires `stack:edit` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
        - name: file
          in: query
          required: false
          description: Path to a specific env file to update.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [content]
              properties:
                content:
                  type: string
                  description: Full env file content (KEY=VALUE format).
      responses:
        "200":
          description: Env file saved.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Env file saved successfully
        "400":
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/containers:
    get:
      operationId: getStackContainers
      tags: [Stacks]
      summary: List stack containers
      description: Returns all containers belonging to the specified stack.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Array of container objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Container"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/services:
    get:
      operationId: getStackServices
      tags: [Stacks]
      summary: List stack services
      description: Returns the service names defined in the stack's compose file.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Array of service names.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                example: ["web", "db", "redis"]
        "400":
          description: Invalid stack name.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/deploy:
    post:
      operationId: deployStack
      tags: [Stacks]
      summary: Deploy stack
      description: |
        Runs `docker compose up -d` for the stack. On Pro tier, uses atomic deployment
        with automatic rollback on failure. Requires `stack:deploy` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Stack deployed successfully.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Deployed successfully
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          description: Deployment failed.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                  rolledBack:
                    type: boolean
                    description: Whether the stack was automatically rolled back (Pro tier).

  /api/stacks/{stackName}/down:
    post:
      operationId: downStack
      tags: [Stacks]
      summary: Tear down stack
      description: Runs `docker compose down` for the stack, removing containers and networks. Requires `stack:deploy` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Command started.
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status:
                    type: string
                    example: Command started
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/start:
    post:
      operationId: startStack
      tags: [Stacks]
      summary: Start stack containers
      description: Starts all stopped containers in the stack via the Docker Engine API. Requires `stack:deploy` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Containers started.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No containers found for this stack.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/stop:
    post:
      operationId: stopStack
      tags: [Stacks]
      summary: Stop stack containers
      description: Stops all running containers in the stack via the Docker Engine API. Requires `stack:deploy` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Containers stopped.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No containers found for this stack.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/restart:
    post:
      operationId: restartStack
      tags: [Stacks]
      summary: Restart stack containers
      description: Restarts all containers in the stack via the Docker Engine API. Requires `stack:deploy` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Containers restarted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No containers found for this stack.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/update:
    post:
      operationId: updateStackImages
      tags: [Stacks]
      summary: Pull and recreate stack
      description: |
        Pulls latest images and recreates containers (`docker compose pull && up -d`).
        On Pro tier, uses atomic update with automatic rollback on failure.
        Requires `stack:deploy` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Update completed.
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status:
                    type: string
                    example: Update completed
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          description: Update failed.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                  rolledBack:
                    type: boolean

  /api/stacks/{stackName}/rollback:
    post:
      operationId: rollbackStack
      tags: [Stacks]
      summary: Rollback stack
      description: Restores the stack to its previous deployment state. Requires Pro license and `stack:deploy` permission.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Stack rolled back.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Stack rolled back successfully.
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: No backup available.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: No backup available for this stack.
        "500":
          $ref: "#/components/responses/InternalError"

  /api/stacks/{stackName}/backup:
    get:
      operationId: getStackBackupStatus
      tags: [Stacks]
      summary: Check backup status
      description: Returns whether a deployment backup exists for this stack and when it was created.
      parameters:
        - $ref: "#/components/parameters/stackName"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Backup status.
          content:
            application/json:
              schema:
                type: object
                required: [exists]
                properties:
                  exists:
                    type: boolean
                  timestamp:
                    type: ["integer", "null"]
                    description: Unix timestamp of the backup, or null if no backup exists.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"


  # ── Containers ──────────────────────────────────────────
  /api/containers:
    get:
      operationId: listContainers
      tags: [Containers]
      summary: List all containers
      description: Returns all running containers on the target node.
      parameters:
        - $ref: "#/components/parameters/nodeId"
        - $ref: "#/components/parameters/nodeIdQuery"
      responses:
        "200":
          description: Array of container objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Container"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/containers/{id}/logs:
    get:
      operationId: streamContainerLogs
      tags: [Containers]
      summary: Stream container logs
      description: |
        Streams container logs as Server-Sent Events (SSE). The connection remains
        open and pushes new log lines as `data:` events in real time.
      parameters:
        - $ref: "#/components/parameters/idPath"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: SSE log stream.
          content:
            text/event-stream:
              schema:
                type: string
                description: Each event is a `data:` line containing a JSON-encoded log string.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/containers/{id}/start:
    post:
      operationId: startContainer
      tags: [Containers]
      summary: Start container
      description: Starts a stopped container. Requires admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Container started.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Container started
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/containers/{id}/stop:
    post:
      operationId: stopContainer
      tags: [Containers]
      summary: Stop container
      description: Stops a running container. Requires admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Container stopped.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Container stopped
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/containers/{id}/restart:
    post:
      operationId: restartContainer
      tags: [Containers]
      summary: Restart container
      description: Restarts a container. Requires admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
        - $ref: "#/components/parameters/nodeId"
      responses:
        "200":
          description: Container restarted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Container restarted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  # ── API Tokens ──────────────────────────────────────────
  /api/api-tokens:
    post:
      operationId: createApiToken
      tags: [API Tokens]
      summary: Create API token
      description: |
        Generates a new scoped API token. The full token is only returned in the creation response
        and cannot be retrieved again. Requires Admiral license and admin role.

        **Note:** API tokens cannot create other API tokens.
      responses:
        "201":
          description: Token created. The `token` field contains the full JWT — save it now, it won't be shown again.
          content:
            application/json:
              schema:
                type: object
                required: [id, token]
                properties:
                  id:
                    type: integer
                  token:
                    type: string
                    description: Full JWT token. Store securely — this is the only time it's returned.
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, scope]
              properties:
                name:
                  type: string
                  description: Human-readable token name.
                  maxLength: 100
                  example: CI/CD Deploy Token
                scope:
                  type: string
                  description: |
                    Permission scope:
                    - `read-only` — GET requests only
                    - `deploy-only` — Read + stack deploy/stop/restart operations
                    - `full-admin` — All operations (except license, user, and token management)
                  enum: [read-only, deploy-only, full-admin]
                expires_in:
                  type: ["integer", "null"]
                  description: Token lifetime in days. Use `null` for no expiry.
                  enum: [30, 60, 90, 365, null]
                  example: 90
    get:
      operationId: listApiTokens
      tags: [API Tokens]
      summary: List API tokens
      description: |
        Returns all API tokens for the current user. Token hashes are never exposed.
        Requires Admiral license and admin role.

        **Note:** API tokens cannot list other API tokens.
      responses:
        "200":
          description: Array of token metadata.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ApiToken"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/api-tokens/{id}:
    delete:
      operationId: revokeApiToken
      tags: [API Tokens]
      summary: Revoke API token
      description: |
        Permanently revokes an API token. Users can only revoke their own tokens.
        Requires Admiral license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Token revoked.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "400":
          description: Invalid token ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  # ── Webhooks ────────────────────────────────────────────
  /api/webhooks:
    get:
      operationId: listWebhooks
      tags: [Webhooks]
      summary: List webhooks
      description: Returns all configured webhooks with masked secrets. Requires Pro license.
      responses:
        "200":
          description: Array of webhook objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Webhook"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      operationId: createWebhook
      tags: [Webhooks]
      summary: Create webhook
      description: |
        Creates a new webhook for a stack. The webhook secret is auto-generated and only
        returned in the creation response. Requires Pro license and admin role.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, stack_name, action]
              properties:
                name:
                  type: string
                  example: GitHub Deploy Hook
                stack_name:
                  type: string
                  description: Target stack name.
                  example: my-app
                action:
                  type: string
                  enum: [deploy, restart, stop, start, pull]
                  description: Action to execute when the webhook is triggered.
                enabled:
                  type: boolean
                  default: true
      responses:
        "201":
          description: Webhook created. The `secret` field is the HMAC signing key — save it now.
          content:
            application/json:
              schema:
                type: object
                required: [id, secret]
                properties:
                  id:
                    type: integer
                  secret:
                    type: string
                    description: HMAC-SHA256 signing secret. Store securely — this is the only time it's returned in full.
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/webhooks/{id}:
    put:
      operationId: updateWebhook
      tags: [Webhooks]
      summary: Update webhook
      description: Updates webhook configuration. Requires Pro license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                stack_name:
                  type: string
                action:
                  type: string
                  enum: [deploy, restart, stop, start, pull]
                enabled:
                  type: boolean
      responses:
        "200":
          description: Webhook updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: deleteWebhook
      tags: [Webhooks]
      summary: Delete webhook
      description: Permanently deletes a webhook. Requires Pro license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Webhook deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/webhooks/{id}/history:
    get:
      operationId: getWebhookHistory
      tags: [Webhooks]
      summary: Get webhook execution history
      description: Returns the execution log for a webhook. Requires Pro license.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Array of execution records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/WebhookExecution"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/webhooks/{id}/trigger:
    post:
      operationId: triggerWebhook
      tags: [Webhooks]
      summary: Trigger webhook
      description: |
        Externally triggers a webhook action. This endpoint is public but requires a valid
        HMAC-SHA256 signature in the `X-Webhook-Signature` header.

        Compute the signature as: `sha256=` + HMAC-SHA256(raw_request_body, webhook_secret).
      security:
        - webhookSignature: []
      parameters:
        - $ref: "#/components/parameters/idPath"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                action:
                  type: string
                  description: Override the default webhook action.
      responses:
        "202":
          description: Webhook accepted and action queued.
          content:
            application/json:
              schema:
                type: object
                required: [message, action]
                properties:
                  message:
                    type: string
                    example: Webhook accepted
                  action:
                    type: string
                    example: deploy
        "401":
          description: Missing or invalid signature.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Webhook not found or disabled.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  # ── Nodes ───────────────────────────────────────────────
  /api/nodes:
    get:
      operationId: listNodes
      tags: [Nodes]
      summary: List all nodes
      description: Returns all registered nodes (local and remote).
      responses:
        "200":
          description: Array of node objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Node"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      operationId: createNode
      tags: [Nodes]
      summary: Register a new node
      description: |
        Adds a new local or remote node. Remote nodes require an API URL pointing to
        another Sencho instance and an API token for authentication.
        Requires `node:manage` permission.

        **Note:** API tokens cannot manage nodes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, type]
              properties:
                name:
                  type: string
                  example: production-server
                type:
                  type: string
                  enum: [local, remote]
                compose_dir:
                  type: string
                  description: Base directory for Compose stacks (defaults to `/app/compose`).
                is_default:
                  type: boolean
                  description: Set as the default node.
                api_url:
                  type: string
                  description: Remote Sencho instance URL (required for remote nodes).
                  example: https://sencho.example.com:3000
                api_token:
                  type: string
                  description: API token for authenticating with the remote Sencho instance.
      responses:
        "200":
          description: Node created.
          content:
            application/json:
              schema:
                type: object
                required: [success, id]
                properties:
                  success:
                    type: boolean
                  id:
                    type: integer
                    description: New node ID.
                  warning:
                    type: string
                    description: Warning if the remote URL uses plain HTTP.
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          description: Node name already exists.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/nodes/{id}:
    get:
      operationId: getNode
      tags: [Nodes]
      summary: Get node details
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Node object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Node"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      operationId: updateNode
      tags: [Nodes]
      summary: Update node
      description: Updates node configuration. Requires `node:manage` permission.
      parameters:
        - $ref: "#/components/parameters/idPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                compose_dir:
                  type: string
                is_default:
                  type: boolean
                api_url:
                  type: string
                api_token:
                  type: string
      responses:
        "200":
          description: Node updated.
          content:
            application/json:
              schema:
                type: object
                required: [success]
                properties:
                  success:
                    type: boolean
                  warning:
                    type: string
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: deleteNode
      tags: [Nodes]
      summary: Delete node
      description: Removes a node from the fleet. Requires `node:manage` permission.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Node deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/nodes/{id}/test:
    post:
      operationId: testNodeConnection
      tags: [Nodes]
      summary: Test node connection
      description: Tests connectivity to a node. For remote nodes, pings the remote Sencho instance's health endpoint.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Connection test result.
          content:
            application/json:
              schema:
                type: object
                required: [success]
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
                  error:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  # ── Fleet ───────────────────────────────────────────────
  /api/fleet/overview:
    get:
      operationId: getFleetOverview
      tags: [Fleet]
      summary: Fleet overview
      description: Returns an aggregated overview of all nodes including status, container stats, and stack counts.
      responses:
        "200":
          description: Array of fleet node overviews.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/FleetNodeOverview"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/fleet/node/{nodeId}/stacks:
    get:
      operationId: getFleetNodeStacks
      tags: [Fleet]
      summary: List stacks on a fleet node
      description: Returns stack names from a specific fleet node. Requires Pro license.
      parameters:
        - name: nodeId
          in: path
          required: true
          schema:
            type: integer
      responses:
        "200":
          description: Array of stack names.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
        "502":
          description: Failed to reach remote node.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "503":
          description: Remote node not configured.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/fleet/node/{nodeId}/stacks/{stackName}/containers:
    get:
      operationId: getFleetNodeStackContainers
      tags: [Fleet]
      summary: List containers in a fleet node stack
      description: Returns containers for a specific stack on a specific fleet node. Requires Pro license.
      parameters:
        - name: nodeId
          in: path
          required: true
          schema:
            type: integer
        - $ref: "#/components/parameters/stackName"
      responses:
        "200":
          description: Array of container objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Container"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
        "503":
          description: Remote node not configured.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"

  /api/fleet/snapshots:
    post:
      operationId: createFleetSnapshot
      tags: [Fleet]
      summary: Create fleet snapshot
      description: Creates a point-in-time backup of all compose files across all nodes. Requires Pro license and admin role.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                description:
                  type: string
                  description: Optional description for the snapshot.
                  example: Pre-migration backup
      responses:
        "201":
          description: Snapshot created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FleetSnapshot"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    get:
      operationId: listFleetSnapshots
      tags: [Fleet]
      summary: List fleet snapshots
      description: Returns paginated fleet snapshots. Requires Pro license.
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Paginated snapshot list.
          content:
            application/json:
              schema:
                type: object
                required: [snapshots, total]
                properties:
                  snapshots:
                    type: array
                    items:
                      $ref: "#/components/schemas/FleetSnapshot"
                  total:
                    type: integer
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/fleet/snapshots/{id}:
    get:
      operationId: getFleetSnapshot
      tags: [Fleet]
      summary: Get snapshot details
      description: Returns full snapshot details including all captured files grouped by node and stack. Requires Pro license.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Snapshot with file contents.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FleetSnapshotDetail"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: deleteFleetSnapshot
      tags: [Fleet]
      summary: Delete snapshot
      description: Permanently deletes a fleet snapshot. Requires Pro license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Snapshot deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/fleet/snapshots/{id}/restore:
    post:
      operationId: restoreFleetSnapshot
      tags: [Fleet]
      summary: Restore from snapshot
      description: Restores a specific stack on a specific node from the snapshot. Optionally redeploys after restore. Requires Pro license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [nodeId, stackName]
              properties:
                nodeId:
                  type: integer
                  description: Target node ID to restore to.
                stackName:
                  type: string
                  description: Stack to restore.
                redeploy:
                  type: boolean
                  default: false
                  description: Whether to redeploy the stack after restoring files.
      responses:
        "200":
          description: Stack restored.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessMessage"
              example:
                message: Stack restored successfully.
        "400":
          description: Missing required fields.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  # ── Scheduled Tasks ─────────────────────────────────────
  /api/scheduled-tasks:
    get:
      operationId: listScheduledTasks
      tags: [Scheduled Tasks]
      summary: List scheduled tasks
      description: Returns all scheduled tasks. Requires Admiral license and admin role.
      responses:
        "200":
          description: Array of scheduled task objects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ScheduledTask"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"
    post:
      operationId: createScheduledTask
      tags: [Scheduled Tasks]
      summary: Create scheduled task
      description: |
        Creates a new recurring task. Action-target rules:
        - `restart` requires `target_type: stack` (with `target_id` and `node_id`)
        - `snapshot` requires `target_type: fleet`
        - `prune` requires `target_type: system`

        Requires Admiral license and admin role.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name, target_type, action, cron_expression]
              properties:
                name:
                  type: string
                  example: Nightly restart
                target_type:
                  type: string
                  enum: [stack, fleet, system]
                target_id:
                  type: string
                  description: Stack name (required when target_type is `stack`).
                node_id:
                  type: integer
                  description: Target node ID (required when target_type is `stack`).
                action:
                  type: string
                  enum: [restart, snapshot, prune]
                cron_expression:
                  type: string
                  description: Standard 5-field cron expression.
                  example: "0 3 * * *"
                enabled:
                  type: boolean
                  default: true
                prune_targets:
                  type: array
                  items:
                    type: string
                    enum: [containers, images, networks, volumes]
                  description: Resources to prune (only for `prune` action).
                target_services:
                  type: array
                  items:
                    type: string
                  description: Specific services to restart (only for `restart` action).
                prune_label_filter:
                  type: string
                  description: Docker label filter for prune operations.
      responses:
        "201":
          description: Task created.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduledTask"
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/scheduled-tasks/{id}:
    get:
      operationId: getScheduledTask
      tags: [Scheduled Tasks]
      summary: Get scheduled task
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Scheduled task object.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduledTask"
        "400":
          description: Invalid task ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    put:
      operationId: updateScheduledTask
      tags: [Scheduled Tasks]
      summary: Update scheduled task
      description: Updates task configuration. Same validation rules as creation apply. Requires Admiral license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                target_type:
                  type: string
                  enum: [stack, fleet, system]
                target_id:
                  type: string
                node_id:
                  type: integer
                action:
                  type: string
                  enum: [restart, snapshot, prune]
                cron_expression:
                  type: string
                enabled:
                  type: boolean
                prune_targets:
                  type: array
                  items:
                    type: string
                target_services:
                  type: array
                  items:
                    type: string
                prune_label_filter:
                  type: string
      responses:
        "200":
          description: Task updated.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduledTask"
        "400":
          description: Validation error.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"
    delete:
      operationId: deleteScheduledTask
      tags: [Scheduled Tasks]
      summary: Delete scheduled task
      description: Permanently deletes a scheduled task. Requires Admiral license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Task deleted.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SuccessBoolean"
        "400":
          description: Invalid task ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/scheduled-tasks/{id}/toggle:
    patch:
      operationId: toggleScheduledTask
      tags: [Scheduled Tasks]
      summary: Toggle task enabled/disabled
      description: Flips the enabled state of a scheduled task. Requires Admiral license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Task toggled. Returns updated task.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduledTask"
        "400":
          description: Invalid task ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/scheduled-tasks/{id}/run:
    post:
      operationId: runScheduledTask
      tags: [Scheduled Tasks]
      summary: Run task immediately
      description: Executes the scheduled task immediately, regardless of its cron schedule. Requires Admiral license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: Task executed. Returns updated task with `last_run_at`.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ScheduledTask"
        "400":
          description: Invalid task ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/scheduled-tasks/{id}/runs:
    get:
      operationId: listScheduledTaskRuns
      tags: [Scheduled Tasks]
      summary: List task execution history
      description: Returns paginated execution history for a scheduled task. Requires Admiral license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        "200":
          description: Array of task run records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ScheduledTaskRun"
        "400":
          description: Invalid task ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"

  /api/scheduled-tasks/{id}/runs/export:
    get:
      operationId: exportScheduledTaskRuns
      tags: [Scheduled Tasks]
      summary: Export task history as CSV
      description: Downloads the execution history for a scheduled task as a CSV file. Requires Admiral license and admin role.
      parameters:
        - $ref: "#/components/parameters/idPath"
      responses:
        "200":
          description: CSV file download.
          content:
            text/csv:
              schema:
                type: string
                description: "CSV with columns: Timestamp, Source, Status, Duration (s), Details"
        "400":
          description: Invalid task ID.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "500":
          $ref: "#/components/responses/InternalError"