openapi-ci-api.yaml

openapi: 3.0.3
info:
  title: CCExtractor CI System API
  version: 1.2.0
  description: |
    Security-hardened JSON-only REST API for the CCExtractor CI/sample platform.
    Designed for AI agents and CI automation. Enforces scoped Bearer token auth,
    strict input validation, rate limiting on all routes, and safe defaults
    throughout. No browser sessions, no HTML, no implicit permissions.

    **Authentication:** All endpoints require bearer token authentication unless
    explicitly marked with `security: []` (only /system/health and POST /auth/tokens).

    **Rate-limit headers:** Every response includes `X-RateLimit-Limit`,
    `X-RateLimit-Remaining`, and `X-RateLimit-Reset` headers. These are modeled
    explicitly on the 429 response for brevity; they are present on all responses
    regardless of status code.

  contact:
    name: CCExtractor Development
    url: https://github.com/CCExtractor/sample-platform
  license:
    name: GPL-3.0-only
    url: https://www.gnu.org/licenses/gpl-3.0.html

servers:
  - url: http://localhost:5000/api/v1
    description: Local development server
  - url: https://sampleplatform.ccextractor.org/api/v1
    description: Production

#
# Global security: all endpoints require auth
# unless explicitly overridden with security: []
#
security:
  - bearerAuth: []

tags:
  - name: Auth
    description: Token issuance and revocation
  - name: Runs
    description: CI run lifecycle — list, inspect, trigger, and cancel
  - name: Samples
    description: Media samples and regression test definitions
  - name: Results
    description: Per-sample output, diffs, and baseline management
  - name: Errors and Logs
    description: Structured errors and raw log access
  - name: System
    description: Health, queue, and artifacts
  - name: Users
    description: Platform accounts and role administration

#
# SECURITY NOTES (implementers must read)
#
# 1. AUTH MODEL
#    - All tokens are opaque, server-side. Never expose session cookies via API.
#    - The CI worker token (/ci/progress-reporter) is a separate secret and is
#      NOT valid for user-facing API endpoints.
#    - Token creation is rate-limited to 5 req/15 min per IP to prevent
#      credential stuffing.
#
# 2. SCOPE ENFORCEMENT
#    - Scope checks happen at the middleware layer before route handlers.
#    - x-required-scope on each operation defines the minimum scope needed.
#    - Missing scope → 403 Forbidden (not 401, token is valid but insufficient).
#
# 3. INPUT VALIDATION
#    - additionalProperties: false on all request bodies (no mass-assignment).
#    - Regex patterns on all free-text IDs (commit_sha, sha256, repository).
#    - maxLength on every string field. maxItems on every array.
#    - Integer IDs have minimum: 1 (no zero or negative IDs).
#
# 4. OUTPUT SAFETY
#    - got=null in TestResultFile means match, not missing output.
#      The dummy row (-1,-1,-1,'','error') is translated server-side to
#      status=missing_output and never surfaced as a real object.
#    - test.failed reflects cancellation only; fail_count is computed from
#      TestResult rows. Do not expose test.failed directly.
#    - Stack traces in infrastructure errors are opt-in (include_stack=false
#      by default) to avoid leaking internal paths.
#
# 5. STORAGE
#    - Artifacts may exist in local SAMPLE_REPOSITORY, GCS, or both.
#    - storage_status=degraded means one backend only; missing means neither.
#    - Never return a download_url that has not been verified to exist.
#    - Log endpoints return 404 (not a broken download link) when the log
#      file is absent from both storage backends.
#
# 6. RATE LIMITING (all routes)
#    - Default: 120 req/min per token (reads), 20 req/min per token (writes).
#    - Auth endpoint: 5 req/15 min per IP.
#    - Every response includes X-RateLimit-Limit, X-RateLimit-Remaining,
#      X-RateLimit-Reset headers.
#    - 429 response includes Retry-After header (seconds).
#
# 7. IDEMPOTENCY
#    - POST /runs/{run_id}/cancel is idempotent; canceling an already-canceled
#      run returns 202 with status=accepted and a no-op message.
#
# 8. DIFF ACCESS
#    - The diff route is header-gated on the legacy system (not role-gated).
#      The API wraps the XHR path and returns structured JSON. No HTML.
#
# 9. STATUS DERIVATION
#    - Run status is derived, not stored. TestStatus has only: preparation,
#      testing, completed, canceled (canceled covers both canceled and error).
#      The API normalizes this to the 7-value enum below.
#    - RunSample.status is computed from TestResult + TestResultFile +
#      expected exit code + multiple acceptable baselines.
#    - fail_count and missing_output_count in RunSummary are mutually
#      exclusive. A sample appears in exactly one bucket (missing_output
#      is checked first; if the dummy sentinel row is detected the function
#      returns immediately without evaluating fail conditions).
#
# 10. REPOSITORY PERMISSIONS
#    - POST /runs enforces a repo-aware permission check. Triggering a run
#      against the main configured repository (GITHUB_OWNER/GITHUB_REPOSITORY)
#      requires the contributor role or above. Any authenticated user with
#      runs:write scope may trigger runs against fork repositories. There is
#      no global repository allowlist; the elevated-role check applies only
#      to the main configured repository.
#

paths:

  # AUTH

  /auth/tokens:
    get:
      tags: [Auth]
      summary: List API tokens
      operationId: listTokens
      description: >
        Lists tokens for the authenticated user. Non-admin users see only their
        own tokens. Admins may append ?all=true to list tokens across the entire
        system; non-admin callers sending ?all=true receive 403.

        Plaintext token values are never included in list responses.
      security:
        - bearerAuth: []
      x-required-scope: tokens:manage
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: all
          in: query
          schema:
            type: boolean
          description: >
            Admin only. Set to true to list tokens for all users in the system.
            Non-admin callers receive 403 if this parameter is present and true.
      responses:
        "200":
          description: Paginated list of tokens (without plaintext secrets).
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ApiTokenItem"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    post:
      tags: [Auth]
      summary: Create an API token
      operationId: createToken
      description: >
        Rate-limited to 5 requests per 15 minutes per IP. Tokens are opaque
        and stored server-side. Scopes are additive; request only what you need.
        Tokens expire after expires_in_days (default 7, max 30).
      security: []
      x-rate-limit: "5/15min per IP"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TokenCreateRequest"
      responses:
        "201":
          description: Token created. Store the token value; it will not be shown again.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AuthToken"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: invalid_credentials
                message: Email or password is incorrect.
                details: {}
        "403":
          description: >
            Authenticated caller tried to create a token with higher scopes
            than their current token.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: forbidden
                message: Cannot create token with scopes you do not possess.
                details: {}
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /auth/tokens/current:
    delete:
      tags: [Auth]
      summary: Revoke the current API token
      operationId: revokeCurrentToken
      description: >
        Immediately invalidates the token used in the Authorization header.
        Subsequent requests with the same token will receive 401.

        No specific scope is required beyond authentication — any valid token
        can self-revoke. This is the preferred way to clean up a token when
        you have it in hand but do not know its numeric ID.
      security:
        - bearerAuth: []
      responses:
        "204":
          description: Token revoked
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /auth/tokens/{token_id}:
    delete:
      tags: [Auth]
      summary: Revoke a specific API token by ID
      operationId: revokeToken
      description: >
        Revokes the token identified by token_id.
        Any authenticated caller may revoke their own tokens (no scope required).
        Admins may revoke any user's token.
        A non-admin attempting to revoke a token they do not own receives 404
        to prevent token-ID enumeration.

        To revoke the token currently in use without knowing its ID, use
        DELETE /auth/tokens/current instead.
      security:
        - bearerAuth: []
      parameters:
        - name: token_id
          in: path
          required: true
          schema:
            type: integer
            minimum: 1
      responses:
        "204":
          description: Token revoked successfully.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: >
            Token not found. Non-admin users attempting to revoke another user's token receive a uniform 404 response to prevent token-ID enumeration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: not_found
                message: Token not found.
                details: {}
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /auth/signup:
    post:
      tags: [Auth]
      summary: Send a registration link to an email address
      operationId: signup
      description: >
        Answers the same way whether or not the address is already
        registered, because a different reply would tell an anonymous caller
        who has an account. The link lands on the classic completion page,
        which is where the account is actually created. Unauthenticated and
        limited to 5 requests per 15 minutes per IP.
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
      responses:
        "202":
          description: Accepted; an email has been sent if appropriate
          content:
            application/json:
              schema:
                type: object
                properties:
                  sent:
                    type: boolean
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /auth/password-reset:
    post:
      tags: [Auth]
      summary: Send a password reset link
      operationId: requestPasswordReset
      description: >
        Silent about whether the address is registered, for the same reason
        signup is. Unauthenticated and limited per IP.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email:
                  type: string
                  format: email
      responses:
        "202":
          description: Accepted; an email has been sent if appropriate
          content:
            application/json:
              schema:
                type: object
                properties:
                  sent:
                    type: boolean
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /auth/password-reset/complete:
    post:
      tags: [Auth]
      summary: Set a new password using a link from the reset email
      operationId: completePasswordReset
      description: >
        The signature covers the current password hash, so a link stops
        working the moment it is used or the password changes by any other
        route. Expired, unknown and forged links share one reply.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [user_id, expires, mac, password]
              properties:
                user_id:
                  type: integer
                  minimum: 1
                expires:
                  type: integer
                mac:
                  type: string
                  maxLength: 128
                password:
                  type: string
      responses:
        "200":
          description: Password changed
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                  password_changed:
                    type: boolean
        "400":
          $ref: "#/components/responses/BadRequest"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /auth/me:
    get:
      tags: [Auth]
      summary: Identify the account behind the current token
      operationId: getCurrentUser
      description: >
        A token does not carry the account's role, so a client cannot infer
        what the caller is allowed to do. Clients gate their interface on
        this instead of guessing, and the granted scopes are echoed so a
        client can also hide what this token could never call. Requires no
        particular scope: it reports on the caller and discloses nothing
        another endpoint would withhold.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: The authenticated account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CurrentUser"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  # RUNS
    patch:
      tags: [Auth]
      summary: Change your own name, email or password
      operationId: updateAccount
      description: >
        Touching the email or the password needs the current one as well:
        the bearer token proves the request came from a signed-in session,
        not that the sender knows the account's own credentials.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  maxLength: 50
                email:
                  type: string
                  format: email
                new_password:
                  type: string
                current_password:
                  type: string
      responses:
        "200":
          description: Account updated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatformUser"
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"


  /runs:
    get:
      tags: [Runs]
      summary: List CI runs
      operationId: listRuns
      description: >
        The underlying table is capped at the 50 most recent runs
        in the current implementation; this endpoint adds full pagination.
        Sorted by -created_at by default (newest first).
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/RunStatus"
        - $ref: "#/components/parameters/Branch"
        - $ref: "#/components/parameters/CommitSha"
        - name: ccx_version
          in: query
          description: >
            Filter to the commit a CCExtractor release was cut from.
          schema:
            type: string
            maxLength: 10
        - $ref: "#/components/parameters/Repository"
        - $ref: "#/components/parameters/Platform"
        - $ref: "#/components/parameters/CreatedAfter"
        - $ref: "#/components/parameters/CreatedBefore"
        - name: sort
          in: query
          schema:
            type: string
            default: -created_at
            enum: [created_at, -created_at, run_id, -run_id]
          description: Sort field. Prefix with - for descending order.
      responses:
        "200":
          description: Paginated runs
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Run"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    post:
      tags: [Runs]
      summary: Trigger a new CI run
      operationId: createRun
      description: >
        Requires runs:write scope and contributor role or above.
        The regression_test_ids set is validated against active tests only.
        If omitted, all active regression tests are used.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin, tester, contributor]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunCreateRequest"
      responses:
        "202":
          description: Run queued. Poll /runs/{run_id}/progress for status.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/UnprocessableEntity"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}:
    get:
      tags: [Runs]
      summary: Get a CI run
      operationId: getRun
      description: >
        Returns normalized run status derived from TestProgress rows.
        status=canceled covers both explicit cancellation and infrastructure
        errors (the underlying model does not distinguish them).
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Run details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/summary:
    get:
      tags: [Runs]
      summary: Get pass/fail summary for a run
      operationId: getRunSummary
      description: >
        fail_count is computed from TestResult rows, not from test.failed.
        test.failed only reflects whether the final progress status is
        canceled — it does not reflect regression test outcomes.
        Use this endpoint, not test.failed, to triage a run.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Run summary
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunSummary"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/progress:
    get:
      tags: [Runs]
      summary: Get progress events for a run
      operationId: getRunProgress
      description: >
        Progress events are sourced from TestProgress rows written by the CI
        worker via /ci/progress-reporter. Messages are unstructured text.
        Structured error types are aspirational until the worker protocol
        emits structured JSON.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: status
          in: query
          schema:
            type: string
            enum: [queued, preparation, testing, completed, canceled]
      responses:
        "200":
          description: Paginated progress events
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ProgressEvent"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/restart:
    post:
      tags: [Runs]
      summary: Queue a finished or stuck run to be executed again
      operationId: restartRun
      description: >
        Clears the run's results and progress trail, which is what makes CI
        pick it up again. The run keeps its id, so existing links stay valid,
        and the old results are replaced rather than kept alongside the new
        ones. Requires runs:write scope.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin, tester, contributor]
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "202":
          description: Restart accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunActionResult"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/cancel:
    post:
      tags: [Runs]
      summary: Cancel a queued or running CI run
      operationId: cancelRun
      description: >
        Idempotent. Canceling an already-canceled or completed run returns
        202 with a no-op message rather than an error.
        Requires runs:write scope.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin, tester, contributor]
      parameters:
        - $ref: "#/components/parameters/RunId"
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  minLength: 5
                  maxLength: 255
                  description: >
                    Reason for cancellation, stored in the audit log.
              additionalProperties: false
      responses:
        "202":
          description: Cancellation accepted (or no-op if already terminal)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunActionResult"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/config:
    get:
      tags: [Runs]
      summary: Get run configuration and test matrix
      operationId: getRunConfig
      description: >
        regression_test_ids lists IDs included in this run. When no custom
        set was configured, all regression tests are returned.
        Implementers must filter by active=true explicitly.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RunId"
      responses:
        "200":
          description: Run configuration
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunConfig"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  # SAMPLES

  /runs/{run_id}/samples:
    get:
      tags: [Samples]
      summary: List regression test results in a run
      operationId: listRunSamples
      description: >
        Returns one entry per regression test result, not one per unique media
        file. A single media sample may yield multiple entries if it has
        multiple regression tests (different command flags).
        sample_progress in the legacy JSON endpoint is len(test.results) over
        total regression tests; it does not reflect multi-output completeness.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: status
          in: query
          schema:
            type: string
            enum: [pass, fail, skipped, missing_output, running, not_started]
        - name: name
          in: query
          schema:
            type: string
            maxLength: 100
        - name: tag
          in: query
          schema:
            type: string
            maxLength: 50
        - name: category
          in: query
          schema:
            type: string
            maxLength: 50
      responses:
        "200":
          description: Paginated regression test results
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/RunSample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/samples/{regression_test_id}:
    get:
      tags: [Samples]
      summary: Get full details for a regression test result in a run
      operationId: getRunSample
      description: >
        Returns the result for a specific regression test within a run.
        Note: the path parameter is regression_test_id, not a media sample ID.
        A single media sample may have multiple regression tests.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/RegressionTestId"
      responses:
        "200":
          description: Regression test result details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunSample"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples:
    get:
      tags: [Samples]
      summary: List all known media samples
      operationId: listSamples
      description: >
        Returns paginated media sample metadata. Samples are the original
        media files uploaded for regression testing.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: status
          in: query
          description: >
            Derived from linked regression tests. The sample table itself has
            no quarantine state; active/inactive reflects whether any active
            regression tests reference the sample.
          schema:
            type: string
            enum: [active, inactive]
        - name: name
          in: query
          schema:
            type: string
            maxLength: 100
        - name: tag
          in: query
          schema:
            type: string
            maxLength: 50
        - name: sha256
          in: query
          schema:
            type: string
            pattern: '^[a-fA-F0-9]{64}$'
        - name: extension
          in: query
          schema:
            type: string
            maxLength: 10
            pattern: '^[a-zA-Z0-9]+$'
      responses:
        "200":
          description: Paginated media samples
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Sample"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples/{sample_id}:
    get:
      tags: [Samples]
      summary: Get media sample metadata
      operationId: getSample
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/SampleId"
      responses:
        "200":
          description: Media sample metadata
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sample"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    patch:
      tags: [Samples]
      summary: Edit a sample's tags and upload metadata
      operationId: updateSample
      description: >
        Notes, parameters, platform and version live on the upload row
        rather than the sample, so a sample that arrived without one (over
        FTP, or seeded directly) can only have its tags changed and asking
        for the rest returns 409. Tags are given by name.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin]
      parameters:
        - $ref: "#/components/parameters/SampleId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tags:
                  type: array
                  maxItems: 50
                  items:
                    type: string
                    maxLength: 64
                notes:
                  type: string
                  maxLength: 1024
                parameters:
                  type: string
                  maxLength: 1024
                platform:
                  type: string
                  enum: [linux, windows, mac, bsd]
                version:
                  type: string
                  maxLength: 10
      responses:
        "200":
          description: Sample updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  sample_id:
                    type: integer
                  tags:
                    type: array
                    items:
                      type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"
    delete:
      tags: [Samples]
      summary: Delete a sample, its extra files and its media info
      operationId: deleteSample
      description: >
        Refused while any regression test still points at the sample,
        because removing the media would leave those tests unable to run and
        their history describing a sample nobody can fetch.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin]
      parameters:
        - $ref: "#/components/parameters/SampleId"
      responses:
        "200":
          description: Sample deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  sample_id:
                    type: integer
                  deleted:
                    type: boolean
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples/{sample_id}/details:
    get:
      tags: [Samples]
      summary: Get the full detail payload for a media sample
      operationId: getSampleDetails
      description: >
        Extends the summary payload with the upload record, any extra files
        attached to the sample, and the parsed MediaInfo tree. Media info is
        best effort: a sample whose XML is missing or unparseable reports
        null rather than failing the response. Unlike the classic page this
        never regenerates the XML, because a GET must not write to the
        sample repository.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/SampleId"
      responses:
        "200":
          description: Full media sample detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SampleDetails"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples/{sample_id}/download:
    get:
      tags: [Samples]
      summary: Locate a sample's media file in storage
      operationId: downloadSample
      description: >
        Returns a signed URL rather than the bytes. Samples run to several
        gigabytes, so streaming one through the API would hold a worker for
        the length of the transfer. Where only the local copy exists there is
        no URL to hand out and storage_status reports that instead.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/SampleId"
      responses:
        "200":
          description: Where the sample file is stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StoredFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples/{sample_id}/history:
    get:
      tags: [Samples]
      summary: Get regression test result history for a sample across runs
      operationId: getSampleHistory
      description: >
        Use failure_signature for flake detection: a stable signature across
        multiple runs on different commits indicates a genuine regression,
        not infrastructure noise.


        Entries cover every regression test on the sample, newest run first,
        so limit counts rows rather than runs. Pass regression_test_id to
        follow one test, where limit then means that many runs of it.


        With status set, the filter runs over a bounded scan of recent
        results; pagination.truncated is true when the sample has more
        history than the scan covered, and total then undercounts.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/SampleId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - $ref: "#/components/parameters/RegressionTestIdFilter"
        - $ref: "#/components/parameters/SampleHistoryStatus"
        - $ref: "#/components/parameters/Branch"
        - $ref: "#/components/parameters/Platform"
        - $ref: "#/components/parameters/CreatedAfter"
        - $ref: "#/components/parameters/CreatedBefore"
      responses:
        "200":
          description: Paginated sample history
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/SampleHistoryEntry"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /regression-tests:
    get:
      tags: [Samples]
      summary: List regression test definitions
      operationId: listRegressionTests
      description: >
        The active filter must be applied explicitly. When no custom set is
        defined, all regression tests are returned — including inactive ones.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: active
          in: query
          schema:
            type: boolean
            default: true
        - name: category
          in: query
          schema:
            type: string
            maxLength: 50
        - name: tag
          in: query
          schema:
            type: string
            maxLength: 50
        - name: sample_id
          in: query
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Paginated regression test definitions
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/RegressionTest"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    post:
      tags: [Samples]
      summary: Create a regression test definition
      operationId: createRegressionTest
      description: >
        Admin or contributor only. The test is created inactive unless the
        body says otherwise, so it cannot join a CI suite before someone has
        seen the output it actually produces on a verification run. Every
        named category must already exist; an unknown name rejects the whole
        request rather than silently dropping it.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegressionTestCreateRequest"
      responses:
        "201":
          description: The created regression test
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegressionTest"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /categories:
    get:
      tags: [Samples]
      summary: List regression test categories
      operationId: listCategories
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Paginated categories, ordered by name
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Category"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    post:
      tags: [Samples]
      summary: Create a category
      operationId: createCategory
      description: Admin or contributor only. Names are unique.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CategoryCreateRequest"
      responses:
        "201":
          description: The created category
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Category"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /categories/{category_id}:
    patch:
      tags: [Samples]
      summary: Rename or re-describe a category
      operationId: updateCategory
      description: Admin or contributor only. An empty body is rejected.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      parameters:
        - $ref: "#/components/parameters/CategoryId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CategoryUpdateRequest"
      responses:
        "200":
          description: The updated category
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Category"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    delete:
      tags: [Samples]
      summary: Delete a category
      operationId: deleteCategory
      description: >
        Admin or contributor only. A category still attached to regression
        tests is refused with 409 and a count, because dropping it would
        change which tests a suite selection picks up. Detach the tests
        first by PATCHing their categories.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      parameters:
        - $ref: "#/components/parameters/CategoryId"
      responses:
        "200":
          description: The category was deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedResource"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /regression-tests/{regression_test_id}:
    get:
      tags: [Samples]
      summary: Get one regression test with its baselines
      operationId: getRegressionTest
      description: >
        Adds the expected outputs and the alternative hashes accepted as
        variants, which the list endpoint omits because they multiply the
        payload for every row.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RegressionTestId"
      responses:
        "200":
          description: Regression test detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegressionTestDetail"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    delete:
      tags: [Samples]
      summary: Delete a regression test
      operationId: deleteRegressionTest
      description: >
        Admin or contributor only. A test that has already run is refused
        with 409 and the number of results referencing it, because deleting
        it would erase evidence of past regressions. Retire such a test with
        PATCH active=false instead.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      parameters:
        - $ref: "#/components/parameters/RegressionTestId"
      responses:
        "200":
          description: The regression test was deleted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeletedResource"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    patch:
      tags: [Samples]
      summary: Update part of a regression test definition
      operationId: updateRegressionTest
      description: >
        Admin or contributor only. Only the fields present in the body are
        written, so two clients editing different fields cannot clobber each
        other. An empty body is rejected.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      parameters:
        - $ref: "#/components/parameters/RegressionTestId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RegressionTestUpdateRequest"
      responses:
        "200":
          description: The updated regression test
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RegressionTest"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /regression-tests/{regression_test_id}/outputs/{output_id}/download:
    get:
      tags: [Regression Tests]
      summary: Locate the baseline a regression test is expected to reproduce
      operationId: downloadRegressionTestOutput
      description: >
        Matches the output against its parent test, so an id belonging to a
        different test reads as absent rather than resolving.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RegressionTestId"
        - $ref: "#/components/parameters/OutputId"
      responses:
        "200":
          description: Where the baseline file is stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StoredFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /regression-tests/{regression_test_id}/outputs/{output_id}/variants/{variant_id}/download:
    get:
      tags: [Regression Tests]
      summary: Locate one of the alternative outputs accepted for a baseline
      operationId: downloadRegressionTestVariant
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/RegressionTestId"
        - $ref: "#/components/parameters/OutputId"
        - name: variant_id
          in: path
          required: true
          description: Id of the variant, from the test detail payload
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Where the variant file is stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StoredFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /regression-tests/{regression_test_id}/outputs/{output_id}/variants:
    post:
      tags: [Regression Tests]
      summary: Accept another output hash as correct for a baseline
      operationId: createRegressionTestVariant
      description: >
        A test can legitimately produce different bytes on different
        platforms or CCExtractor builds. Recording the hash here makes those
        runs pass without overwriting the baseline everyone else is compared
        against, which is what promoting to baseline would do.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin, contributor]
      parameters:
        - $ref: "#/components/parameters/RegressionTestId"
        - $ref: "#/components/parameters/OutputId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [hash]
              properties:
                hash:
                  type: string
                  maxLength: 128
                  pattern: '^[A-Za-z0-9]+$'
      responses:
        "201":
          description: Variant accepted
          content:
            application/json:
              schema:
                type: object
                required: [id, hash]
                properties:
                  id:
                    type: integer
                    minimum: 1
                  hash:
                    type: string
                    maxLength: 128
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /regression-tests/{regression_test_id}/outputs/{output_id}/variants/{variant_id}:
    delete:
      tags: [Regression Tests]
      summary: Stop accepting one alternative output for a baseline
      operationId: deleteRegressionTestVariant
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin, contributor]
      parameters:
        - $ref: "#/components/parameters/RegressionTestId"
        - $ref: "#/components/parameters/OutputId"
        - name: variant_id
          in: path
          required: true
          description: Id of the variant, from the test detail payload
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Variant removed
          content:
            application/json:
              schema:
                type: object
                required: [id, deleted]
                properties:
                  id:
                    type: integer
                  deleted:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples/{sample_id}/media-info/download:
    get:
      tags: [Samples]
      summary: Locate the MediaInfo XML written alongside a sample
      operationId: downloadSampleMediaInfo
      description: >
        The parsed tree is already on /samples/{sample_id}/details; this is
        for anyone who wants the original file MediaInfo produced.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/SampleId"
      responses:
        "200":
          description: Where the media info file is stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StoredFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples/{sample_id}/extra-files/{extra_id}/download:
    get:
      tags: [Samples]
      summary: Locate one of the files uploaded alongside a sample
      operationId: downloadSampleExtraFile
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/SampleId"
        - name: extra_id
          in: path
          required: true
          description: Id of the accompanying file, from the sample details payload
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Where the accompanying file is stored
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StoredFile"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples/{sample_id}/extra-files/{extra_id}:
    delete:
      tags: [Samples]
      summary: Delete one of the files uploaded alongside a sample
      operationId: deleteSampleExtraFile
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin]
      parameters:
        - $ref: "#/components/parameters/SampleId"
        - name: extra_id
          in: path
          required: true
          description: Id of the accompanying file, from the sample details payload
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Accompanying file deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  deleted:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /tags:
    get:
      tags: [Samples]
      summary: List the tags a sample can be labelled with
      operationId: listTags
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Paginated tags
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            name:
                              type: string
                            description:
                              type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"
    post:
      tags: [Samples]
      summary: Create a tag
      operationId: createTag
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      x-required-roles: [admin]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name:
                  type: string
                  maxLength: 64
                description:
                  type: string
                  maxLength: 1024
      responses:
        "201":
          description: Tag created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: string
                  description:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /system/about:
    get:
      tags: [System]
      summary: Report the versions this platform runs against
      operationId: systemAbout
      description: >
        The classic about page is static prose. The parts worth reading from
        a client are the CCExtractor release under test and the commit the
        platform itself was deployed from.
      security:
        - bearerAuth: []
      x-required-scope: system:read
      responses:
        "200":
          description: Platform and CCExtractor versions
          content:
            application/json:
              schema:
                type: object
                properties:
                  platform_commit:
                    type: string
                    nullable: true
                  ccextractor_version:
                    type: string
                    nullable: true
                  ccextractor_released:
                    type: string
                    nullable: true
                  last_tested_commit:
                    type: string
                    nullable: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /users/{user_id}/deactivate:
    post:
      tags: [Auth]
      summary: Anonymise an account and lock it out
      operationId: deactivateUser
      description: >
        The row stays so the uploads and runs it owns keep an author, which
        is why this scrubs the identity instead of deleting. Open to admins
        and to the account's owner. Scope-free for the same reason revoking
        your own token is: closing your own account cannot depend on
        tokens:manage, which no role below admin may hold.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          description: Account deactivated and its own tokens revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                  deactivated:
                    type: boolean
                  tokens_revoked:
                    type: integer
                    description: >
                      How many of the account's tokens were still live and
                      have now been revoked. Scrambling the password only
                      stops new ones being minted, so the ones already
                      issued are ended here as well.
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /samples/upload:
    post:
      tags: [Uploads]
      summary: Upload a media file into the queue
      operationId: uploadSample
      description: >
        Uploading and describing are two steps, as on the classic pages: the
        transfer is slow and the metadata needs a CCExtractor version the
        uploader may have to look up, so the bytes are banked first. The file
        is hashed as it is written, and content already in the library or the
        queue is refused with 409. Extension and mime type are checked
        against the forbidden lists.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "201":
          description: Upload queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  sha:
                    type: string
                  extension:
                    type: string
                  original_name:
                    type: string
                  user_id:
                    type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
        "413":
          description: File larger than the configured upload limit
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /queued-samples:
    get:
      tags: [Uploads]
      summary: List uploads waiting to be described
      operationId: listQueuedSamples
      description: >
        Admins see the whole queue; everyone else sees only their own
        uploads.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Paginated queued uploads
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                    type: object
                    properties:
                      id:
                        type: integer
                      sha:
                        type: string
                      extension:
                        type: string
                      original_name:
                        type: string
                      user_id:
                        type: integer
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /queued-samples/{queued_id}:
    get:
      tags: [Uploads]
      summary: Get one queued upload
      operationId: getQueuedSample
      description: >
        Someone else's upload reads as absent rather than forbidden, so an
        id cannot be used to find out what others have queued.
      security:
        - bearerAuth: []
      x-required-scope: runs:read
      parameters:
        - name: queued_id
          in: path
          required: true
          description: Id of the queued upload
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: The queued upload
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  sha:
                    type: string
                  extension:
                    type: string
                  original_name:
                    type: string
                  user_id:
                    type: integer
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"
    delete:
      tags: [Uploads]
      summary: Discard a queued upload
      operationId: deleteQueuedSample
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      parameters:
        - name: queued_id
          in: path
          required: true
          description: Id of the queued upload
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Queued upload discarded
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  deleted:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /queued-samples/{queued_id}/finalize:
    post:
      tags: [Uploads]
      summary: Turn a queued upload into a sample
      operationId: finalizeQueuedSample
      description: >
        The file only moves into TestFiles once the rows are committed, so a
        failure part way through leaves the upload in the queue to retry
        rather than a sample row pointing at a file that was never placed.
        Reporting the sample as a GitHub issue stays on the classic page.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      parameters:
        - name: queued_id
          in: path
          required: true
          description: Id of the queued upload
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [version, platform]
              properties:
                version:
                  type: string
                  maxLength: 10
                  description: CCExtractor release the sample was produced with
                platform:
                  type: string
                  enum: [linux, windows, mac, bsd]
                parameters:
                  type: string
                  maxLength: 1024
                notes:
                  type: string
                  maxLength: 1024
      responses:
        "201":
          description: Sample created from the upload
          content:
            application/json:
              schema:
                type: object
                properties:
                  sample_id:
                    type: integer
                  sha:
                    type: string
                  original_name:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /users/{user_id}/password-reset:
    post:
      tags: [Auth]
      summary: Send a reset link to another account, or to your own
      operationId: sendUserPasswordReset
      description: >
        Unlike the public /auth/password-reset this names an account rather
        than an address, so it says plainly when the id is unknown: the
        caller is already signed in and can list users anyway. Scope-free
        for the same reason deactivation is.
      security:
        - bearerAuth: []
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "202":
          description: Reset link sent
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                  sent:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /auth/me/github:
    get:
      tags: [Auth]
      summary: Whether your account is connected to GitHub
      operationId: getGithubLink
      description: >
        Connecting is a browser redirect, so this hands back the URL to send
        somebody to rather than performing it. Trading the code GitHub
        returns for a token stays on the classic callback, which already
        holds the client secret and the registered redirect. The stored
        token is never part of this response; the URL carries only the
        client id and the scope asked for, both of which are public.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: Connection status and where to start one
          content:
            application/json:
              schema:
                type: object
                properties:
                  linked:
                    type: boolean
                  github_login:
                    type: string
                    nullable: true
                  authorize_url:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"
    delete:
      tags: [Auth]
      summary: Forget this platform's copy of your GitHub connection
      operationId: unlinkGithub
      description: >
        Only ever the caller's own. This drops the token the platform
        holds; the authorisation itself is withdrawn from GitHub's own
        applications page, which is the only place that can really end it.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: The connection has been forgotten
          content:
            application/json:
              schema:
                type: object
                properties:
                  linked:
                    type: boolean
                  github_login:
                    type: string
                    nullable: true
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"
  /auth/me/ftp-credentials:
    get:
      tags: [Uploads]
      summary: Get your own FTP details for the ingest server
      operationId: getFtpCredentials
      description: >
        Created on first ask and stable afterwards. Only ever the caller's
        own: these are working credentials, so there is no version of this
        that reads someone else's. The password is stored in the clear by
        design, being random and unchangeable, so this is the only place it
        can come from.
      security:
        - bearerAuth: []
      responses:
        "200":
          description: FTP connection details
          content:
            application/json:
              schema:
                type: object
                properties:
                  host:
                    type: string
                  port:
                    type: string
                  username:
                    type: string
                  password:
                    type: string
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /queued-samples/{queued_id}/link:
    post:
      tags: [Uploads]
      summary: Attach a queued upload to an existing sample
      operationId: linkQueuedSample
      description: >
        For material that belongs with a sample without being one, such as a
        subtitle track to compare against. The classic page offered this but
        never carried it out: its confirm step checks permissions and then
        redirects without touching anything, so this is the behaviour it
        described rather than the behaviour it had.
      security:
        - bearerAuth: []
      x-required-scope: runs:write
      parameters:
        - name: queued_id
          in: path
          required: true
          description: Id of the queued upload
          schema:
            type: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sample_id]
              properties:
                sample_id:
                  type: integer
                  minimum: 1
      responses:
        "201":
          description: Upload attached as an extra file
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  sample_id:
                    type: integer
                  filename:
                    type: string
        "400":
          $ref: "#/components/responses/BadRequest"
        "409":
          $ref: "#/components/responses/Conflict"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  # PLATFORM CONFIGURATION

  /system/maintenance:
    get:
      tags: [System]
      summary: Report maintenance state for every platform
      operationId: getMaintenance
      description: >
        A platform that has never been put into maintenance is reported as
        disabled=false rather than omitted, so a client always receives one
        entry per platform. Keyed on platforms rather than the data
        collection envelope: the list comes from the platform enum, not a
        growable table, so there is nothing to paginate. Admin only, like
        the rest of the platform configuration.
      security:
        - bearerAuth: []
      x-required-scope: system:read
      responses:
        "200":
          description: Maintenance state per platform
          content:
            application/json:
              schema:
                type: object
                properties:
                  platforms:
                    type: array
                    items:
                      $ref: "#/components/schemas/MaintenanceState"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /system/maintenance/{platform}:
    patch:
      tags: [System]
      summary: Pause or resume CI for one platform
      operationId: updateMaintenance
      description: >
        Admin only. While a platform is disabled new runs still queue; they
        are simply not handed to a VM until it is resumed.
      security:
        - bearerAuth: []
      x-required-scope: system:write
      parameters:
        - $ref: "#/components/parameters/PlatformPath"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/MaintenanceUpdateRequest"
      responses:
        "200":
          description: The updated maintenance state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/MaintenanceState"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /system/blocked-users:
    get:
      tags: [System]
      summary: List GitHub accounts blocked from triggering CI runs
      operationId: listBlockedUsers
      description: >
        Admin only. The blocklist names GitHub accounts, so it is not
        readable with system:read alone.
      security:
        - bearerAuth: []
      x-required-scope: system:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Paginated blocked GitHub accounts
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/BlockedUser"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    post:
      tags: [System]
      summary: Block a GitHub account from triggering CI runs
      operationId: createBlockedUser
      description: >
        Admin only. Keyed on the numeric GitHub account id rather than the
        login, because a login can be changed and reused, which would
        silently unblock somebody.
      security:
        - bearerAuth: []
      x-required-scope: system:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BlockedUserCreateRequest"
      responses:
        "201":
          description: The account is now blocked
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BlockedUser"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /system/blocked-users/{user_id}:
    delete:
      tags: [System]
      summary: Unblock a GitHub account
      operationId: deleteBlockedUser
      description: Admin only.
      security:
        - bearerAuth: []
      x-required-scope: system:write
      parameters:
        - $ref: "#/components/parameters/BlockedUserId"
      responses:
        "200":
          description: The account is no longer blocked
          content:
            application/json:
              schema:
                type: object
                properties:
                  user_id:
                    type: integer
                  deleted:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /system/forbidden-extensions:
    get:
      tags: [System]
      summary: List file extensions rejected on upload
      operationId: listForbiddenExtensions
      description: Admin only, like the rest of the platform configuration.
      security:
        - bearerAuth: []
      x-required-scope: system:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Paginated forbidden extensions, without a leading dot
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          type: string
                          maxLength: 32
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

    post:
      tags: [System]
      summary: Forbid a file extension on upload
      operationId: createForbiddenExtension
      description: >
        Admin only. Stored lower-cased and without a leading dot, matching
        how upload validation looks it up.
      security:
        - bearerAuth: []
      x-required-scope: system:write
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ForbiddenExtensionCreateRequest"
      responses:
        "201":
          description: The extension is now forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  extension:
                    type: string
                    maxLength: 32
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "409":
          $ref: "#/components/responses/Conflict"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /system/forbidden-extensions/{extension}:
    delete:
      tags: [System]
      summary: Allow a file extension to be uploaded again
      operationId: deleteForbiddenExtension
      description: Admin only. A leading dot in the path is tolerated.
      security:
        - bearerAuth: []
      x-required-scope: system:write
      parameters:
        - $ref: "#/components/parameters/ExtensionPath"
      responses:
        "200":
          description: The extension is no longer forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  extension:
                    type: string
                    maxLength: 32
                  deleted:
                    type: boolean
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  # USERS

  /users:
    get:
      tags: [Users]
      summary: List platform users
      operationId: listUsers
      description: >
        Admin only. Paginated like every other collection here, because the
        platform has hundreds of accounts. Credentials and GitHub tokens are
        never included.
      security:
        - bearerAuth: []
      x-required-scope: tokens:manage
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
      responses:
        "200":
          description: Paginated platform users
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/PlatformUser"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /users/{user_id}:
    get:
      tags: [Auth]
      summary: Get one platform user
      operationId: getUser
      security:
        - bearerAuth: []
      x-required-scope: tokens:manage
      x-required-roles: [admin]
      parameters:
        - $ref: "#/components/parameters/UserId"
      responses:
        "200":
          description: The user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatformUser"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"
    patch:
      tags: [Users]
      summary: Change a user's role
      operationId: updateUserRole
      description: >
        Admin only. An admin cannot change their own role: demoting the last
        admin through this endpoint would leave nobody able to undo it, so
        that request is refused with 403.
      security:
        - bearerAuth: []
      x-required-scope: tokens:manage
      parameters:
        - $ref: "#/components/parameters/UserId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RoleUpdateRequest"
      responses:
        "200":
          description: The updated user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlatformUser"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: >
            The caller is not an admin, or attempted to change their own role.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: forbidden
                message: You cannot change your own role.
                details: {}
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  # RESULTS

  /runs/{run_id}/samples/{sample_id}/regression-tests/{regression_id}/outputs/{output_id}/expected:
    get:
      tags: [Results]
      summary: Get expected output for a regression test result
      operationId: getExpectedOutput
      description: >
        Expected output is a file reference stored under TestResults using the
        regression output extension. Resolved from GCS or local
        SAMPLE_REPOSITORY at request time. storage_status reflects which
        backends have the file. Do not assume local and GCS are always in sync.
      security:
        - bearerAuth: []
      x-required-scope: results:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/SampleId"
        - $ref: "#/components/parameters/RegressionId"
        - $ref: "#/components/parameters/OutputId"
        - $ref: "#/components/parameters/Format"
      responses:
        "200":
          description: Expected output file
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutputFile"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/samples/{sample_id}/regression-tests/{regression_id}/outputs/{output_id}/actual:
    get:
      tags: [Results]
      summary: Get actual output generated by a regression test in a run
      operationId: getActualOutput
      description: >
        IMPORTANT: TestResultFile.got = null means the actual output MATCHED
        expected, not that actual output is missing. This is a semantic trap
        in the data model. Missing output is represented by a dummy row
        (-1,-1,-1,'','error') which the API translates to status=missing_output
        and returns 404. A 200 response always contains a real output file.
      security:
        - bearerAuth: []
      x-required-scope: results:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/SampleId"
        - $ref: "#/components/parameters/RegressionId"
        - $ref: "#/components/parameters/OutputId"
        - $ref: "#/components/parameters/Format"
      responses:
        "200":
          description: Actual output file (output exists and differs from expected)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OutputFile"
        "303":
          description: Output matched expected. Redirected to /expected.
          headers:
            Location:
              schema:
                type: string
                format: uri
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/samples/{sample_id}/regression-tests/{regression_id}/outputs/{output_id}/diff:
    get:
      tags: [Results]
      summary: Get expected-vs-actual diff for a failing regression test result
      operationId: getDiff
      description: >
        The legacy diff route is header-gated (X-Requested-With: XMLHttpRequest),
        not role-gated. The 403 seen on direct browser requests was a
        header-check artifact. This endpoint wraps the XHR logic and returns
        structured JSON — no HTML, no 50-line truncation.
      security:
        - bearerAuth: []
      x-required-scope: results:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/SampleId"
        - $ref: "#/components/parameters/RegressionId"
        - $ref: "#/components/parameters/OutputId"
        - name: context_lines
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 3
        - name: format
          in: query
          schema:
            type: string
            enum: [structured, unified]
            default: structured
      responses:
        "200":
          description: Structured or unified diff
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/Diff"
                  - $ref: "#/components/schemas/UnifiedDiff"
                discriminator:
                  propertyName: format
                  mapping:
                    structured: "#/components/schemas/Diff"
                    unified: "#/components/schemas/UnifiedDiff"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/samples/{sample_id}/baseline-approval:
    post:
      tags: [Results]
      summary: Approve actual output as new expected baseline
      operationId: approveBaseline
      description: >
        Requires baselines:write scope and admin role.
        This is a destructive write — the approved output becomes the new
        expected baseline for the regression test.
      security:
        - bearerAuth: []
      x-required-scope: baselines:write
      x-required-roles: [admin]
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/SampleId"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BaselineApprovalRequest"
      responses:
        "200":
          description: Baseline approval applied immediately.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BaselineApproval"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  # ERRORS AND LOGS

  /runs/{run_id}/errors:
    get:
      tags: [Errors and Logs]
      summary: Get structured test errors for a run
      operationId: listRunErrors
      description: >
        Error types are derived from TestResult and TestResultFile rows.
        missing_output is detected from the dummy (-1,-1,-1,'','error') row
        pattern, not from got=null (which means match, not missing).
      security:
        - bearerAuth: []
      x-required-scope: results:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: type
          in: query
          schema:
            type: string
            enum: [test_failure, exit_code_mismatch, missing_output, diff_mismatch]
        - name: severity
          in: query
          schema:
            type: string
            enum: [info, warning, error, critical]
        - name: sample_id
          in: query
          schema:
            type: integer
            minimum: 1
      responses:
        "200":
          description: Paginated test errors
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ErrorItem"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/infrastructure-errors:
    get:
      tags: [Errors and Logs]
      summary: Get worker, provisioning, and build errors for a run
      operationId: listInfraErrors
      description: >
        Errors are extracted from TestProgress rows written by the CI worker.
        Messages are currently unstructured text. The type filter does
        best-effort text matching until the worker protocol emits structured
        error types.
        Stack traces are opt-in (include_stack defaults to false) to avoid
        leaking internal paths to unauthorized callers.
      security:
        - bearerAuth: []
      x-required-scope: system:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: type
          in: query
          schema:
            type: string
            enum: [queue, vm_provisioning, checkout, merge, build, worker, web_server, storage]
        - name: severity
          in: query
          schema:
            type: string
            enum: [info, warning, error, critical]
        - name: include_stack
          in: query
          schema:
            type: boolean
            default: false
          description: >
            Default false. Set true only when debugging infrastructure failures.
            Stacks may contain internal paths; access requires system:read scope.
      responses:
        "200":
          description: Paginated infrastructure errors
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ErrorItem"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/logs:
    get:
      tags: [Errors and Logs]
      summary: Get raw logs for a run
      operationId: getRunLogs
      description: >
        Logs are stored at SAMPLE_REPOSITORY/LogFiles/{id}.txt and served
        via GCS signed URL. Returns 404 — not a broken download link — when
        the file is absent from both local and GCS storage.
        Uses cursor-based pagination.
      security:
        - bearerAuth: []
      x-required-scope: system:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: level
          in: query
          schema:
            type: string
            enum: [debug, info, warning, error, critical]
        - name: source
          in: query
          schema:
            type: string
            enum: [orchestrator, worker, build, test_runner, web]
        - name: contains
          in: query
          schema:
            type: string
            maxLength: 100
      responses:
        "200":
          description: Cursor-paginated run log lines
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/CursorPage"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/LogLine"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          description: Log file not found in local or GCS storage
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                code: log_not_found
                message: Log file for run 9309 does not exist in any storage backend.
                details:
                  run_id: 9309
                  checked: [local, gcs]
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/samples/{sample_id}/logs:
    get:
      tags: [Errors and Logs]
      summary: Get raw logs for a regression test result in a run
      operationId: getSampleLogs
      description: >
        Returns raw log lines for a specific regression test result.
        Logs are stored at SAMPLE_REPOSITORY/LogFiles/ and served via GCS
        signed URL when available. Returns 404 when the log file is absent
        from both local and GCS storage.
      security:
        - bearerAuth: []
      x-required-scope: system:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/SampleId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Cursor"
        - name: level
          in: query
          schema:
            type: string
            enum: [debug, info, warning, error, critical]
        - name: contains
          in: query
          schema:
            type: string
            maxLength: 100
      responses:
        "200":
          description: Cursor-paginated sample log lines
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/CursorPage"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/LogLine"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/error-summary:
    get:
      tags: [Errors and Logs]
      summary: Get grouped error summary for a run
      operationId: getErrorSummary
      description: >
        Use this endpoint to triage a run before drilling into individual
        errors. group_by=type gives a high-level failure breakdown;
        group_by=sample_id helps identify flaky samples.
      security:
        - bearerAuth: []
      x-required-scope: results:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: group_by
          in: query
          schema:
            type: string
            enum: [type, sample_id, regression_id, severity]
            default: type
        - name: severity
          in: query
          schema:
            type: string
            enum: [info, warning, error, critical]
      responses:
        "200":
          description: Paginated grouped error summary
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/ErrorSummaryBucket"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  # SYSTEM

  /system/health:
    get:
      tags: [System]
      summary: Get CI system health and dependency status
      operationId: getHealth
      description: >
        Unauthenticated. Returns overall system status and per-dependency
        health. Used by monitoring and uptime checks.
      security: []
      responses:
        "200":
          description: System healthy or degraded
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemHealth"
        "503":
          description: System is down
          headers:
            X-RateLimit-Limit:
              $ref: "#/components/headers/RateLimitLimit"
            X-RateLimit-Remaining:
              $ref: "#/components/headers/RateLimitRemaining"
            X-RateLimit-Reset:
              $ref: "#/components/headers/RateLimitReset"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemHealth"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /system/queue:
    get:
      tags: [System]
      summary: Get queue depth and currently running jobs
      operationId: getQueue
      security:
        - bearerAuth: []
      x-required-scope: system:read
      parameters:
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: platform
          in: query
          schema:
            type: string
            enum: [linux, windows]
        - name: status
          in: query
          schema:
            type: string
            enum: [queued, running]
      responses:
        "200":
          description: Queue status and active jobs
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      queue_depth:
                        type: integer
                        minimum: 0
                      running_count:
                        type: integer
                        minimum: 0
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/QueueJob"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

  /runs/{run_id}/artifacts:
    get:
      tags: [System]
      summary: List downloadable artifacts for a run
      operationId: listArtifacts
      description: >
        Only returns artifacts with a verified download_url from at least one
        storage backend. storage_status=degraded means one backend only;
        storage_status=missing means neither backend has the file (download_url
        will be null). Never returns a URL that has not been verified to exist.
      security:
        - bearerAuth: []
      x-required-scope: results:read
      parameters:
        - $ref: "#/components/parameters/RunId"
        - $ref: "#/components/parameters/Limit"
        - $ref: "#/components/parameters/Offset"
        - name: type
          in: query
          schema:
            type: string
            enum: [build_log, sample_output, expected_output, diff, media_info, binary, coredump, combined_stdout]
      responses:
        "200":
          description: Paginated run artifacts
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/Page"
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: "#/components/schemas/Artifact"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
        default:
          $ref: "#/components/responses/Error"

#
# COMPONENTS
#
components:

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: >
        Opaque server-side API token. Obtain via POST /auth/tokens.
        The CI worker token used by /ci/progress-reporter is a separate
        secret and is NOT valid here. Never use browser session cookies
        for API clients.

  # HEADERS

  headers:
    RateLimitLimit:
      description: Maximum requests allowed in the current window
      schema:
        type: integer
        example: 120
    RateLimitRemaining:
      description: Requests remaining in the current window
      schema:
        type: integer
        example: 117
    RateLimitReset:
      description: Unix timestamp when the rate limit window resets
      schema:
        type: integer
        example: 1748908800

  # PARAMETERS

  parameters:
    Limit:
      name: limit
      in: query
      description: Maximum number of results to return (1–100)
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50

    Offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        minimum: 0
        maximum: 2147483647
        default: 0

    Cursor:
      name: cursor
      in: query
      description: >
        Numeric line offset or ID for cursor-based pagination. Do not mix with offset. Mixing cursor and offset returns 400.
        Obtain next_cursor from the previous response's pagination object.
      schema:
        type: integer
        minimum: 0
        maximum: 10000000

    RunId:
      name: run_id
      in: path
      required: true
      description: Numeric run ID
      schema:
        type: integer
        minimum: 1

    SampleId:
      name: sample_id
      in: path
      required: true
      description: Numeric media sample ID
      schema:
        type: integer
        minimum: 1

    RegressionTestId:
      name: regression_test_id
      in: path
      required: true
      description: Numeric regression test ID (not the same as media sample ID)
      schema:
        type: integer
        minimum: 1

    RegressionTestIdFilter:
      name: regression_test_id
      in: query
      description: >
        Restrict the history to a single regression test of this sample, so
        that limit counts runs of that test rather than rows across every
        regression test on the sample. Must belong to the sample in the path;
        400 otherwise.
      schema:
        type: integer
        minimum: 1
        maximum: 2147483647

    SampleHistoryStatus:
      name: status
      in: query
      description: >
        Normalized per-sample status, derived from the result files and the
        expected outputs of each result. Because it is derived rather than
        stored, this filter is applied over a bounded scan of the most recent
        results; see pagination.truncated on the response.
      schema:
        type: string
        enum: [pass, fail, missing_output, not_started]
        example: fail

    UserId:
      name: user_id
      in: path
      required: true
      description: Numeric platform user ID
      schema:
        type: integer
        minimum: 1

    CategoryId:
      name: category_id
      in: path
      required: true
      description: Numeric category ID
      schema:
        type: integer
        minimum: 1

    BlockedUserId:
      name: user_id
      in: path
      required: true
      description: Numeric GitHub account ID (not the login)
      schema:
        type: integer
        minimum: 1

    PlatformPath:
      name: platform
      in: path
      required: true
      description: CI platform
      schema:
        type: string
        enum: [linux, windows]

    ExtensionPath:
      name: extension
      in: path
      required: true
      description: File extension, with or without a leading dot
      schema:
        type: string
        maxLength: 33

    RunStatus:
      name: status
      in: query
      description: >
        Normalized run status. Derived from TestProgress rows and TestResult
        outcomes. The underlying TestStatus model stores only preparation,
        testing, completed, and canceled (where canceled covers both canceled
        and error). This enum is the normalized API contract.
      schema:
        type: string
        enum: [queued, running, pass, fail, canceled, incomplete]
        example: pass

    Branch:
      name: branch
      in: query
      description: Filter by branch name (e.g. master, develop).
      schema:
        type: string
        maxLength: 100
        example: master

    CommitSha:
      name: commit_sha
      in: query
      description: >
        Filter by full 40-character SHA-1 commit hash.
      schema:
        type: string
        pattern: '^[a-fA-F0-9]{40}$'
        example: 0b1a967b732898e705ea8f2fda5d08eb00328579

    Repository:
      name: repository
      in: query
      description: >
        Filter by GitHub repository in owner/repo format.
      schema:
        type: string
        pattern: '^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$'
        maxLength: 100
        example: CCExtractor/ccextractor

    Platform:
      name: platform
      in: query
      schema:
        type: string
        enum: [linux, windows]
        example: linux

    CreatedAfter:
      name: created_after
      in: query
      description: >
        ISO 8601 datetime filter. Returns runs created after this time.
        Example: 2025-01-01T00:00:00Z
      schema:
        type: string
        format: date-time

    CreatedBefore:
      name: created_before
      in: query
      description: >
        ISO 8601 datetime filter. Returns runs created before this time.
        Example: 2026-12-31T23:59:59Z
      schema:
        type: string
        format: date-time

    RegressionId:
      name: regression_id
      in: path
      required: true
      description: Regression test definition ID
      schema:
        type: integer
        minimum: 1

    OutputId:
      name: output_id
      in: path
      required: true
      description: Output file ID within a regression test definition
      schema:
        type: integer
        minimum: 1

    Format:
      name: format
      in: query
      description: >
        Content encoding for file responses.
        Use text only when the file is known to be UTF-8 compatible.
        Binary or unknown content defaults to base64.
      schema:
        type: string
        enum: [text, base64]
        default: base64

  # RESPONSES

  responses:
    BadRequest:
      description: Request body or query parameters failed schema validation
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: validation_error
            message: Request failed schema validation.
            details:
              fields:
                commit_sha: Must match pattern ^[a-fA-F0-9]{40}$
                platform: Must be one of [linux, windows]

    Unauthorized:
      description: Missing, expired, or invalid bearer token
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: unauthorized
            message: Bearer token is missing, expired, or invalid.
            details: {}

    Forbidden:
      description: Token is valid but lacks the required scope or role
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: forbidden
            message: Token does not have the required scope for this operation.
            details:
              required_scope: runs:write
              token_scopes: [runs:read, results:read]

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: not_found
            message: Run 9317 not found.
            details:
              resource: run

    Conflict:
      description: >
        The request clashes with existing state — a duplicate name, or a
        deletion that would discard records still referenced elsewhere.
        Where the conflict is about dependants, details carries their count
        and the request can be repeated with ?force=true.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: conflict
            message: >
              Regression test 42 has 118 historical result(s). Pass
              ?force=true to delete it and them.
            details:
              result_count: 118
              id: 9317

    UnprocessableEntity:
      description: Request is valid JSON but semantically invalid
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: unprocessable
            message: regression_test_ids contains inactive test IDs.
            details:
              inactive_ids: [42, 99]

    RateLimited:
      description: Too many requests. Retry after the indicated number of seconds.
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema:
            type: integer
            example: 30
        X-RateLimit-Limit:
          $ref: "#/components/headers/RateLimitLimit"
        X-RateLimit-Remaining:
          $ref: "#/components/headers/RateLimitRemaining"
        X-RateLimit-Reset:
          $ref: "#/components/headers/RateLimitReset"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"
          example:
            code: rate_limited
            message: Rate limit exceeded. Retry after 30 seconds.
            details:
              retry_after: 30
              limit: 120
              window: 60s

    Error:
      description: Unexpected server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ErrorResponse"

  # SCHEMAS

  schemas:

    Page:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          description: >
            Result items. The concrete type is defined by allOf composition
            in each endpoint response.
          items: {}
        pagination:
          type: object
          required: [limit, offset, total]
          properties:
            limit:
              type: integer
              minimum: 1
            offset:
              type: integer
              minimum: 0
            total:
              type: integer
              minimum: -1
              nullable: true
              description: >
                Total matching records. Null if count was not computed for this request.
                Pass ?count=true to force computation.
            next_offset:
              type: integer
              minimum: 0
              nullable: true
            truncated:
              type: boolean
              description: >
                Present and true when the result set was capped by an
                internal safety limit (e.g. status-filter on runs). When
                true, total may undercount the real number of matches.

    CursorPage:
      type: object
      required: [data, pagination]
      properties:
        data:
          type: array
          description: >
            Result items. The concrete type is defined by allOf composition
            in each endpoint response.
          items: {}
        pagination:
          type: object
          required: [limit, next_cursor]
          properties:
            limit:
              type: integer
              minimum: 1
            next_cursor:
              type: integer
              minimum: 0
              nullable: true
              description: >
                Numeric cursor for the next page. Null when there are no
                more results.

    ErrorResponse:
      type: object
      required: [code, message, details]
      properties:
        code:
          type: string
          maxLength: 100
          description: Machine-readable error code (snake_case)
          example: not_found
        message:
          type: string
          maxLength: 500
          description: Human-readable error summary
          example: Run 9317 not found.
        details:
          type: object
          additionalProperties: true
          description: >
            Structured context for the error. Always an object, never null.
            Empty object {} when no additional detail is available.

    ApiTokenItem:
      type: object
      description: >
        Token metadata returned when listing tokens. The plaintext token
        value is never included - it is shown only once at creation time.
      required: [id, user_id, token_name, scopes, created_at, expires_at, is_revoked]
      properties:
        id:
          type: integer
          minimum: 1
        user_id:
          type: integer
          minimum: 1
          description: Owner of the token. Visible to admins when listing all tokens.
        token_name:
          type: string
          maxLength: 50
        scopes:
          type: array
          maxItems: 7
          uniqueItems: true
          items:
            type: string
            enum: [runs:read, runs:write, results:read, baselines:write, system:read, system:write, tokens:manage]
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        is_revoked:
          type: boolean
          description: True if the token has been explicitly revoked.
        revoked_at:
          type: string
          format: date-time
          nullable: true

    TokenCreateRequest:
      type: object
      required: [email, password, token_name]
      additionalProperties: false
      properties:
        email:
          type: string
          format: email
          maxLength: 255
        password:
          type: string
          format: password
          minLength: 8
          maxLength: 128
          description: Not stored or logged. Used only to verify identity.
        token_name:
          type: string
          minLength: 1
          maxLength: 50
          pattern: '^[a-zA-Z0-9_-]+$'
          description: >
            Descriptive label for the token (e.g., local-agent, ci-bot).
            Must be unique per user.
        expires_in_days:
          type: integer
          minimum: 1
          maximum: 30
          default: 7
        scopes:
          type: array
          maxItems: 7
          uniqueItems: true
          default: [runs:read, results:read]
          items:
            type: string
            enum: [runs:read, runs:write, results:read, baselines:write, system:read, system:write, tokens:manage]
          description: >
            Requested scopes. Grant only what the client needs.
            runs:read — list and inspect runs, samples, history.
            runs:write — trigger and cancel runs, and edit the regression suite.
            results:read — access expected/actual output, diffs, errors, logs.
            baselines:write — approve new expected baselines.
            system:read — queue, infrastructure errors, stack traces, artifacts,
            and the platform configuration.
            system:write — change the platform configuration: maintenance mode,
            blocked CI users, forbidden upload extensions. Admin only.
            tokens:manage — list and revoke API tokens, and administer users.

    AuthToken:
      type: object
      required: [token, token_type, token_name, scopes, expires_at]
      properties:
        token:
          type: string
          maxLength: 512
          description: >
            Opaque token value. Store it securely. It will not be shown again.
        token_type:
          type: string
          enum: [bearer]
        token_name:
          type: string
          maxLength: 50
        scopes:
          type: array
          maxItems: 8
          uniqueItems: true
          items:
            type: string
            enum: [runs:read, runs:write, results:read, baselines:write, system:read, system:write, tokens:manage]
        expires_at:
          type: string
          format: date-time

    RunCreateRequest:
      type: object
      required: [repository, commit_sha, platform]
      additionalProperties: false
      properties:
        repository:
          type: string
          pattern: '^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$'
          maxLength: 100
          example: CCExtractor/ccextractor
        branch:
          type: string
          pattern: '^[A-Za-z0-9._-]+(/[A-Za-z0-9._-]+)*$'
          maxLength: 100
          example: master
        commit_sha:
          type: string
          pattern: '^[a-fA-F0-9]{40}$'
          example: 0632bff4e382d5f86eff9073b9ddd37f03f9778c
        pull_request:
          type: integer
          minimum: 1
          maximum: 2147483647
          nullable: true
          example: 2264
        platform:
          type: string
          enum: [linux, windows]
          example: windows
        regression_test_ids:
          type: array
          maxItems: 500
          uniqueItems: true
          items:
            type: integer
            minimum: 1
            maximum: 2147483647
          description: >
            Optional subset of active regression test IDs.
            If omitted, all active tests are used.
            Inactive test IDs are rejected with 422.

    Run:
      type: object
      required: [run_id, status, repository, commit_sha, platform]
      properties:
        run_id:
          type: integer
          minimum: 1
        status:
          type: string
          enum: [queued, running, pass, fail, canceled, incomplete]
          description: >
            Normalized status. Derived from TestProgress rows and TestResult
            outcomes. status=canceled covers both explicit cancellation and
            infrastructure error (the underlying model conflates them).
        platform:
          type: string
          enum: [linux, windows]
        test_type:
          type: string
          enum: [pr, commit]
          description: Whether this run was triggered by a pull request or a commit push.
        repository:
          type: string
          maxLength: 100
        branch:
          type: string
          maxLength: 100
          nullable: true
        commit_sha:
          type: string
          pattern: '^[a-fA-F0-9]{40}$'
          description: >
            Recorded trigger SHA. For pull requests this is the PR head, which
            GitHub Actions does not build when testing merge refs.
        built_commit_sha:
          type: string
          pattern: '^[a-fA-F0-9]{7,40}$'
          nullable: true
          description: >
            SHA that was actually compiled and tested, when it differs from
            commit_sha. For PRs this is GitHub's merge commit and/or the
            `Git commit:` line from VM logs. Null when unknown or identical.
        pr_number:
          type: integer
          minimum: 1
          nullable: true
          description: Pull request number, if this run was triggered by a PR.
        created_at:
          type: string
          format: date-time
          nullable: true
        queued_at:
          type: string
          format: date-time
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        completed_at:
          type: string
          format: date-time
          nullable: true
        github_link:
          type: string
          format: uri
          nullable: true
          description: Direct link to the commit or PR on GitHub.

    RunSummary:
      type: object
      required: [run_id, status, total_samples, pass_count, fail_count, skipped_count, missing_output_count]
      properties:
        run_id:
          type: integer
          minimum: 1
        status:
          type: string
          enum: [queued, running, pass, fail, canceled, incomplete]
          description: >
            Overall run status at the time the summary was generated.
            Same derivation as Run.status.
        total_samples:
          type: integer
          minimum: 0
          description: Total regression test results in this run.
        pass_count:
          type: integer
          minimum: 0
        fail_count:
          type: integer
          minimum: 0
          description: >
            Computed from TestResult rows. NOT derived from test.failed,
            which only reflects cancellation state and is unreliable for
            determining whether regression tests actually passed.
        skipped_count:
          type: integer
          minimum: 0
        missing_output_count:
          type: integer
          minimum: 0
          description: >
            Samples that produced no output when output was expected.
            Detected from the dummy TestResultFile(-1,-1,-1,'','error') row,
            not from got=null (which means output matched).
        error_count:
          type: integer
          minimum: 0
        duration_ms:
          type: integer
          minimum: 0
          nullable: true

    ProgressEvent:
      type: object
      required: [timestamp, status, message]
      properties:
        timestamp:
          type: string
          format: date-time
        status:
          type: string
          enum: [queued, preparation, testing, completed, canceled, error]
        message:
          type: string
          maxLength: 500
          description: Unstructured text from TestProgress rows.
        step:
          type: integer
          minimum: 0
          nullable: true

    RunActionResult:
      type: object
      required: [run_id, action, status]
      properties:
        run_id:
          type: integer
          minimum: 1
          description: ID of the run this action targets.
        action:
          type: string
          enum: [cancel]
        status:
          type: string
          enum: [accepted, rejected, no_op]
          description: no_op is returned when canceling an already-terminal run.
        message:
          type: string
          maxLength: 500

    RunConfig:
      type: object
      required: [run_id, platform, branch, commit_sha, regression_test_ids]
      properties:
        run_id:
          type: integer
          minimum: 1
        platform:
          type: string
          enum: [linux, windows]
        branch:
          type: string
          maxLength: 100
        commit_sha:
          type: string
          pattern: '^[a-fA-F0-9]{40}$'
        regression_test_ids:
          type: array
          maxItems: 500
          uniqueItems: true
          items:
            type: integer
            minimum: 1
          description: >
            IDs included in this run. When no custom set was configured, all
            regression tests are returned. Implementers must filter by
            active=true — get_customized_regressiontests() does not do this.

    Sample:
      type: object
      required: [sample_id, sha]
      properties:
        sample_id:
          type: integer
          minimum: 1
        sha:
          type: string
          pattern: '^[a-fA-F0-9]{64}$'
          description: SHA256 hash of the sample file.
        extension:
          type: string
          maxLength: 10
        original_name:
          type: string
          maxLength: 255
        filename:
          type: string
          maxLength: 255
        tags:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 50
        regression_test_count:
          type: integer
          minimum: 0
          description: Number of active regression tests referencing this sample.
        active:
          type: boolean
          description: True if at least one active regression test references this sample.

    DeletedResource:
      type: object
      required: [deleted]
      properties:
        id:
          type: integer
          minimum: 1
        deleted:
          type: boolean

    Category:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
          minimum: 1
        name:
          type: string
          maxLength: 64
        description:
          type: string
          maxLength: 1024
        test_count:
          type: integer
          minimum: 0
          description: How many regression tests reference this category.

    CategoryCreateRequest:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
        description:
          type: string
          default: ""
          maxLength: 1024

    CategoryUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      description: Only the fields present are written; an empty body is rejected.
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 64
        description:
          type: string
          maxLength: 1024

    RegressionTestDetail:
      allOf:
        - $ref: "#/components/schemas/RegressionTest"
        - type: object
          properties:
            outputs:
              type: array
              maxItems: 100
              description: Expected outputs, with the hashes accepted as variants.
              items:
                type: object
                properties:
                  id:
                    type: integer
                    minimum: 1
                  correct:
                    type: string
                    maxLength: 128
                  correct_extension:
                    type: string
                    maxLength: 64
                  expected_filename:
                    type: string
                    maxLength: 255
                    nullable: true
                  ignore:
                    type: boolean
                  variants:
                    type: array
                    maxItems: 100
                    items:
                      type: object
                      required: [id, hash]
                      properties:
                        id:
                          type: integer
                          minimum: 1
                          description: Addresses the variant in its download route.
                        hash:
                          type: string
                          maxLength: 128

    StoredFile:
      type: object
      required: [filename, download_url, storage_status]
      description: >
        Where a file lives rather than the file itself. Samples and baselines
        are handed out as signed URLs so that large transfers do not run
        through the API. A null download_url with storage_status=degraded
        means the only copy is on the platform's own disk.
      properties:
        filename:
          type: string
          maxLength: 255
        download_url:
          type: string
          format: uri
          nullable: true
        storage_status:
          type: string
          enum: [ok, degraded]

    MaintenanceState:
      type: object
      required: [platform, disabled]
      properties:
        platform:
          type: string
          enum: [linux, windows]
        disabled:
          type: boolean
          description: >
            True while the platform is paused. Runs still queue; they are
            just not handed to a VM.

    MaintenanceUpdateRequest:
      type: object
      additionalProperties: false
      required: [disabled]
      properties:
        disabled:
          type: boolean

    BlockedUser:
      type: object
      required: [user_id]
      properties:
        user_id:
          type: integer
          minimum: 1
          description: Numeric GitHub account ID.
        comment:
          type: string
          maxLength: 1024

    BlockedUserCreateRequest:
      type: object
      additionalProperties: false
      required: [user_id]
      properties:
        user_id:
          type: integer
          minimum: 1
        comment:
          type: string
          default: ""
          maxLength: 1024

    ForbiddenExtensionCreateRequest:
      type: object
      additionalProperties: false
      required: [extension]
      properties:
        extension:
          type: string
          minLength: 1
          maxLength: 32
          pattern: "^[A-Za-z0-9]+$"
          description: Alphanumeric, without a leading dot.

    CurrentUser:
      type: object
      required: [user_id, email, role, scopes]
      properties:
        user_id:
          type: integer
          minimum: 1
        name:
          type: string
          maxLength: 255
        email:
          type: string
          format: email
          maxLength: 255
        role:
          type: string
          enum: [admin, contributor, tester, user]
        scopes:
          type: array
          maxItems: 6
          items:
            type: string
            maxLength: 50

    PlatformUser:
      type: object
      required: [user_id, email, role]
      properties:
        user_id:
          type: integer
          minimum: 1
        name:
          type: string
          maxLength: 255
        email:
          type: string
          format: email
          maxLength: 255
        role:
          type: string
          enum: [admin, contributor, tester, user]
        github_linked:
          type: boolean
        github_login:
          type: string
          maxLength: 255
          nullable: true

    RoleUpdateRequest:
      type: object
      additionalProperties: false
      required: [role]
      properties:
        role:
          type: string
          enum: [admin, contributor, tester, user]

    SampleDetails:
      type: object
      required: [sample_id, sha, extension, original_name]
      properties:
        sample_id:
          type: integer
          minimum: 1
        sha:
          type: string
          maxLength: 128
        extension:
          type: string
          maxLength: 64
        original_name:
          type: string
          maxLength: 255
        filename:
          type: string
          maxLength: 255
        tags:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 100
        upload:
          nullable: true
          description: The upload record, or null when the sample predates one.
          type: object
          properties:
            platform:
              type: string
              maxLength: 50
              nullable: true
            parameters:
              type: string
              maxLength: 1024
            notes:
              type: string
              maxLength: 4096
            version:
              type: string
              maxLength: 50
              nullable: true
            version_released:
              type: string
              format: date-time
              nullable: true
        extra_files:
          type: array
          maxItems: 100
          items:
            type: object
            properties:
              id:
                type: integer
                minimum: 1
              original_name:
                type: string
                maxLength: 255
              extension:
                type: string
                maxLength: 64
        media_info:
          nullable: true
          description: >
            Parsed MediaInfo tree, or null when the XML is absent or cannot
            be parsed. Shape mirrors the source document and is not fixed.
          type: array
          items:
            type: object

    RegressionTestCreateRequest:
      type: object
      additionalProperties: false
      required: [sample_id, command, categories]
      properties:
        sample_id:
          type: integer
          minimum: 1
        command:
          type: string
          minLength: 1
          maxLength: 500
        input_type:
          type: string
          default: file
          enum: [file, stdin, udp]
        output_type:
          type: string
          default: file
          enum: [file, "null", stdout, tcp, cea708, multiprogram, report]
        expected_rc:
          type: integer
          default: 0
          minimum: 0
          maximum: 255
        description:
          type: string
          default: ""
          maxLength: 1024
        categories:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 64
        active:
          type: boolean
          default: false
          description: >
            Left false so a new test cannot join a CI suite before its
            output has been verified on a run.

    RegressionTestUpdateRequest:
      type: object
      additionalProperties: false
      minProperties: 1
      description: Only the fields present are written; an empty body is rejected.
      properties:
        command:
          type: string
          minLength: 1
          maxLength: 500
        input_type:
          type: string
          enum: [file, stdin, udp]
        output_type:
          type: string
          enum: [file, "null", stdout, tcp, cea708, multiprogram, report]
        expected_rc:
          type: integer
          minimum: 0
          maximum: 255
        description:
          type: string
          maxLength: 1024
        categories:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 64
        active:
          type: boolean

    RegressionTest:
      type: object
      required: [regression_test_id, sample_id, command]
      properties:
        regression_test_id:
          type: integer
          minimum: 1
        sample_id:
          type: integer
          minimum: 1
        sample_name:
          type: string
          maxLength: 255
          nullable: true
        command:
          type: string
          maxLength: 500
        input_type:
          type: string
          maxLength: 50
        output_type:
          type: string
          maxLength: 50
        expected_rc:
          type: integer
          nullable: true
        active:
          type: boolean
        categories:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 100
        description:
          type: string
          maxLength: 1000
          nullable: true

    RunSample:
      type: object
      required: [regression_test_id, sample_id, status]
      properties:
        regression_test_id:
          type: integer
          minimum: 1
        sample_id:
          type: integer
          minimum: 1
          nullable: true
        sample_name:
          type: string
          maxLength: 255
          nullable: true
        categories:
          type: array
          maxItems: 50
          items:
            type: string
            maxLength: 100
          description: Category labels from the regression test definition.
        command:
          type: string
          maxLength: 500
          nullable: true
        status:
          type: string
          enum: [pass, fail, skipped, missing_output, running, not_started]
          description: >
            Computed from TestResult, TestResultFile, expected exit code,
            and multiple acceptable baselines. Not a stored column.
        runtime_ms:
          type: integer
          minimum: 0
          nullable: true
        exit_code:
          type: integer
          nullable: true
        expected_rc:
          type: integer
          nullable: true
          description: Expected return code for this regression test.
        outputs:
          type: array
          maxItems: 20
          description: >
            One entry per expected output file.
            got=null in the DB means output matched expected; no actual file
            is stored. The dummy (-1,-1,-1,'','error') row is translated to
            status=missing_output and is never exposed here.
          items:
            type: object
            required: [output_id, filename, status]
            additionalProperties: false
            properties:
              output_id:
                type: integer
                minimum: 1
              filename:
                type: string
                maxLength: 255
              status:
                type: string
                enum: [pass, fail, missing_output, missing_expected]
                description: >
                  pass = actual identical to expected.
                  fail = actual differs from expected.
                  missing_output = test produced no output.
                  missing_expected = no expected baseline exists.

    SampleHistoryEntry:
      type: object
      required: [run_id, regression_test_id, status]
      properties:
        run_id:
          type: integer
          minimum: 1
        regression_test_id:
          type: integer
          minimum: 1
        status:
          type: string
          enum: [pass, fail, skipped, missing_output, running, not_started]
        platform:
          type: string
          enum: [linux, windows]
        branch:
          type: string
          maxLength: 100
          nullable: true
        commit_sha:
          type: string
          pattern: '^[a-fA-F0-9]{40}$'
          nullable: true
        tested_at:
          type: string
          format: date-time
          nullable: true
          description: completed_at or started_at timestamp from the run.
        failure_signature:
          type: string
          maxLength: 255
          nullable: true
          description: >
            Stable string identifying the failure type and output ID.
            Use across runs to detect genuine regressions vs. infrastructure
            flakes.

    OutputFile:
      type: object
      required: [sample_id, regression_id, output_id, filename, content_type, encoding, content, storage_status]
      properties:
        run_id:
          type: integer
          minimum: 1
          nullable: true
          description: Null for expected output not tied to a specific run.
        sample_id:
          type: integer
          minimum: 1
        regression_id:
          type: integer
          minimum: 1
        output_id:
          type: integer
          minimum: 1
        filename:
          type: string
          maxLength: 255
        content_type:
          type: string
          maxLength: 100
        encoding:
          type: string
          enum: [utf-8, base64]
          description: >
            utf-8 only when file is confirmed text. Default is base64.
        content:
          type: string
          maxLength: 1048576
          description: >
            File content. Base64-encoded unless encoding=utf-8.
            Files exceeding 1MB are truncated. Check truncated=true and use
            download_url for the full file.
        truncated:
          type: boolean
          description: True if content was truncated due to size limits.
        download_url:
          type: string
          format: uri
          nullable: true
          description: URL to download the full file if it was truncated.
        sha256:
          type: string
          pattern: '^[a-fA-F0-9]{64}$'
        storage_status:
          type: string
          enum: [ok, degraded, missing]
          description: >
            ok = file verified in at least one storage backend.
            degraded = file exists but integrity or redundancy check failed.
            missing = file not found in any storage backend.

    Diff:
      type: object
      required: [run_id, sample_id, regression_id, output_id, status]
      properties:
        run_id:
          type: integer
          minimum: 1
        sample_id:
          type: integer
          minimum: 1
        regression_id:
          type: integer
          minimum: 1
        output_id:
          type: integer
          minimum: 1
        status:
          type: string
          enum: [identical, different, missing_expected, missing_actual]
        summary:
          type: object
          required: [added_lines, removed_lines, changed_hunks]
          properties:
            added_lines:
              type: integer
              minimum: 0
            removed_lines:
              type: integer
              minimum: 0
            changed_hunks:
              type: integer
              minimum: 0
        hunks:
          type: array
          maxItems: 500
          items:
            type: object
            required: [expected_start, actual_start, lines]
            additionalProperties: false
            properties:
              expected_start:
                type: integer
                minimum: 0
              actual_start:
                type: integer
                minimum: 0
              lines:
                type: array
                maxItems: 500
                items:
                  type: object
                  required: [kind, text]
                  additionalProperties: false
                  properties:
                    kind:
                      type: string
                      enum: [context, added, removed]
                    expected_line:
                      type: integer
                      minimum: 0
                      nullable: true
                    actual_line:
                      type: integer
                      minimum: 0
                      nullable: true
                    text:
                      type: string
                      maxLength: 1000

    UnifiedDiff:
      type: object
      required: [run_id, sample_id, regression_id, output_id, format, content]
      properties:
        run_id:
          type: integer
        sample_id:
          type: integer
        regression_id:
          type: integer
        output_id:
          type: integer
        format:
          type: string
          enum: [unified]
        content:
          type: string
          description: Raw unified diff text.
          maxLength: 524288

    BaselineApprovalRequest:
      type: object
      required: [regression_id, output_id]
      additionalProperties: false
      properties:
        regression_id:
          type: integer
          minimum: 1
        output_id:
          type: integer
          minimum: 1
        remove_variants:
          type: boolean
          default: false
          description: >
            If true, removes all platform-specific variants (output_id != 1)
            and promotes this output to the global baseline.

    BaselineApproval:
      type: object
      required: [status, run_id, sample_id, regression_id, output_id, requested_by, created_at]
      properties:
        status:
          type: string
          enum: [approved]
        run_id:
          type: integer
          minimum: 1
        sample_id:
          type: integer
          minimum: 1
        regression_id:
          type: integer
          minimum: 1
        output_id:
          type: integer
          minimum: 1
        requested_by:
          type: string
          maxLength: 100
          description: Display name of the user who requested the approval.
        created_at:
          type: string
          format: date-time

    ErrorItem:
      type: object
      required: [error_id, run_id, type, severity, message, occurred_at]
      properties:
        error_id:
          type: string
          maxLength: 100
        run_id:
          type: integer
          minimum: 1
        sample_id:
          type: integer
          minimum: 1
          nullable: true
        regression_id:
          type: integer
          minimum: 1
          nullable: true
        type:
          type: string
          enum: [test_failure, exit_code_mismatch, missing_output, diff_mismatch, queue, vm_provisioning, checkout, merge, build, worker, web_server, storage]
          maxLength: 100
        severity:
          type: string
          enum: [info, warning, error, critical]
        message:
          type: string
          maxLength: 1000
        location:
          type: object
          nullable: true
          additionalProperties: true
          properties:
            file:
              type: string
              maxLength: 500
              nullable: true
            line:
              type: integer
              minimum: 0
              nullable: true
            column:
              type: integer
              minimum: 0
              nullable: true
            sample_name:
              type: string
              maxLength: 255
              nullable: true
        stack:
          type: array
          maxItems: 50
          description: Only present when include_stack=true was requested.
          items:
            type: string
            maxLength: 2000
        occurred_at:
          type: string
          format: date-time

    LogLine:
      type: object
      required: [timestamp, level, source, message, run_id]
      properties:
        timestamp:
          type: string
          format: date-time
        level:
          type: string
          enum: [debug, info, warning, error, critical]
        source:
          type: string
          enum: [orchestrator, worker, build, test_runner, web]
        message:
          type: string
          maxLength: 4000
        run_id:
          type: integer
          minimum: 1
        sample_id:
          type: integer
          minimum: 1
          nullable: true

    ErrorSummaryBucket:
      type: object
      required: [key, count, severity, group_by]
      properties:
        group_by:
          type: string
          enum: [type, sample_id, regression_id, severity]
          description: The dimension this bucket is grouped by.
        key:
          type: string
          maxLength: 100
          description: >
            Value of the group_by dimension. When group_by=sample_id or
            regression_id, this is an integer serialized as a string.
        count:
          type: integer
          minimum: 0
        severity:
          type: string
          enum: [info, warning, error, critical]
        sample_ids:
          type: array
          maxItems: 1000
          items:
            type: integer
            minimum: 1
        first_seen_at:
          type: string
          format: date-time
          nullable: true
        last_seen_at:
          type: string
          format: date-time
          nullable: true

    SystemHealth:
      type: object
      required: [status, checked_at, dependencies]
      properties:
        status:
          type: string
          enum: [ok, degraded, down]
        checked_at:
          type: string
          format: date-time
        dependencies:
          type: array
          maxItems: 20
          items:
            type: object
            required: [name, status]
            properties:
              name:
                type: string
                maxLength: 100
              status:
                type: string
                enum: [ok, degraded, down]
              message:
                type: string
                maxLength: 500
                nullable: true

    QueueJob:
      type: object
      required: [run_id, status, platform, queued_at]
      properties:
        run_id:
          type: integer
          minimum: 1
        status:
          type: string
          enum: [queued, running]
        platform:
          type: string
          enum: [linux, windows]
        queued_at:
          type: string
          format: date-time
          nullable: true
        started_at:
          type: string
          format: date-time
          nullable: true
        position:
          type: integer
          minimum: 1
          nullable: true
          description: Queue position. Null for jobs that are already running.

    Artifact:
      type: object
      required: [artifact_id, run_id, type, filename, content_type, storage_status]
      properties:
        artifact_id:
          type: string
          maxLength: 100
        run_id:
          type: integer
          minimum: 1
        sample_id:
          type: integer
          minimum: 1
          nullable: true
        type:
          type: string
          enum: [build_log, sample_output, expected_output, actual_output, diff, media_info, binary, coredump, combined_stdout]
        filename:
          type: string
          maxLength: 255
        content_type:
          type: string
          maxLength: 100
        size_bytes:
          type: integer
          minimum: 0
          nullable: true
        storage_status:
          type: string
          enum: [ok, degraded, missing]
          description: >
            ok = file verified in at least one storage backend.
            degraded = file exists but integrity or redundancy check failed.
            missing = file not found in any storage backend.
        download_url:
          type: string
          format: uri
          nullable: true
          description: >
            Only present and non-null when storage_status is ok or degraded.
            Always a verified URL. Null when storage_status=missing.