repowise-dev Symbols API

openapi: 3.2.0
info:
  title: repowise Symbols API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: Symbols
paths:
  /api/symbols:
    get:
      tags:
      - Symbols
      summary: Search Symbols
      description: 'Search symbols by name/kind/language with importance-aware ranking.


        Importance sort is stable across pages: the server scores every symbol

        that matches the filters, sorts in Python (composite score is cheap),

        and returns the requested page. For very large symbol tables (>50k) the

        score should be persisted at index time — tracked as Phase 3 work.'
      operationId: search_symbols_api_symbols_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: query
        required: true
        schema:
          type: string
          description: Repository ID
          title: Repo Id
        description: Repository ID
      - name: q
        in: query
        required: false
        schema:
          type: string
          description: Search query (substring match on name)
          default: ''
          title: Q
        description: Search query (substring match on name)
      - name: kind
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by symbol kind
          title: Kind
        description: Filter by symbol kind
      - name: language
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by language
          title: Language
        description: Filter by language
      - name: visibility
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by visibility
          title: Visibility
        description: Filter by visibility
      - name: file_path
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by exact source file path (for hotspot drill-down)
          title: File Path
        description: Filter by exact source file path (for hotspot drill-down)
      - name: in_hot_files
        in: query
        required: false
        schema:
          type: boolean
          description: Only symbols whose file is a hotspot
          default: false
          title: In Hot Files
        description: Only symbols whose file is a hotspot
      - name: in_entry_points
        in: query
        required: false
        schema:
          type: boolean
          description: Only symbols in entry-point files
          default: false
          title: In Entry Points
        description: Only symbols in entry-point files
      - name: bug_fixed
        in: query
        required: false
        schema:
          type: boolean
          description: Only symbols with a counted bug fix
          default: false
          title: Bug Fixed
        description: Only symbols with a counted bug fix
      - name: sort
        in: query
        required: false
        schema:
          enum:
          - importance
          - name
          - complexity
          - kind
          type: string
          description: Sort key
          default: importance
          title: Sort
        description: Sort key
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          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/Paginated_SymbolResponse_'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/symbols/detail:
    get:
      tags:
      - Symbols
      summary: Symbol Detail
      description: 'Everything the symbol entity page renders, in one call.


        Symbol row + function blame + callers/callees + graph metrics +

        governing decisions + parent-file context.'
      operationId: symbol_detail_api_symbols_detail_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: query
        required: true
        schema:
          type: string
          description: Repository ID
          title: Repo Id
        description: Repository ID
      - name: symbol_id
        in: query
        required: true
        schema:
          type: string
          description: Symbol ID ({path}::{name})
          title: Symbol Id
        description: Symbol ID ({path}::{name})
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Symbol Detail Api Symbols Detail Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/symbols/by-name/{name}:
    get:
      tags:
      - Symbols
      summary: Lookup By Name
      description: 'Look up symbols by exact or fuzzy name match.


        Returns exact matches first, then LIKE matches, up to 10 results.'
      operationId: lookup_by_name_api_symbols_by_name__name__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
          title: Name
      - name: repo_id
        in: query
        required: true
        schema:
          type: string
          description: Repository ID
          title: Repo Id
        description: Repository ID
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SymbolResponse'
                title: Response Lookup By Name Api Symbols By Name  Name  Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/symbols/{symbol_db_id}:
    get:
      tags:
      - Symbols
      summary: Get Symbol
      description: Get a single symbol by its database ID.
      operationId: get_symbol_api_symbols__symbol_db_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: symbol_db_id
        in: path
        required: true
        schema:
          type: string
          title: Symbol Db Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SymbolResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
components:
  schemas:
    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
    Paginated_SymbolResponse_:
      properties:
        items:
          items:
            $ref: '#/components/schemas/SymbolResponse'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        has_more:
          type: boolean
          title: Has More
        next_offset:
          anyOf:
          - type: integer
          - type: 'null'
          title: Next Offset
      type: object
      required:
      - items
      - total
      - has_more
      title: Paginated[SymbolResponse]
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    SymbolResponse:
      properties:
        id:
          type: string
          title: Id
        repository_id:
          type: string
          title: Repository Id
        file_path:
          type: string
          title: File Path
        symbol_id:
          type: string
          title: Symbol Id
        name:
          type: string
          title: Name
        qualified_name:
          type: string
          title: Qualified Name
        kind:
          type: string
          title: Kind
        signature:
          type: string
          title: Signature
        start_line:
          type: integer
          title: Start Line
        end_line:
          type: integer
          title: End Line
        docstring:
          anyOf:
          - type: string
          - type: 'null'
          title: Docstring
        visibility:
          type: string
          title: Visibility
        is_async:
          type: boolean
          title: Is Async
        complexity_estimate:
          type: integer
          title: Complexity Estimate
        language:
          type: string
          title: Language
        parent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Name
        importance_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Importance Score
        importance_components:
          anyOf:
          - $ref: '#/components/schemas/SymbolImportanceComponents'
          - type: 'null'
        file_pagerank:
          anyOf:
          - type: number
          - type: 'null'
          title: File Pagerank
        is_entry_point:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Entry Point
        file_churn_percentile:
          anyOf:
          - type: number
          - type: 'null'
          title: File Churn Percentile
        file_is_hotspot:
          anyOf:
          - type: boolean
          - type: 'null'
          title: File Is Hotspot
        blame_mod_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Blame Mod Count
        blame_recent_mod_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Blame Recent Mod Count
        blame_median_author_time:
          anyOf:
          - type: integer
          - type: 'null'
          title: Blame Median Author Time
        blame_owner_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Blame Owner Name
        blame_owner_line_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Blame Owner Line Pct
        fix_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Fix Count
      type: object
      required:
      - id
      - repository_id
      - file_path
      - symbol_id
      - name
      - qualified_name
      - kind
      - signature
      - start_line
      - end_line
      - docstring
      - visibility
      - is_async
      - complexity_estimate
      - language
      - parent_name
      title: SymbolResponse
    SymbolImportanceComponents:
      properties:
        file_pagerank:
          type: number
          title: File Pagerank
          default: 0.0
        visibility_factor:
          type: number
          title: Visibility Factor
          default: 0.5
        complexity_norm:
          type: number
          title: Complexity Norm
          default: 0.0
        kind_boost:
          type: number
          title: Kind Boost
          default: 1.0
        is_entry_point:
          type: boolean
          title: Is Entry Point
          default: false
      type: object
      title: SymbolImportanceComponents
      description: 'Transparent breakdown of the composite importance score so the UI can

        explain *why* a symbol ranks where it does. All fields are normalized to

        [0, 1] except booleans.'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization