openapi: 3.0.3
info:
  title: Planekeeper Shared API Components
  description: Shared paths used by both client and internal APIs
  version: v1

paths:
  /gather-jobs:
    get:
      operationId: listGatherJobs
      summary: List gather jobs
      description: |
        Lists gather jobs with optional scope filtering and search.
        Scope can be 'org' (organization only), 'global' (global only), or 'all' (both).
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
        - $ref: "./components/parameters.yaml#/Scope"
        - name: search
          in: query
          description: Search by name or artifact name
          schema:
            type: string
        - name: status
          in: query
          description: Filter by job status
          schema:
            $ref: "./components/schemas.yaml#/JobStatus"
      responses:
        "200":
          description: List of gather jobs
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListGatherJobsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "429":
          $ref: "./components/responses.yaml#/RateLimited"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    post:
      operationId: createGatherJob
      summary: Create a gather job
      description: |
        Creates a new gather job for the authenticated organization.
        The job will fetch release information from the specified upstream source.
      tags:
        - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateGatherJobRequest"
      responses:
        "201":
          description: Gather job created successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/GatherJob"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "429":
          $ref: "./components/responses.yaml#/RateLimited"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /gather-jobs/{id}:
    get:
      operationId: getGatherJob
      summary: Get a gather job by ID
      description: Retrieves a single gather job by its ID.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "200":
          description: Gather job details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/GatherJob"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateGatherJob
      summary: Update a gather job
      description: Updates an existing gather job.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateGatherJobRequest"
      responses:
        "200":
          description: Gather job updated successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/GatherJob"
        "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: deleteGatherJob
      summary: Delete a gather job
      description: Deletes a gather job and all associated upstream releases.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "204":
          description: Gather job deleted successfully
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /gather-jobs/{id}/run:
    post:
      operationId: triggerGatherJob
      summary: Trigger a gather job to run immediately
      description: |
        Triggers a gather job to run immediately by setting its status to pending
        and next_run_at to now.
      tags:
        - Jobs
      parameters:
        - name: id
          in: path
          required: true
          description: The gather job ID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 123
      responses:
        "200":
          description: Job triggered successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/TriggerJobResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /gather-jobs/{id}/clear-releases:
    post:
      operationId: clearGatherJobReleases
      summary: Clear all releases for a gather job
      description: |
        Deletes all upstream releases associated with a gather job without deleting the job itself.
        Useful when job configuration has changed and you want to start fresh.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "204":
          description: Releases cleared successfully
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /gather-jobs/summary:
    get:
      operationId: getGatherJobsSummary
      summary: Get gather jobs summary
      description: Returns aggregate counts of gather jobs by status.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/Scope"
      responses:
        "200":
          description: Gather jobs summary
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/GatherJobsSummary"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /scrape-jobs/summary:
    get:
      operationId: getScrapeJobsSummary
      summary: Get scrape jobs summary
      description: Returns aggregate counts for scrape jobs.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/Scope"
      responses:
        "200":
          description: Scrape jobs summary
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ScrapeJobsSummary"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /scrape-jobs:
    get:
      operationId: listScrapeJobs
      summary: List scrape jobs
      description: Lists all scrape jobs for the authenticated organization with pagination.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
        - name: status
          in: query
          description: Filter by job status
          schema:
            $ref: "./components/schemas.yaml#/JobStatus"
      responses:
        "200":
          description: List of scrape jobs
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListScrapeJobsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "429":
          $ref: "./components/responses.yaml#/RateLimited"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    post:
      operationId: createScrapeJob
      summary: Create a scrape job
      description: |
        Creates a new scrape job for the authenticated organization.
        The job will clone the specified repository, read the target file,
        and extract version information using the configured parser.
      tags:
        - Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateScrapeJobRequest"
      responses:
        "201":
          description: Scrape job created successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ScrapeJob"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "429":
          $ref: "./components/responses.yaml#/RateLimited"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /scrape-jobs/{id}:
    get:
      operationId: getScrapeJob
      summary: Get a scrape job by ID
      description: Retrieves a single scrape job by its ID.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "200":
          description: Scrape job details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ScrapeJob"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateScrapeJob
      summary: Update a scrape job
      description: Updates an existing scrape job.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateScrapeJobRequest"
      responses:
        "200":
          description: Scrape job updated successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ScrapeJob"
        "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: deleteScrapeJob
      summary: Delete a scrape job
      description: Deletes a scrape job and all associated version snapshots.
      tags:
        - Jobs
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "204":
          description: Scrape job deleted successfully
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /scrape-jobs/{id}/versions:
    get:
      operationId: getVersionHistory
      summary: Get version history for a scrape job
      description: |
        Returns the version history for a specific scrape job,
        ordered by most recent first.
      tags:
        - Jobs
      parameters:
        - name: id
          in: path
          required: true
          description: The scrape job ID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 123
        - name: limit
          in: query
          description: Maximum number of versions to return (default 10, max 20)
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 20
            default: 10
      responses:
        "200":
          description: Version history
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/VersionHistoryResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /scrape-jobs/{id}/run:
    post:
      operationId: triggerScrapeJob
      summary: Trigger a scrape job to run immediately
      description: |
        Triggers a scrape job to run immediately by setting its status to pending
        and next_run_at to now.
      tags:
        - Jobs
      parameters:
        - name: id
          in: path
          required: true
          description: The scrape job ID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 123
      responses:
        "200":
          description: Job triggered successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/TriggerJobResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /scrape-jobs/{id}/set-version:
    post:
      operationId: setManualVersion
      summary: Set version for a manual scrape job
      description: |
        Sets the deployed version for a manual scrape job. This creates a version
        snapshot and triggers rule evaluation. Only valid for scrape jobs with
        parse_type 'manual'.
      tags:
        - Jobs
      parameters:
        - name: id
          in: path
          required: true
          description: The scrape job ID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 123
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/SetManualVersionRequest"
      responses:
        "200":
          description: Version set successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/VersionSnapshot"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /helm-sync-jobs:
    get:
      operationId: listHelmSyncJobs
      summary: List helm sync jobs
      description: |
        Lists helm sync jobs with optional scope filtering and search.
        Scope can be 'org' (organization only), 'global' (global only), or 'all' (both).
      tags:
        - HelmSync
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
        - $ref: "./components/parameters.yaml#/Scope"
        - name: search
          in: query
          description: Search by name or repository URL
          schema:
            type: string
        - name: status
          in: query
          description: Filter by job status
          schema:
            $ref: "./components/schemas.yaml#/JobStatus"
      responses:
        "200":
          description: List of helm sync jobs
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListHelmSyncJobsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "429":
          $ref: "./components/responses.yaml#/RateLimited"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    post:
      operationId: createHelmSyncJob
      summary: Create a helm sync job
      description: |
        Creates a new helm sync job that will discover charts in a Helm repository
        and create gather jobs for each discovered chart.
      tags:
        - HelmSync
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/CreateHelmSyncJobRequest"
      responses:
        "201":
          description: Helm sync job created successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/HelmSyncJob"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "429":
          $ref: "./components/responses.yaml#/RateLimited"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /helm-sync-jobs/{id}:
    get:
      operationId: getHelmSyncJob
      summary: Get a helm sync job by ID
      description: Retrieves a single helm sync job by its ID.
      tags:
        - HelmSync
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "200":
          description: Helm sync job details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/HelmSyncJob"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"
    put:
      operationId: updateHelmSyncJob
      summary: Update a helm sync job
      description: Updates an existing helm sync job.
      tags:
        - HelmSync
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/UpdateHelmSyncJobRequest"
      responses:
        "200":
          description: Helm sync job updated successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/HelmSyncJob"
        "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: deleteHelmSyncJob
      summary: Delete a helm sync job
      description: |
        Deletes a helm sync job. Child gather jobs will have their parent reference cleared
        but will not be deleted.
      tags:
        - HelmSync
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "204":
          description: Helm sync job deleted successfully
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /helm-sync-jobs/{id}/run:
    post:
      operationId: triggerHelmSyncJob
      summary: Trigger a helm sync job to run immediately
      description: |
        Triggers a helm sync job to run immediately by setting its status to pending
        and next_run_at to now.
      tags:
        - HelmSync
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "200":
          description: Job triggered successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/TriggerJobResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /helm-sync-jobs/{id}/charts:
    get:
      operationId: listHelmSyncJobCharts
      summary: List gather jobs created by this sync job
      description: Returns all gather jobs that were created by this helm sync job.
      tags:
        - HelmSync
      parameters:
        - $ref: "./components/parameters.yaml#/JobId"
      responses:
        "200":
          description: List of child gather jobs
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/HelmSyncChildJobsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /releases:
    get:
      operationId: listReleases
      summary: List upstream releases
      description: |
        Lists all upstream releases for the authenticated organization with pagination.
        Optionally filter by artifact name.
      tags:
        - Releases
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
        - $ref: "./components/parameters.yaml#/SortOrder"
        - $ref: "./components/parameters.yaml#/Scope"
        - name: artifact_name
          in: query
          description: Filter releases by artifact name
          schema:
            type: string
            example: kubernetes/kubernetes
        - name: include_prerelease
          in: query
          description: Whether to include prerelease versions (default false, only stable releases)
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: List of releases
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListReleasesResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "429":
          $ref: "./components/responses.yaml#/RateLimited"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /releases/{id}:
    get:
      operationId: getReleaseById
      summary: Get a release by ID
      description: Retrieves a single upstream release by its ID.
      tags:
        - Releases
      parameters:
        - name: id
          in: path
          required: true
          description: The release ID
          schema:
            type: integer
            format: int64
            minimum: 1
            example: 456
      responses:
        "200":
          description: Release details
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/UpstreamRelease"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "404":
          $ref: "./components/responses.yaml#/NotFound"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /releases/summary:
    get:
      operationId: getReleasesSummary
      summary: Get releases summary
      description: |
        Returns aggregate statistics for releases including counts, unique artifacts,
        and artifact names for autocomplete.
      tags:
        - Releases
      parameters:
        - $ref: "./components/parameters.yaml#/Scope"
        - name: include_prerelease
          in: query
          description: Whether to include prerelease versions in counts (default false)
          schema:
            type: boolean
            default: false
      responses:
        "200":
          description: Releases summary
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ReleasesSummary"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /versions:
    get:
      operationId: listVersionSnapshots
      summary: List version snapshots
      description: |
        Lists all version snapshots for the authenticated organization with pagination.
        Optionally filter by repository URL.
      tags:
        - Versions
      parameters:
        - $ref: "./components/parameters.yaml#/Limit"
        - $ref: "./components/parameters.yaml#/Offset"
        - name: repository_url
          in: query
          description: Filter version snapshots by repository URL
          schema:
            type: string
            example: https://github.com/helm/charts
      responses:
        "200":
          description: List of version snapshots
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListVersionSnapshotsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "429":
          $ref: "./components/responses.yaml#/RateLimited"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /settings:
    get:
      operationId: listSettings
      summary: List all settings
      description: Lists all system settings with their current values.
      tags:
        - Settings
      responses:
        "200":
          description: List of settings
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListSettingsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /agents:
    get:
      operationId: listAgents
      summary: List registered agents
      description: |
        Lists all registered agent service instances with their metadata,
        including capabilities and available credentials.
      tags:
        - Agents
      responses:
        "200":
          description: List of agents
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListAgentsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /agents/{agent_uuid}/submission-logs:
    get:
      operationId: listAgentSubmissionLogs
      summary: List submission logs for an agent
      description: |
        Returns recent submission logs for a specific agent, useful for debugging
        task completion and failure tracking.
      tags:
        - Agents
      parameters:
        - name: agent_uuid
          in: path
          required: true
          description: The agent's UUID
          schema:
            type: string
            format: uuid
        - name: limit
          in: query
          description: Maximum number of logs to return (default 20, max 100)
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: List of submission logs
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ListAgentSubmissionLogsResponse"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /validate/regex:
    post:
      operationId: validateRegex
      summary: Validate a regex pattern
      description: |
        Validates that a regex pattern can be compiled.
        Returns whether the pattern is valid and any error message if invalid.
      tags:
        - Utilities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "./components/schemas.yaml#/ValidateRegexRequest"
      responses:
        "200":
          description: Validation result
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ValidateRegexResponse"
        "400":
          $ref: "./components/responses.yaml#/BadRequest"
        "401":
          $ref: "./components/responses.yaml#/Unauthorized"
        "500":
          $ref: "./components/responses.yaml#/InternalError"

  /webhooks/acknowledge/{token}:
    post:
      operationId: acknowledgeViaWebhook
      summary: Acknowledge alert via webhook callback
      description: |
        Allows external systems to acknowledge alerts via a webhook callback URL.
        The token is included in webhook notification payloads and is valid for 24 hours.
        No authentication required - the token serves as the credential.
      tags:
        - Webhooks
      security: []
      parameters:
        - name: token
          in: path
          required: true
          description: Acknowledgment token from the webhook payload
          schema:
            type: string
            minLength: 64
            maxLength: 64
      responses:
        "200":
          description: Alert acknowledged successfully
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/WebhookAcknowledgeResponse"
        "400":
          description: Token expired or already used
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ErrorResponse"
        "404":
          description: Token not found
          content:
            application/json:
              schema:
                $ref: "./components/schemas.yaml#/ErrorResponse"
        "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"
    Scope:
      $ref: "./components/parameters.yaml#/Scope"

  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: Settings
    description: System settings
  - name: Agents
    description: Agent registration and status
  - name: Utilities
    description: Utility endpoints
  - name: Webhooks
    description: Webhook callback endpoints (no auth required)