repowise-dev Repos API

openapi: 3.2.0
info:
  title: repowise Repos API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: Repos
paths:
  /api/repos:
    get:
      tags:
      - Repos
      summary: List Repos
      description: 'List all registered repositories.


        In workspace mode, aggregates indexed repos from the primary DB and

        every workspace repo DB, AND includes synthetic entries for

        workspace repos that haven''t been indexed yet (status="needs_index")

        or whose directory has gone missing (status="missing_dir"). This is

        what powers the web UI sidebar — silently dropping unindexed repos

        used to cause the "I only see the primary" Discord report.'
      operationId: list_repos_api_repos_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/RepoResponse'
                type: array
                title: Response List Repos Api Repos Get
      security:
      - APIKeyHeader: []
      x-repowise-stability: stable
    post:
      tags:
      - Repos
      summary: Create Repo
      description: 'Register a new repository (or update if same local_path exists).


        The repository''s data lives in its own ``/.repowise/wiki.db`` (the

        same store the CLI uses); the server''s primary database only keeps a

        registry row so the repo stays listed across restarts. With ``index``

        (the default) the first full index — docs included, when a provider is

        configured — is enqueued immediately; the created job''s id is returned

        as ``initial_job_id`` so clients can attach to its progress stream.'
      operationId: create_repo_api_repos_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RepoCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepoResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
      x-repowise-stability: stable
  /api/repos/summary:
    get:
      tags:
      - Repos
      summary: Repos Summary
      description: 'One-call payload for the multi-repo dashboard.


        Its cost does not grow with the number of repos. Declared **before**

        ``/{repo_id}``: FastAPI matches in declaration order.'
      operationId: repos_summary_api_repos_summary_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReposSummaryResponse'
      security:
      - APIKeyHeader: []
      x-repowise-stability: stable
  /api/repos/{repo_id}:
    get:
      tags:
      - Repos
      summary: Get Repo
      description: Get a single repository by ID.
      operationId: get_repo_api_repos__repo_id__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/RepoResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
    patch:
      tags:
      - Repos
      summary: Update Repo
      description: 'Update repository fields.


        ``exclude_patterns`` and ``wiki_style`` in ``settings`` go to the repo''s

        ``.repowise/config.yaml`` (where the CLI reads them), written first so a

        failed write leaves the row untouched.'
      operationId: update_repo_api_repos__repo_id__patch
      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/RepoUpdate'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RepoResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
    delete:
      tags:
      - Repos
      summary: Delete Repo
      description: Delete a repository and all its data.
      operationId: delete_repo_api_repos__repo_id__delete
      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/RepoDeletedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/stats:
    get:
      tags:
      - Repos
      summary: Get Repo Stats
      description: Get aggregate stats for a repository.
      operationId: get_repo_stats_api_repos__repo_id__stats_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/RepoStatsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/sync:
    post:
      tags:
      - Repos
      summary: Sync Repo
      description: 'Trigger an incremental documentation sync for a repository.


        Creates a generation job, launches the pipeline in the background,

        and returns immediately with the job ID.'
      operationId: sync_repo_api_repos__repo_id__sync_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAcceptedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/full-resync:
    post:
      tags:
      - Repos
      summary: Full Resync
      description: 'Trigger a full re-generation of all documentation.


        Creates a generation job, launches the pipeline in the background,

        and returns immediately with the job ID.'
      operationId: full_resync_api_repos__repo_id__full_resync_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAcceptedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/generate:
    post:
      tags:
      - Repos
      summary: Generate Pages
      description: 'Write a subset of the wiki with a model (the HTTP ``repowise generate``).


        Launches a background ``generate`` job that rehydrates the graph, resolves

        the requested selection + cascade, and writes exactly those pages via the

        shared core engine. Returns immediately with a job id to stream.'
      operationId: generate_pages_api_repos__repo_id__generate_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/GenerateRequestBody'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAcceptedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/generate/estimate:
    post:
      tags:
      - Repos
      summary: Generate Estimate
      description: 'Cost + page counts for a generate selection, including cascade fallout.


        Resolves the exact same scope the job would (rehydrating the graph and

        re-parsing), so the returned page count and estimate match what a launched

        job spends. Heavier than the pre-index preflight because it walks the real

        dependency graph rather than a file count. ``?provider=`` prices a

        provider the repo does not use yet, so a picker can show the cost first.'
      operationId: generate_estimate_api_repos__repo_id__generate_estimate_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: provider
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateRequestBody'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Generate Estimate Api Repos  Repo Id  Generate Estimate Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/index:
    post:
      tags:
      - Repos
      summary: Index Repo
      description: 'Run the first full index (docs included) for a registered repository.


        Unlike ``/sync`` and ``/full-resync``, this endpoint also establishes the

        repo-local database and writes the ``repowise init`` baseline

        (``state.json``, ``config.yaml``), so a repo that was merely registered

        becomes fully indexed and CLI-compatible. Safe to call on an already

        indexed repo — it behaves like a full rebuild.'
      operationId: index_repo_api_repos__repo_id__index_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobAcceptedResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/preflight:
    post:
      tags:
      - Repos
      summary: Preflight Index
      description: 'Pre-index readiness check: provider connectivity + rough cost estimate.


        Mirrors the CLI''s pre-generation gate — a live provider smoke test plus a

        page-count/cost estimate — so the UI can surface the expected spend and a

        broken API key *before* launching an index job. The estimate is derived

        from a fast file walk (no parsing), so page counts are approximate; the

        reported range absorbs the variance.'
      operationId: preflight_index_api_repos__repo_id__preflight_post
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: coverage_pct
        in: query
        required: false
        schema:
          type: number
          maximum: 1.0
          minimum: 0.0
          default: 0.2
          title: Coverage Pct
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Preflight Index Api Repos  Repo Id  Preflight Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/export:
    get:
      tags:
      - Repos
      summary: Export Wiki
      description: Export all wiki pages as a ZIP of markdown files with folder structure.
      operationId: export_wiki_api_repos__repo_id__export_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: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/file-content:
    get:
      tags:
      - Repos
      summary: Get File Content
      description: 'Return raw file content from the repository''s local checkout.


        Only files the indexer actually recorded are servable. Containment in the

        repo root is not a sufficient guard on its own: ``.repowise/.env`` (the

        user''s provider API keys) and ``.git/config`` live inside the root too, so

        the endpoint was an exfiltration path for anything under the checkout.'
      operationId: get_file_content_api_repos__repo_id__file_content_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: file_path
        in: query
        required: true
        schema:
          type: string
          title: File Path
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
components:
  schemas:
    RepoSummaryRow:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        local_path:
          type: string
          title: Local Path
        updated_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Updated At
        status:
          type: string
          title: Status
          default: indexed
        file_count:
          type: integer
          title: File Count
          default: 0
        symbol_count:
          type: integer
          title: Symbol Count
          default: 0
        entry_point_count:
          type: integer
          title: Entry Point Count
          default: 0
        doc_page_count:
          type: integer
          title: Doc Page Count
          default: 0
        doc_fresh_page_count:
          type: integer
          title: Doc Fresh Page Count
          default: 0
        dead_export_count:
          type: integer
          title: Dead Export Count
          default: 0
        tracked_file_count:
          type: integer
          title: Tracked File Count
          default: 0
        hotspot_count:
          type: integer
          title: Hotspot Count
          default: 0
        average_health:
          anyOf:
          - type: number
          - type: 'null'
          title: Average Health
        hotspot_health:
          anyOf:
          - type: number
          - type: 'null'
          title: Hotspot Health
        health_taken_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Health Taken At
        indexed_commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Indexed Commit
        live_head:
          anyOf:
          - type: string
          - type: 'null'
          title: Live Head
        index_behind:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Index Behind
      type: object
      required:
      - id
      - name
      - local_path
      title: RepoSummaryRow
      description: 'One repository''s headline figures, for the multi-repo dashboard.


        Every count here is a count of the thing its name says. ``file_count`` in

        particular is file nodes only: ``/stats`` counts every ``graph_nodes`` row,

        which on this repo is 38,813 against 3,600 actual files, because symbol

        nodes live in the same table.'
    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
    JobAcceptedResponse:
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
          default: accepted
        stream_token:
          type: string
          title: Stream Token
      type: object
      required:
      - job_id
      - stream_token
      title: JobAcceptedResponse
      description: 'The 202 payload every background-job launch returns.


        ``stream_token`` authorizes ``/api/jobs/{job_id}/stream`` directly, so a

        client can attach without a second round-trip or an API key in the query

        string.'
    ReposSummaryResponse:
      properties:
        repos:
          items:
            $ref: '#/components/schemas/RepoSummaryRow'
          type: array
          title: Repos
      type: object
      required:
      - repos
      title: ReposSummaryResponse
    RepoResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        url:
          type: string
          title: Url
        local_path:
          type: string
          title: Local Path
        default_branch:
          type: string
          title: Default Branch
        head_commit:
          anyOf:
          - type: string
          - type: 'null'
          title: Head Commit
        settings:
          additionalProperties: true
          type: object
          title: Settings
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        workspace_alias:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Alias
        workspace_status:
          anyOf:
          - type: string
          - type: 'null'
          title: Workspace Status
        is_primary:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Primary
        docs_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Docs Enabled
        docs_mode:
          anyOf:
          - type: string
            enum:
            - none
            - deterministic
            - llm
          - type: 'null'
          title: Docs Mode
        docs_skip_reason:
          anyOf:
          - type: string
          - type: 'null'
          title: Docs Skip Reason
        run_mode:
          anyOf:
          - type: string
          - type: 'null'
          title: Run Mode
        git_tier:
          anyOf:
          - type: string
          - type: 'null'
          title: Git Tier
        index_scope:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Index Scope
        initial_job_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Initial Job Id
      type: object
      required:
      - id
      - name
      - url
      - local_path
      - default_branch
      - head_commit
      - settings
      - created_at
      - updated_at
      title: RepoResponse
    RepoDeletedResponse:
      properties:
        ok:
          type: boolean
          title: Ok
          default: true
        deleted_pages:
          type: integer
          title: Deleted Pages
          default: 0
      type: object
      title: RepoDeletedResponse
      description: What a repository delete removed, for the confirmation toast.
    RepoCreate:
      properties:
        name:
          type: string
          title: Name
        local_path:
          type: string
          title: Local Path
        url:
          type: string
          title: Url
          default: ''
        default_branch:
          type: string
          title: Default Branch
          default: main
        settings:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Settings
        index:
          type: boolean
          title: Index
          default: true
      type: object
      required:
      - name
      - local_path
      title: RepoCreate
    GenerateSelectionBody:
      properties:
        kind:
          type: string
          enum:
          - all
          - unwritten
          - stale
          - page_ids
          - path_prefix
          - ranked
          title: Kind
          default: unwritten
        page_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Page Ids
        path_prefix:
          anyOf:
          - type: string
          - type: 'null'
          title: Path Prefix
        coverage_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Coverage Pct
        top_n:
          anyOf:
          - type: integer
          - type: 'null'
          title: Top N
      type: object
      title: GenerateSelectionBody
      description: "Which pages a generate request targets.\n\nTwo selection philosophies, kept distinct exactly as the CLI keeps them:\n\n- **Explicit**: ``all`` / ``unwritten`` / ``stale``, an explicit ``page_ids``\n  list, or every page under a ``path_prefix`` — the caller names the pages.\n- **Ranked** (``kind=\"ranked\"``): write the most important slice by the same\n  importance model ``repowise init`` uses, sized by ``coverage_pct`` (a\n  fraction in ``(0, 1]``; ``1.0`` == everything) or ``top_n`` (a target page\n  count, not exact). The two are mutually exclusive.\n\nThe two philosophies cannot be combined; :func:`_validate_generate_selection`\nenforces it with an actionable 400."
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    GenerateRequestBody:
      properties:
        selection:
          $ref: '#/components/schemas/GenerateSelectionBody'
        cascade:
          anyOf:
          - type: string
            enum:
            - none
            - dependents
            - full
          - type: 'null'
          title: Cascade
        style:
          anyOf:
          - type: string
          - type: 'null'
          title: Style
      type: object
      title: GenerateRequestBody
      description: 'Body for the generate + estimate endpoints.


        ``cascade`` is optional: left unset it resolves to ``none`` for a ranked

        selection (the ranked set is already a coherent slice) and ``dependents`` for

        an explicit one, matching the CLI ``generate`` defaults.'
    RepoUpdate:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
        url:
          anyOf:
          - type: string
          - type: 'null'
          title: Url
        default_branch:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Branch
        settings:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Settings
      type: object
      title: RepoUpdate
    RepoStatsResponse:
      properties:
        file_count:
          type: integer
          title: File Count
        symbol_count:
          type: integer
          title: Symbol Count
        entry_point_count:
          type: integer
          title: Entry Point Count
        doc_coverage_pct:
          type: number
          title: Doc Coverage Pct
        freshness_score:
          type: number
          title: Freshness Score
        dead_export_count:
          type: integer
          title: Dead Export Count
      type: object
      required:
      - file_count
      - symbol_count
      - entry_point_count
      - doc_coverage_pct
      - freshness_score
      - dead_export_count
      title: RepoStatsResponse
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization