openapi: 3.0.3
info:
  title: Planekeeper Client API
  description: |
    Organization-scoped API for managing version tracking and alerts.
    This API is designed for external consumers and organization-level operations.
  version: v1
  contact:
    name: Planekeeper
servers:
  - url: https://www.planekeeper.com/api/v1/client
    description: Production
  - url: /api/v1/client
    description: Current Host

security:
  - apiKey: []

paths:
  # Shared paths - referenced from openapi-shared.yaml
  /gather-jobs:
    $ref: './openapi-shared.yaml#/paths/~1gather-jobs'
  /gather-jobs/{id}:
    $ref: './openapi-shared.yaml#/paths/~1gather-jobs~1%7Bid%7D'
  /gather-jobs/{id}/run:
    $ref: './openapi-shared.yaml#/paths/~1gather-jobs~1%7Bid%7D~1run'
  /gather-jobs/{id}/clear-releases:
    $ref: './openapi-shared.yaml#/paths/~1gather-jobs~1%7Bid%7D~1clear-releases'
  /scrape-jobs:
    $ref: './openapi-shared.yaml#/paths/~1scrape-jobs'
  /scrape-jobs/{id}:
    $ref: './openapi-shared.yaml#/paths/~1scrape-jobs~1%7Bid%7D'
  /scrape-jobs/{id}/versions:
    $ref: './openapi-shared.yaml#/paths/~1scrape-jobs~1%7Bid%7D~1versions'
  /scrape-jobs/{id}/run:
    $ref: './openapi-shared.yaml#/paths/~1scrape-jobs~1%7Bid%7D~1run'
  /scrape-jobs/{id}/set-version:
    $ref: './openapi-shared.yaml#/paths/~1scrape-jobs~1%7Bid%7D~1set-version'
  /helm-sync-jobs:
    $ref: './openapi-shared.yaml#/paths/~1helm-sync-jobs'
  /helm-sync-jobs/{id}:
    $ref: './openapi-shared.yaml#/paths/~1helm-sync-jobs~1%7Bid%7D'
  /helm-sync-jobs/{id}/run:
    $ref: './openapi-shared.yaml#/paths/~1helm-sync-jobs~1%7Bid%7D~1run'
  /helm-sync-jobs/{id}/charts:
    $ref: './openapi-shared.yaml#/paths/~1helm-sync-jobs~1%7Bid%7D~1charts'
  /releases:
    $ref: './openapi-shared.yaml#/paths/~1releases'
  /releases/{id}:
    $ref: './openapi-shared.yaml#/paths/~1releases~1%7Bid%7D'
  /releases/summary:
    $ref: './openapi-shared.yaml#/paths/~1releases~1summary'
  /versions:
    $ref: './openapi-shared.yaml#/paths/~1versions'
  /settings:
    $ref: './openapi-shared.yaml#/paths/~1settings'
  /agents:
    $ref: './openapi-shared.yaml#/paths/~1agents'
  /validate/regex:
    $ref: './openapi-shared.yaml#/paths/~1validate~1regex'

  # Client-only paths
  /rules:
    get:
      operationId: listMonitoringRules
      summary: List monitoring rules
      description: Lists all monitoring rules for the authenticated organization with pagination.
      tags:
        - Rules
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
      responses:
        "200":
          description: List of monitoring rules
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListMonitoringRulesResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    post:
      operationId: createMonitoringRule
      summary: Create a monitoring rule
      description: |
        Creates a new monitoring rule for the authenticated organization.
        Rules define how to evaluate version staleness and generate alerts.
      tags:
        - Rules
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateMonitoringRuleRequest"
      responses:
        "201":
          description: Monitoring rule created successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/MonitoringRule"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /rules/{id}:
    get:
      operationId: getMonitoringRule
      summary: Get a monitoring rule by ID
      description: Retrieves a single monitoring rule by its ID.
      tags:
        - Rules
      parameters:
        - name: id
          in: path
          required: true
          description: The monitoring rule ID
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "200":
          description: Monitoring rule details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/MonitoringRule"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateMonitoringRule
      summary: Update a monitoring rule
      description: Updates an existing monitoring rule.
      tags:
        - Rules
      parameters:
        - name: id
          in: path
          required: true
          description: The monitoring rule ID
          schema:
            type: integer
            format: int64
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateMonitoringRuleRequest"
      responses:
        "200":
          description: Monitoring rule updated successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/MonitoringRule"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    delete:
      operationId: deleteMonitoringRule
      summary: Delete a monitoring rule
      description: Deletes a monitoring rule. This also deletes all associated alerts.
      tags:
        - Rules
      parameters:
        - name: id
          in: path
          required: true
          description: The monitoring rule ID
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "204":
          description: Monitoring rule deleted successfully
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /rules/{id}/toggle:
    post:
      operationId: toggleMonitoringRule
      summary: Toggle a monitoring rule's active state
      description: Toggles whether a monitoring rule is active or inactive.
      tags:
        - Rules
      parameters:
        - name: id
          in: path
          required: true
          description: The monitoring rule ID
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "200":
          description: Monitoring rule toggled successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/MonitoringRule"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /rules/evaluate:
    post:
      operationId: evaluateRules
      summary: Trigger rule evaluation
      description: |
        Triggers evaluation of all active alert configurations.
        Returns a summary of the evaluation including alerts created.
      tags:
        - Rules
      responses:
        "200":
          description: Evaluation completed
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/EvaluateRulesResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts:
    get:
      operationId: listAlerts
      summary: List alerts
      description: Lists all alerts for the authenticated organization with pagination and filtering.
      tags:
        - Alerts
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
        - name: unacknowledged_only
          in: query
          description: Only return unacknowledged alerts
          schema:
            type: boolean
            default: false
        - name: severity
          in: query
          description: Filter by severity level
          schema:
            $ref: "./components/schemas.yaml#/AlertSeverity"
      responses:
        "200":
          description: List of alerts
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListAlertsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/summary:
    get:
      operationId: getAlertSummary
      summary: Get alert summary
      description: Returns aggregate counts of alerts by status and severity.
      tags:
        - Alerts
      responses:
        "200":
          description: Alert summary
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/AlertSummary"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/resolved:
    get:
      operationId: listResolvedAlerts
      summary: List resolved alerts
      description: Lists resolved (historical) alerts for the authenticated organization with pagination and filtering.
      tags:
        - Alerts
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
        - name: severity
          in: query
          description: Filter by severity level
          schema:
            $ref: "./components/schemas.yaml#/AlertSeverity"
      responses:
        "200":
          description: List of resolved alerts
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListAlertsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/{id}:
    get:
      operationId: getAlert
      summary: Get alert by ID
      description: Returns a single alert with full detail including config, rule, and job info.
      tags:
        - Alerts
      parameters:
        - name: id
          in: path
          required: true
          description: The alert ID
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "200":
          description: Alert details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/Alert"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/{id}/resolve:
    post:
      operationId: resolveAlert
      summary: Manually resolve an alert
      description: Marks an alert as resolved by setting resolved_at timestamp. Resolved alerts appear in the resolved alerts list.
      tags:
        - Alerts
      parameters:
        - name: id
          in: path
          required: true
          description: The alert ID
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "204":
          description: Alert resolved successfully
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/{id}/acknowledge:
    post:
      operationId: acknowledgeAlert
      summary: Acknowledge an alert
      description: Marks an alert as acknowledged.
      tags:
        - Alerts
      parameters:
        - name: id
          in: path
          required: true
          description: The alert ID
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "200":
          description: Alert acknowledged successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/Alert"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/{id}/unacknowledge:
    post:
      operationId: unacknowledgeAlert
      summary: Unacknowledge an alert
      description: Removes the acknowledged status from an alert.
      tags:
        - Alerts
      parameters:
        - name: id
          in: path
          required: true
          description: The alert ID
          schema:
            type: integer
            format: int64
            minimum: 1
      responses:
        "200":
          description: Alert unacknowledged successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/Alert"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/acknowledge:
    post:
      operationId: bulkAcknowledgeAlerts
      summary: Bulk acknowledge alerts
      description: Acknowledges multiple alerts at once.
      tags:
        - Alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/BulkAcknowledgeRequest"
      responses:
        "200":
          description: Alerts acknowledged successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/BulkAcknowledgeResponse"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alert-configs:
    get:
      operationId: listAlertConfigs
      summary: List alert configurations
      description: |
        Lists all alert configurations for the authenticated organization.
        Alert configs link scrape jobs (version source) with gather jobs (release source) and rules.
      tags:
        - AlertConfigs
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
      responses:
        "200":
          description: Alert configurations retrieved
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListAlertConfigsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    post:
      operationId: createAlertConfig
      summary: Create an alert configuration
      description: Creates a new alert configuration linking a scrape job, gather job, and rule.
      tags:
        - AlertConfigs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateAlertConfigRequest"
      responses:
        "201":
          description: Alert config created
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/AlertConfig"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alert-configs/{id}:
    get:
      operationId: getAlertConfig
      summary: Get an alert configuration
      tags:
        - AlertConfigs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Alert config details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/AlertConfig"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateAlertConfig
      summary: Update an alert configuration
      tags:
        - AlertConfigs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateAlertConfigRequest"
      responses:
        "200":
          description: Alert config updated
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/AlertConfig"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    delete:
      operationId: deleteAlertConfig
      summary: Delete an alert configuration
      tags:
        - AlertConfigs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Alert config deleted
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alert-configs/{id}/toggle:
    post:
      operationId: toggleAlertConfig
      summary: Toggle alert configuration active status
      tags:
        - AlertConfigs
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Alert config toggled
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/AlertConfig"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /dropdowns/org-members:
    get:
      operationId: listOrgMembersDropdown
      summary: List organization members for dropdown selection
      tags:
        - Dropdowns
      responses:
        "200":
          description: Organization members list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./components/schemas.yaml#/OrgMemberDropdownItem"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /dropdowns/scrape-jobs:
    get:
      operationId: listScrapeJobsDropdown
      summary: List scrape jobs for dropdown selection
      tags:
        - Dropdowns
      responses:
        "200":
          description: Scrape jobs list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./components/schemas.yaml#/ScrapeJobDropdownItem"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /dropdowns/gather-jobs:
    get:
      operationId: listGatherJobsDropdown
      summary: List gather jobs for dropdown selection
      tags:
        - Dropdowns
      responses:
        "200":
          description: Gather jobs list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./components/schemas.yaml#/GatherJobDropdownItem"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /dropdowns/gather-jobs/global:
    get:
      operationId: listGlobalGatherJobsDropdown
      summary: List global gather jobs for dropdown selection
      description: |
        Lists all globally-scoped gather jobs for dropdown selection in alert configurations.
        These are jobs created by system API keys that provide releases accessible to all organizations.
      tags:
        - Dropdowns
      responses:
        "200":
          description: Global gather jobs list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./components/schemas.yaml#/GatherJobDropdownItem"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /dropdowns/rules:
    get:
      operationId: listRulesDropdown
      summary: List rules for dropdown selection
      tags:
        - Dropdowns
      responses:
        "200":
          description: Rules list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./components/schemas.yaml#/RuleDropdownItem"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /settings/effective:
    get:
      operationId: listEffectiveSettings
      summary: List effective settings for the caller's organization
      description: |
        Returns all effective settings for the authenticated organization.
        For each setting, returns the org-specific override if one exists,
        otherwise returns the global default value.
      tags:
        - Settings
      responses:
        "200":
          description: List of effective settings
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListEffectiveSettingsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /settings/org-overrides:
    get:
      operationId: listOrgOverrides
      summary: List organization-specific setting overrides
      description: |
        Returns only the settings that have organization-specific overrides.
        Settings using the global default are not included.
      tags:
        - Settings
      responses:
        "200":
          description: List of org override settings
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListSettingsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /settings/org-overrides/{key}:
    put:
      operationId: upsertOrgOverride
      summary: Create or update an organization setting override
      description: |
        Creates or updates an organization-specific override for a setting.
        The setting will use this value instead of the global default.
      tags:
        - Settings
      parameters:
        - name: key
          in: path
          required: true
          description: The setting key to override
          schema:
            type: string
            example: agent_poll_interval_seconds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateSettingRequest"
      responses:
        "200":
          description: Setting override created/updated successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/Setting"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    delete:
      operationId: deleteOrgOverride
      summary: Remove an organization setting override
      description: |
        Removes an organization-specific override for a setting.
        The setting will revert to using the global default value.
      tags:
        - Settings
      parameters:
        - name: key
          in: path
          required: true
          description: The setting key to remove override for
          schema:
            type: string
            example: agent_poll_interval_seconds
      responses:
        "204":
          description: Setting override removed successfully
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  # Notification Channel endpoints
  /notification-channels:
    get:
      operationId: listNotificationChannels
      summary: List notification channels
      description: Lists all notification channels for the authenticated organization.
      tags:
        - Notifications
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
      responses:
        "200":
          description: List of notification channels
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListNotificationChannelsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    post:
      operationId: createNotificationChannel
      summary: Create a notification channel
      description: Creates a new notification channel (webhook).
      tags:
        - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateNotificationChannelRequest"
      responses:
        "201":
          description: Channel created successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationChannel"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-channels/{id}:
    get:
      operationId: getNotificationChannel
      summary: Get a notification channel
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Channel details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationChannel"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateNotificationChannel
      summary: Update a notification channel
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateNotificationChannelRequest"
      responses:
        "200":
          description: Channel updated
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationChannel"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    delete:
      operationId: deleteNotificationChannel
      summary: Delete a notification channel
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Channel deleted
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-channels/{id}/test:
    post:
      operationId: testNotificationChannel
      summary: Test a notification channel
      description: Sends a test notification to verify channel connectivity.
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Test result
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationChannelTestResult"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-channels/{id}/toggle:
    post:
      operationId: toggleNotificationChannel
      summary: Toggle channel active state
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Channel toggled
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationChannel"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-channels/{id}/stats:
    get:
      operationId: getNotificationChannelStats
      summary: Get channel health stats
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Channel stats
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationChannelStats"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-channels/validate:
    post:
      operationId: validateWebhookConfig
      summary: Validate webhook configuration
      description: Validates URL and template syntax without creating a channel.
      tags:
        - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/ValidateWebhookConfigRequest"
      responses:
        "200":
          description: Validation result
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/WebhookConfigValidationResult"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-templates:
    get:
      operationId: listNotificationTemplates
      summary: List effective notification templates
      description: |
        Returns all notification templates for the organization with their effective values.
        Each template shows its source (global default or organization override) and
        the available fields for that template category.

        Global templates are read-only defaults set by administrators.
        Organization templates override global defaults and can be managed via PUT/DELETE.
      tags:
        - Notifications
      responses:
        "200":
          description: List of effective templates
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListNotificationTemplatesResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-templates/{category}:
    put:
      operationId: updateNotificationTemplate
      summary: Set organization template override
      description: |
        Sets an organization-level template override for the specified category.
        This overrides the global default template for this organization only.

        To clear an org override and revert to the global default, use DELETE instead.
      tags:
        - Notifications
      parameters:
        - name: category
          in: path
          required: true
          schema:
            $ref: "./components/schemas.yaml#/NotificationTemplateCategory"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateNotificationTemplateRequest"
      responses:
        "200":
          description: Template updated
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationTemplateInfo"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    delete:
      operationId: deleteNotificationTemplate
      summary: Remove organization template override
      description: |
        Removes the organization-level template override for the specified category.
        After deletion, the global default template will be used.
      tags:
        - Notifications
      parameters:
        - name: category
          in: path
          required: true
          schema:
            $ref: "./components/schemas.yaml#/NotificationTemplateCategory"
      responses:
        "200":
          description: Template override removed, now using global default
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationTemplateInfo"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          description: No organization override exists for this category
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ErrorResponse"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-templates/preview:
    post:
      operationId: previewNotificationTemplate
      summary: Preview template rendering
      description: |
        Renders a template with sample data to preview the output.
        Useful for testing templates before saving them.
      tags:
        - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/NotificationTemplatePreviewRequest"
      responses:
        "200":
          description: Preview result
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationTemplatePreviewResponse"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-rules:
    get:
      operationId: listNotificationRules
      summary: List notification rules
      tags:
        - Notifications
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
      responses:
        "200":
          description: List of notification rules
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListNotificationRulesResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    post:
      operationId: createNotificationRule
      summary: Create a notification rule
      tags:
        - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateNotificationRuleRequest"
      responses:
        "201":
          description: Rule created
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationRule"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-rules/{id}:
    get:
      operationId: getNotificationRule
      summary: Get a notification rule
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Rule details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationRule"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateNotificationRule
      summary: Update a notification rule
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateNotificationRuleRequest"
      responses:
        "200":
          description: Rule updated
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationRule"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    delete:
      operationId: deleteNotificationRule
      summary: Delete a notification rule
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: Rule deleted
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-rules/{id}/toggle:
    post:
      operationId: toggleNotificationRule
      summary: Toggle rule active state
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Rule toggled
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationRule"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-rules/{id}/stats:
    get:
      operationId: getNotificationRuleStats
      summary: Get rule match stats
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Rule stats
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationRuleStats"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-rules/{id}/simulate:
    post:
      operationId: simulateNotificationRule
      summary: Simulate rule matching
      description: Returns which channels would be notified for given alert criteria.
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/SimulateNotificationRuleRequest"
      responses:
        "200":
          description: Simulation result
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationRuleSimulationResult"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-settings:
    get:
      operationId: getNotificationSettings
      summary: Get notification settings
      description: Gets the organization's default notification channel and other settings.
      tags:
        - Notifications
      responses:
        "200":
          description: Notification settings
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationSettings"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateNotificationSettings
      summary: Update notification settings
      tags:
        - Notifications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateNotificationSettingsRequest"
      responses:
        "200":
          description: Settings updated
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationSettings"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-deliveries:
    get:
      operationId: listNotificationDeliveries
      summary: List notification deliveries
      description: Lists all notification deliveries with filtering.
      tags:
        - Notifications
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
        - name: channel_id
          in: query
          schema:
            type: integer
            format: int64
        - name: status
          in: query
          schema:
            $ref: "./components/schemas.yaml#/NotificationDeliveryStatus"
        - name: event_type
          in: query
          schema:
            type: string
        - name: since
          in: query
          schema:
            type: string
            format: date-time
      responses:
        "200":
          description: List of deliveries
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListNotificationDeliveriesResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-deliveries/dead:
    get:
      operationId: listDeadLetters
      summary: List dead letters
      description: Lists deliveries that failed permanently.
      tags:
        - Notifications
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
      responses:
        "200":
          description: List of dead letters
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListNotificationDeliveriesResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /notification-deliveries/{id}/retry:
    post:
      operationId: retryDeadLetter
      summary: Retry a dead letter
      description: Resets a dead letter delivery to pending for retry.
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Delivery reset for retry
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/NotificationDelivery"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/{id}/deliveries:
    get:
      operationId: listAlertDeliveries
      summary: List deliveries for an alert
      tags:
        - Notifications
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
      responses:
        "200":
          description: List of deliveries
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListNotificationDeliveriesResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /alerts/{id}/actions:
    get:
      operationId: listAlertActions
      summary: List audit trail entries for an alert
      tags:
        - Alerts
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
      responses:
        "200":
          description: List of audit trail entries
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListAuditTrailResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /dropdowns/notification-channels:
    get:
      operationId: listNotificationChannelsDropdown
      summary: List channels for dropdown selection
      tags:
        - Dropdowns
      responses:
        "200":
          description: Channels list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "./components/schemas.yaml#/NotificationChannelDropdownItem"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  # Feedback
  /feedback:
    post:
      operationId: submitFeedback
      summary: Submit user feedback
      description: Submits feedback from the authenticated user.
      tags:
        - Feedback
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateFeedbackRequest"
      responses:
        "201":
          description: Feedback submitted successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/CreateFeedbackResponse"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  # API Key management
  /api-keys:
    get:
      operationId: listAPIKeys
      summary: List API keys
      description: Lists all non-system API keys for the authenticated organization.
      tags:
        - APIKeys
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
      responses:
        "200":
          description: List of API keys
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListAPIKeysResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    post:
      operationId: createAPIKey
      summary: Create an API key
      description: |
        Creates a new API key for the authenticated organization.
        The plaintext key is returned only once in the response.
        Requires JWT authentication (Supabase login).
      tags:
        - APIKeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateAPIKeyRequest"
      responses:
        "201":
          description: API key created successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/CreateAPIKeyResponse"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /api-keys/{id}:
    get:
      operationId: getAPIKey
      summary: Get an API key
      description: Gets details of a single API key (never includes the secret).
      tags:
        - APIKeys
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: API key details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/APIKey"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateAPIKey
      summary: Update an API key
      description: Updates the name and/or description of an API key.
      tags:
        - APIKeys
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateAPIKeyRequest"
      responses:
        "200":
          description: Updated API key
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/APIKey"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /api-keys/{id}/toggle:
    post:
      operationId: toggleAPIKey
      summary: Toggle API key active state
      description: Toggles an API key between active and inactive states.
      tags:
        - APIKeys
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: Toggled API key
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/APIKey"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /api-keys/{id}/deactivate:
    post:
      operationId: deactivateAPIKey
      summary: Permanently deactivate an API key
      description: Permanently deactivates an API key. This action cannot be undone.
      tags:
        - APIKeys
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "204":
          description: API key deactivated
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

components:
  securitySchemes:
    apiKey:
      $ref: "./components/securitySchemes.yaml#/apiKey"

  parameters:
    JobId:
      $ref: "./components/parameters.yaml#/JobId"
    Limit:
      $ref: "./components/parameters.yaml#/Limit"
    Offset:
      $ref: "./components/parameters.yaml#/Offset"
    SortOrder:
      $ref: "./components/parameters.yaml#/SortOrder"

  responses:
    BadRequest:
      $ref: "./components/responses.yaml#/BadRequest"
    Unauthorized:
      $ref: "./components/responses.yaml#/Unauthorized"
    NotFound:
      $ref: "./components/responses.yaml#/NotFound"
    RateLimited:
      $ref: "./components/responses.yaml#/RateLimited"
    InternalError:
      $ref: "./components/responses.yaml#/InternalError"

tags:
  - name: Jobs
    description: Gather and scrape job management
  - name: HelmSync
    description: Helm repository synchronization jobs
  - name: Releases
    description: Upstream release information
  - name: Versions
    description: Discovered version snapshots
  - name: Rules
    description: Monitoring rule management
  - name: Alerts
    description: Alert management
  - name: AlertConfigs
    description: Alert configuration management
  - name: Notifications
    description: Notification channel and rule management
  - name: Dropdowns
    description: Dropdown data for UI forms
  - name: Settings
    description: Organization settings management
  - name: Agents
    description: Agent registration and status
  - name: APIKeys
    description: API key management
  - name: Feedback
    description: User feedback submission
  - name: Utilities
    description: Utility endpoints