repowise-dev Episodes API

openapi: 3.2.0
info:
  title: repowise Episodes API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: episodes
paths:
  /api/repos/{repo_id}/episodes:
    get:
      tags:
      - episodes
      summary: List Episodes
      description: 'A page of episodes, newest first, without their bodies.


        Zero git calls by construction: the only currency shown is the one derived

        from stamps already in the row. Runs inline rather than on a worker thread

        because the work is two bounded SQLite reads, matching the other sidecar

        readers in this package; the detail route below is the one that threads,

        because it shells out. Bounded rather than indexed — there is no index on

        ``birth_at``, so each page sorts the filtered set in a temp b-tree, which

        the store''s own row cap is what makes affordable.'
      operationId: list_episodes_api_repos__repo_id__episodes_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: tier
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: 'Filter to one tier: structural | git'
          title: Tier
        description: 'Filter to one tier: structural | git'
      - name: kind
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter to one kind, e.g. code_fix
          title: Kind
        description: Filter to one kind, e.g. code_fix
      - 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
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
  /api/repos/{repo_id}/episodes/counts:
    get:
      tags:
      - episodes
      summary: Episode Counts
      description: 'Totals by tier and by kind.


        Declared above ``/{episode_id}`` deliberately: FastAPI matches in

        declaration order, so below it "counts" would be looked up as an episode

        id — the same trap the decisions router documents.'
      operationId: episode_counts_api_repos__repo_id__episodes_counts_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeCountsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
  /api/repos/{repo_id}/episodes/by-file:
    get:
      tags:
      - episodes
      summary: Episodes By File
      description: 'Episodes bound at, above or below *path*, newest first.


        Normally served through the store''s node index — 0.22 ms against 22 ms for

        a scan over the JSON scope column at the store''s row cap. ``total`` is the

        count for this path, which is what makes the number on a file page a

        measured one rather than the size of the window.


        **Threaded, unlike the other list routes, and the index is why.** When

        :meth:`~EpisodeStore._ensure_node_index` cannot build the index — a

        read-only database, a disk error — both reads silently fall back to a full

        scan. That path is the one thing here that can take tens of milliseconds,

        so it does not get to sit on the event loop; the store, not this route,

        decides which one runs.'
      operationId: episodes_by_file_api_repos__repo_id__episodes_by_file_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: path
        in: query
        required: true
        schema:
          type: string
          description: Repo-relative file or directory path
          title: Path
        description: Repo-relative file or directory path
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 20
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
  /api/repos/{repo_id}/episodes/{episode_id}:
    get:
      tags:
      - episodes
      summary: Get Episode
      description: 'One episode, whole, with the currency question actually asked of git.


        The only route here that spends a subprocess, and it spends exactly one.

        It runs on a worker thread for that reason — the convention this package

        already applies to every episode read that shells out.


        Two 404s with different wording, because this is the one route where the

        difference decides what a client does next: a repository with no episode

        store at all is a feature that has nothing here, while an unknown id on a

        populated store is a bad request worth not retrying. The list routes make

        the same distinction with ``available``, which a single-object response

        has no room for.'
      operationId: get_episode_api_repos__repo_id__episodes__episode_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: episode_id
        in: path
        required: true
        schema:
          type: string
          title: Episode Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EpisodeDetail'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: internal
components:
  schemas:
    EpisodeListResponse:
      properties:
        available:
          type: boolean
          title: Available
          default: true
        total:
          type: integer
          title: Total
          default: 0
        episodes:
          items:
            $ref: '#/components/schemas/EpisodeSummary'
          type: array
          title: Episodes
          default: []
      type: object
      title: EpisodeListResponse
      description: A page of summaries, with the measured total behind it.
    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
    EpisodeCountsResponse:
      properties:
        available:
          type: boolean
          title: Available
          default: true
        total:
          type: integer
          title: Total
          default: 0
        by_tier:
          additionalProperties:
            type: integer
          type: object
          title: By Tier
          default: {}
        by_kind:
          additionalProperties:
            type: integer
          type: object
          title: By Kind
          default: {}
      type: object
      title: EpisodeCountsResponse
      description: 'Counts by tier and by kind, from a grouped read of the same filters.


        Exists for the same reason the decision counts endpoint does: a page that

        counts its own rows reports the size of a window, not the size of a store.'
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    EpisodeDetail:
      properties:
        id:
          type: string
          title: Id
        tier:
          type: string
          title: Tier
        kind:
          type: string
          title: Kind
        subject:
          type: string
          title: Subject
        body:
          type: string
          title: Body
        evidence:
          type: string
          title: Evidence
        nodes:
          items:
            type: string
          type: array
          title: Nodes
        node_count:
          type: integer
          title: Node Count
        birth_commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Birth Commit
        birth_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Birth At
        last_seen_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Seen At
        still_true:
          type: string
          title: Still True
        current:
          type: boolean
          title: Current
      type: object
      required:
      - id
      - tier
      - kind
      - subject
      - body
      - evidence
      - nodes
      - node_count
      - birth_commit
      - birth_at
      - last_seen_at
      - still_true
      - current
      title: EpisodeDetail
      description: 'One episode, whole, with the currency question actually asked.


        ``current`` is the gate half of the verdict and ``still_true`` the sentence

        half. Both are served because they answer different questions: a reader

        asking *what happened here* wants the sentence even when the scope has

        moved, while anything putting a claim beside a statement about the present

        must respect the boolean.'
    EpisodeSummary:
      properties:
        id:
          type: string
          title: Id
        tier:
          type: string
          title: Tier
        kind:
          type: string
          title: Kind
        subject:
          type: string
          title: Subject
        evidence:
          type: string
          title: Evidence
        nodes:
          items:
            type: string
          type: array
          title: Nodes
        node_count:
          type: integer
          title: Node Count
        birth_commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Birth Commit
        birth_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Birth At
        last_seen_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Seen At
        still_true:
          anyOf:
          - type: string
          - type: 'null'
          title: Still True
      type: object
      required:
      - id
      - tier
      - kind
      - subject
      - evidence
      - nodes
      - node_count
      - birth_commit
      - birth_at
      - last_seen_at
      title: EpisodeSummary
      description: One timeline row. No body, and no git call was made to build it.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization