repowise-dev Changes API

openapi: 3.2.0
info:
  title: repowise Changes API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: Changes
paths:
  /api/repos/{repo_id}/changes:
    get:
      tags:
      - Changes
      summary: List Changes
      description: 'A page of changes, newest merged first, each led by what its commits did

        to health. ``since``/``until`` read ``merged_at``; ``delta`` and

        ``touches_hotspot`` judge the change''s rollup.'
      operationId: list_changes_api_repos__repo_id__changes_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: One commit category, e.g. fix
          title: Category
        description: One commit category, e.g. fix
      - name: shape
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: merge | squash | commit
          title: Shape
        description: merge | squash | commit
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Substring of the title, id or a file path
          title: Q
        description: Substring of the title, id or a file path
      - name: evidence
        in: query
        required: false
        schema:
          type: boolean
          description: Add each row's kept checklist status counts; never builds one
          default: false
          title: Evidence
        description: Add each row's kept checklist status counts; never builds one
      - name: needs_attention
        in: query
        required: false
        schema:
          type: boolean
          description: Only changes whose kept checklist has an attention item
          default: false
          title: Needs Attention
        description: Only changes whose kept checklist has an attention item
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      - name: author
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Author email (any case) or exact name
          title: Author
        description: Author email (any case) or exact name
      - name: area
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: A directory or file path; keeps work touching it
          title: Area
        description: A directory or file path; keeps work touching it
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: ISO 8601, inclusive
          title: Since
        description: ISO 8601, inclusive
      - name: until
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: ISO 8601, exclusive
          title: Until
        description: ISO 8601, exclusive
      - name: delta
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(improved|worsened|mixed|neutral)$
          - type: 'null'
          description: 'What it did to health: improved | worsened (each includes mixed) | mixed | neutral. Never-scanned work matches none.'
          title: Delta
        description: 'What it did to health: improved | worsened (each includes mixed) | mixed | neutral. Never-scanned work matches none.'
      - name: touches_hotspot
        in: query
        required: false
        schema:
          type: boolean
          description: Only work that touched a hotspot file
          default: false
          title: Touches Hotspot
        description: Only work that touched a hotspot file
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/changes/summary:
    get:
      tags:
      - Changes
      summary: Changes Summary
      description: 'A period headline: how many changes made health better, worse, both or

        neither (improvements first), and the findings behind it.'
      operationId: changes_summary_api_repos__repo_id__changes_summary_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: category
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: One commit category, e.g. fix
          title: Category
        description: One commit category, e.g. fix
      - name: author
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Author email (any case) or exact name
          title: Author
        description: Author email (any case) or exact name
      - name: area
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: A directory or file path; keeps work touching it
          title: Area
        description: A directory or file path; keeps work touching it
      - name: since
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: ISO 8601, inclusive
          title: Since
        description: ISO 8601, inclusive
      - name: until
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          description: ISO 8601, exclusive
          title: Until
        description: ISO 8601, exclusive
      - name: delta
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            pattern: ^(improved|worsened|mixed|neutral)$
          - type: 'null'
          description: 'What it did to health: improved | worsened (each includes mixed) | mixed | neutral. Never-scanned work matches none.'
          title: Delta
        description: 'What it did to health: improved | worsened (each includes mixed) | mixed | neutral. Never-scanned work matches none.'
      - name: touches_hotspot
        in: query
        required: false
        schema:
          type: boolean
          description: Only work that touched a hotspot file
          default: false
          title: Touches Hotspot
        description: Only work that touched a hotspot file
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PeriodHealthSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/changes/{change_id}:
    get:
      tags:
      - Changes
      summary: Get Change
      description: One change by id (``pr-123``), or the change that landed a commit sha.
      operationId: get_change_api_repos__repo_id__changes__change_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: change_id
        in: path
        required: true
        schema:
          type: string
          title: Change Id
      - name: evidence
        in: query
        required: false
        schema:
          type: boolean
          description: Include the evidence checklist (built on first read, then kept)
          default: false
          title: Evidence
        description: Include the evidence checklist (built on first read, then kept)
      - name: refresh
        in: query
        required: false
        schema:
          type: boolean
          description: Rebuild the evidence checklist
          default: false
          title: Refresh
        description: Rebuild the evidence checklist
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChangeRecord'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/suspects:
    post:
      tags:
      - Changes
      summary: Rank Suspects
      description: 'The changes merged in a window, ranked against a symptom, with each row''s evidence.


        An order to read changes in, never a cause or a probability.'
      operationId: rank_suspects_api_repos__repo_id__suspects_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SuspectsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuspectsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
components:
  schemas:
    MovedFromResponse:
      properties:
        path:
          type: string
          title: Path
        symbol:
          anyOf:
          - type: string
          - type: 'null'
          title: Symbol
      type: object
      required:
      - path
      title: MovedFromResponse
      description: Where a finding's code was before the commit moved it.
    ChangeAuthor:
      properties:
        name:
          type: string
          title: Name
        email:
          type: string
          title: Email
      type: object
      required:
      - name
      - email
      title: ChangeAuthor
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ChangeEvidence:
      properties:
        schema_version:
          type: integer
          title: Schema Version
        change_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Change Id
        revspec:
          anyOf:
          - type: string
          - type: 'null'
          title: Revspec
        generated_at:
          type: string
          title: Generated At
        index_commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Index Commit
        items:
          items:
            $ref: '#/components/schemas/EvidenceItem'
          type: array
          title: Items
      type: object
      required:
      - schema_version
      - generated_at
      - items
      title: ChangeEvidence
      description: The evidence checklist (``repowise.core.changes.evidence``), versioned.
    ChangeHealthFindingResponse:
      properties:
        change_kind:
          type: string
          title: Change Kind
        dimension:
          type: string
          title: Dimension
        biomarker_type:
          type: string
          title: Biomarker Type
        severity:
          type: string
          title: Severity
        severity_before:
          anyOf:
          - type: string
          - type: 'null'
          title: Severity Before
        path:
          type: string
          title: Path
        symbol:
          anyOf:
          - type: string
          - type: 'null'
          title: Symbol
        line_start:
          anyOf:
          - type: integer
          - type: 'null'
          title: Line Start
        line_end:
          anyOf:
          - type: integer
          - type: 'null'
          title: Line End
        attribution_basis:
          type: string
          title: Attribution Basis
        reason:
          type: string
          title: Reason
        moved_from:
          anyOf:
          - $ref: '#/components/schemas/MovedFromResponse'
          - type: 'null'
        sha:
          type: string
          title: Sha
      type: object
      required:
      - change_kind
      - dimension
      - biomarker_type
      - severity
      - path
      - attribution_basis
      - reason
      - sha
      title: ChangeHealthFindingResponse
      description: A finding a change's commit introduced or worsened, with that commit.
    Suspect:
      properties:
        id:
          type: string
          title: Id
        ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Ref
        title:
          type: string
          title: Title
        merged_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Merged At
        category:
          type: string
          title: Category
        head_sha:
          type: string
          title: Head Sha
        files_changed:
          type: integer
          title: Files Changed
        provenance:
          anyOf:
          - type: string
          - type: 'null'
          title: Provenance
        rank:
          type: integer
          title: Rank
        signals:
          additionalProperties:
            $ref: '#/components/schemas/SuspectSignal'
          type: object
          title: Signals
      type: object
      required:
      - id
      - title
      - category
      - head_sha
      - files_changed
      - rank
      - signals
      title: Suspect
      description: One change in reading order; ``signals`` holds each signal that fired.
    ChangeProvenance:
      properties:
        label:
          type: string
          title: Label
        agent_commits:
          type: integer
          title: Agent Commits
        human_attested_commits:
          type: integer
          title: Human Attested Commits
        unknown_commits:
          type: integer
          title: Unknown Commits
        coverage:
          anyOf:
          - type: number
          - type: 'null'
          title: Coverage
      type: object
      required:
      - label
      - agent_commits
      - human_attested_commits
      - unknown_commits
      title: ChangeProvenance
      description: Three-state AI provenance over the change's commits, with its coverage.
    ChangeListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ChangeListItem'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        attribution:
          type: boolean
          title: Attribution
        checklists_built:
          anyOf:
          - $ref: '#/components/schemas/ChecklistsBuilt'
          - type: 'null'
      type: object
      required:
      - items
      - total
      - limit
      - offset
      - attribution
      title: ChangeListResponse
    SuspectSignal:
      properties:
        rank:
          type: integer
          title: Rank
        evidence:
          items:
            type: string
          type: array
          title: Evidence
      type: object
      required:
      - rank
      - evidence
      title: SuspectSignal
    ChangeEvidenceSummary:
      properties:
        generated_at:
          type: string
          title: Generated At
        ok:
          type: integer
          title: Ok
        attention:
          type: integer
          title: Attention
        unknown:
          type: integer
          title: Unknown
      type: object
      required:
      - generated_at
      - ok
      - attention
      - unknown
      title: ChangeEvidenceSummary
      description: Status counts of a change's kept checklist; never builds one.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    ChecklistsBuilt:
      properties:
        built:
          type: integer
          title: Built
        changes:
          type: integer
          title: Changes
      type: object
      required:
      - built
      - changes
      title: ChecklistsBuilt
      description: How many of the changes a list's filters match keep an evidence checklist.
    SuspectsResponse:
      properties:
        window:
          additionalProperties:
            type: string
          type: object
          title: Window
        candidates:
          type: integer
          title: Candidates
        candidates_capped:
          type: boolean
          title: Candidates Capped
        texts_missing:
          type: integer
          title: Texts Missing
          default: 0
        symptom_files:
          items:
            type: string
          type: array
          title: Symptom Files
          default: []
        suspects:
          items:
            $ref: '#/components/schemas/Suspect'
          type: array
          title: Suspects
        note:
          type: string
          title: Note
      type: object
      required:
      - window
      - candidates
      - candidates_capped
      - suspects
      - note
      title: SuspectsResponse
    ChangeIdentity:
      properties:
        kind:
          type: string
          title: Kind
        value:
          type: string
          title: Value
      type: object
      required:
      - kind
      - value
      title: ChangeIdentity
      description: '``pr`` | ``change_id`` | ``merge`` | ``commit``, first that applies.'
    EvidenceItem:
      properties:
        kind:
          type: string
          title: Kind
        label:
          type: string
          title: Label
        status:
          type: string
          enum:
          - ok
          - attention
          - unknown
          title: Status
        basis:
          type: string
          enum:
          - measured
          - inferred
          - declared
          - unresolved
          title: Basis
        value:
          title: Value
        details:
          items:
            additionalProperties: true
            type: object
          type: array
          title: Details
        source:
          type: string
          title: Source
        line:
          anyOf:
          - $ref: '#/components/schemas/EvidenceLine'
          - type: 'null'
      type: object
      required:
      - kind
      - label
      - status
      - basis
      - details
      - source
      title: EvidenceItem
      description: 'One checklist row: what was found, whether it needs a look, how it is known.'
    HealthRollupResponse:
      properties:
        status:
          type: string
          title: Status
        kind:
          type: string
          enum:
          - improved
          - worsened
          - mixed
          - neutral
          title: Kind
        scanned_commits:
          type: integer
          title: Scanned Commits
        unscanned_commits:
          type: integer
          title: Unscanned Commits
        introduced:
          type: integer
          title: Introduced
        worsened:
          type: integer
          title: Worsened
        resolved:
          type: integer
          title: Resolved
        improved:
          anyOf:
          - type: integer
          - type: 'null'
          title: Improved
        moved:
          anyOf:
          - type: integer
          - type: 'null'
          title: Moved
        files_improved:
          anyOf:
          - type: integer
          - type: 'null'
          title: Files Improved
        files_worsened:
          type: integer
          title: Files Worsened
      type: object
      required:
      - status
      - kind
      - scanned_commits
      - unscanned_commits
      - introduced
      - worsened
      - resolved
      - files_worsened
      title: HealthRollupResponse
      description: 'What a change''s commits did to health, summed.


        ``status`` is ``partial`` when a commit was not scanned or skipped files.

        Only rows from the current analyzer count; the rest are unscanned.

        ``files_worsened`` counts paths the stored worse findings name (a floor:

        findings are capped per commit). ``files_improved`` is null until stored

        deltas carry per-file scores.'
    ChangeListItem:
      properties:
        schema_version:
          type: integer
          title: Schema Version
        id:
          type: string
          title: Id
        identity:
          $ref: '#/components/schemas/ChangeIdentity'
        shape:
          type: string
          title: Shape
        forge:
          type: string
          title: Forge
        forge_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Forge Ref
        title:
          type: string
          title: Title
        merged_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Merged At
        head_sha:
          type: string
          title: Head Sha
        author:
          $ref: '#/components/schemas/ChangeAuthor'
        commit_count:
          type: integer
          title: Commit Count
        files_changed:
          type: integer
          title: Files Changed
        lines_added:
          type: integer
          title: Lines Added
        lines_deleted:
          type: integer
          title: Lines Deleted
        category:
          type: string
          title: Category
        provenance:
          anyOf:
          - $ref: '#/components/schemas/ChangeProvenance'
          - type: 'null'
        health:
          anyOf:
          - $ref: '#/components/schemas/HealthRollupResponse'
          - type: 'null'
        touches_hotspot:
          type: integer
          title: Touches Hotspot
          default: 0
        evidence_summary:
          anyOf:
          - $ref: '#/components/schemas/ChangeEvidenceSummary'
          - type: 'null'
      type: object
      required:
      - schema_version
      - id
      - identity
      - shape
      - forge
      - title
      - head_sha
      - author
      - commit_count
      - files_changed
      - lines_added
      - lines_deleted
      - category
      title: ChangeListItem
    EvidenceLine:
      properties:
        key:
          type: string
          title: Key
        params:
          additionalProperties: true
          type: object
          title: Params
      type: object
      required:
      - key
      - params
      title: EvidenceLine
      description: An item's value as a message key and its parameters, for a client to word.
    ChangeFile:
      properties:
        path:
          type: string
          title: Path
        added:
          type: integer
          title: Added
        deleted:
          type: integer
          title: Deleted
      type: object
      required:
      - path
      - added
      - deleted
      title: ChangeFile
    ChangeRecord:
      properties:
        schema_version:
          type: integer
          title: Schema Version
        id:
          type: string
          title: Id
        identity:
          $ref: '#/components/schemas/ChangeIdentity'
        shape:
          type: string
          title: Shape
        forge:
          type: string
          title: Forge
        forge_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Forge Ref
        title:
          type: string
          title: Title
        merged_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Merged At
        head_sha:
          type: string
          title: Head Sha
        author:
          $ref: '#/components/schemas/ChangeAuthor'
        commit_count:
          type: integer
          title: Commit Count
        files_changed:
          type: integer
          title: Files Changed
        lines_added:
          type: integer
          title: Lines Added
        lines_deleted:
          type: integer
          title: Lines Deleted
        category:
          type: string
          title: Category
        provenance:
          anyOf:
          - $ref: '#/components/schemas/ChangeProvenance'
          - type: 'null'
        health:
          anyOf:
          - $ref: '#/components/schemas/ChangeHealthResponse'
          - type: 'null'
        touches_hotspot:
          type: integer
          title: Touches Hotspot
          default: 0
        commits:
          items:
            type: string
          type: array
          title: Commits
        files:
          items:
            $ref: '#/components/schemas/ChangeFile'
          type: array
          title: Files
        metadata:
          $ref: '#/components/schemas/ChangeForgeMetadata'
        evidence:
          anyOf:
          - $ref: '#/components/schemas/ChangeEvidence'
          - type: 'null'
        evidence_building:
          type: boolean
          title: Evidence Building
          default: false
      type: object
      required:
      - schema_version
      - id
      - identity
      - shape
      - forge
      - title
      - head_sha
      - author
      - commit_count
      - files_changed
      - lines_added
      - lines_deleted
      - category
      - commits
      - files
      - metadata
      title: ChangeRecord
    PeriodHealthSummaryResponse:
      properties:
        since:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Since
        until:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Until
        total:
          type: integer
          title: Total
        improved:
          type: integer
          title: Improved
        mixed:
          type: integer
          title: Mixed
        worsened:
          type: integer
          title: Worsened
        neutral:
          type: integer
          title: Neutral
        unscanned:
          type: integer
          title: Unscanned
        findings_resolved:
          type: integer
          title: Findings Resolved
        findings_improved:
          anyOf:
          - type: integer
          - type: 'null'
          title: Findings Improved
        findings_introduced:
          type: integer
          title: Findings Introduced
        findings_worsened:
          type: integer
          title: Findings Worsened
        net_findings:
          type: integer
          title: Net Findings
      type: object
      required:
      - total
      - improved
      - mixed
      - worsened
      - neutral
      - unscanned
      - findings_resolved
      - findings_introduced
      - findings_worsened
      - net_findings
      title: PeriodHealthSummaryResponse
      description: 'A period headline: items that made health better first, then worse.


        Items are changes on ``/changes/summary`` and commits on

        ``/commits/health-summary``. ``unscanned`` items have no delta from the

        current analyzer ("not yet analysed") and are in none of the four kinds;

        recent commits refill as updates rescan them.'
    ChangeForgeMetadata:
      properties:
        source:
          anyOf:
          - type: string
          - type: 'null'
          title: Source
        reviewers:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Reviewers
        approvals:
          anyOf:
          - type: integer
          - type: 'null'
          title: Approvals
        labels:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Labels
        linked_issues:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Linked Issues
      type: object
      title: ChangeForgeMetadata
      description: Forge facts from a metadata source; ``None`` means unknown.
    ChangeHealthResponse:
      properties:
        status:
          type: string
          title: Status
        kind:
          type: string
          enum:
          - improved
          - worsened
          - mixed
          - neutral
          title: Kind
        scanned_commits:
          type: integer
          title: Scanned Commits
        unscanned_commits:
          type: integer
          title: Unscanned Commits
        introduced:
          type: integer
          title: Introduced
        worsened:
          type: integer
          title: Worsened
        resolved:
          type: integer
          title: Resolved
        improved:
          anyOf:
          - type: integer
          - type: 'null'
          title: Improved
        moved:
          anyOf:
          - type: integer
          - type: 'null'
          title: Moved
        files_improved:
          anyOf:
          - type: integer
          - type: 'null'
          title: Files Improved
        files_worsened:
          type: integer
          title: Files Worsened
        findings:
          items:
            $ref: '#/components/schemas/ChangeHealthFindingResponse'
          type: array
          title: Findings
      type: object
      required:
      - status
      - kind
      - scanned_commits
      - unscanned_commits
      - introduced
      - worsened
      - resolved
      - files_worsened
      title: ChangeHealthResponse
      description: 'A change''s health rollup plus its worse findings, worst first and

        capped: file, lines, symbol and biomarker, enough for a fix prompt.'
    SuspectsRequest:
      properties:
        symptom:
          type: string
          maxLength: 20000
          title: Symptom
          default: ''
        files:
          items:
            type: string
          type: array
          maxItems: 50
          title: Files
          default: []
        trace:
          type: string
          maxLength: 20000
          title: Trace
          default: ''
        since:
          anyOf:
          - type: string
          - type: 'null'
          title: Since
        until:
          anyOf:
          - type: string
          - type: 'null'
          title: Until
        limit:
          type: integer
          maximum: 200.0
          minimum: 1.0
          title: Limit
          default: 10
      type: object
      title: SuspectsRequest
      description: A symptom and the window to rank the changes merged in.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization