repowise-dev External Systems API

openapi: 3.2.0
info:
  title: repowise External Systems API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: external-systems
paths:
  /api/repos/{repo_id}/external-systems/summary:
    get:
      tags:
      - external-systems
      summary: Summarize External Systems
      description: Canonical packages joined to already-persisted import evidence.
      operationId: summarize_external_systems_api_repos__repo_id__external_systems_summary_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: scope
        in: query
        required: false
        schema:
          enum:
          - primary
          - all
          type: string
          default: primary
          title: Scope
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 400
          minimum: 1
          default: 200
          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/ExternalSystemsSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/external-systems/{package_key}/usage:
    get:
      tags:
      - external-systems
      summary: External System Usage
      description: 'Where a package is imported; *package_key* is ``ecosystem:name`` or a bare name.


        Reads the importing files from the local checkout for line numbers, so it

        needs one (a 404 says when there is none).'
      operationId: external_system_usage_api_repos__repo_id__external_systems__package_key__usage_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: package_key
        in: path
        required: true
        schema:
          type: string
          title: Package Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageUsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/external-systems/{package_key}/graph/files:
    get:
      tags:
      - external-systems
      summary: External System Importing Files
      description: Paginate importing files only after a relationship aggregate is opened.
      operationId: external_system_importing_files_api_repos__repo_id__external_systems__package_key__graph_files_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: package_key
        in: path
        required: true
        schema:
          type: string
          title: Package Key
      - name: aggregate_key
        in: query
        required: true
        schema:
          type: string
          title: Aggregate Key
      - name: scope
        in: query
        required: false
        schema:
          enum:
          - primary
          - all
          type: string
          default: primary
          title: Scope
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 25
          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/ExternalSystemImportingFilesResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/external-systems/{package_key}/graph:
    get:
      tags:
      - external-systems
      summary: External System Relationship Graph
      description: Show bounded first-party communities related to one declared package.
      operationId: external_system_relationship_graph_api_repos__repo_id__external_systems__package_key__graph_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: package_key
        in: path
        required: true
        schema:
          type: string
          title: Package Key
      - name: scope
        in: query
        required: false
        schema:
          enum:
          - primary
          - all
          type: string
          default: primary
          title: Scope
      - name: node_limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 50
          title: Node Limit
      - name: edge_limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 200
          title: Edge Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExternalSystemRelationshipGraphResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/repos/{repo_id}/external-systems:
    get:
      tags:
      - external-systems
      summary: List External Systems
      description: 'Every declared third-party dependency, unfiltered and undeduplicated.


        Unlike the C4 L1 view (which dedupes by name for the diagram boundary),

        this returns one row per (name, declared_in) so a monorepo''s per-package

        manifests stay distinguishable. Sorted by category prominence, then name.'
      operationId: list_external_systems_api_repos__repo_id__external_systems_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/ExternalSystemsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ExternalSystemImportingFile:
      properties:
        path:
          type: string
          title: Path
        language:
          type: string
          title: Language
        import_edge_count:
          type: integer
          title: Import Edge Count
        matched_external_node_count:
          type: integer
          title: Matched External Node Count
      type: object
      required:
      - path
      - language
      - import_edge_count
      - matched_external_node_count
      title: ExternalSystemImportingFile
    ExternalSystemEntry:
      properties:
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        ecosystem:
          type: string
          title: Ecosystem
        category:
          type: string
          title: Category
        io_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Io Kind
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        declared_in:
          type: string
          title: Declared In
        is_dev_dep:
          type: boolean
          title: Is Dev Dep
          default: false
      type: object
      required:
      - name
      - display_name
      - ecosystem
      - category
      - declared_in
      title: ExternalSystemEntry
      description: One declared third-party dependency.
    ExternalSystemRelationshipEdge:
      properties:
        source:
          type: string
          title: Source
        target:
          type: string
          title: Target
        import_edge_count:
          type: integer
          title: Import Edge Count
      type: object
      required:
      - source
      - target
      - import_edge_count
      title: ExternalSystemRelationshipEdge
    PackageUsageReachability:
      properties:
        state:
          type: string
          title: State
        basis:
          type: string
          title: Basis
      type: object
      required:
      - state
      - basis
      title: PackageUsageReachability
    ExternalSystemGraphTarget:
      properties:
        node_id:
          type: string
          title: Node Id
        match_basis:
          type: string
          enum:
          - exact
          - subpath
          - mapped
          title: Match Basis
      type: object
      required:
      - node_id
      - match_basis
      title: ExternalSystemGraphTarget
      description: One persisted external graph node linked to the selected package.
    PackageUsageDeclaration:
      properties:
        package_key:
          type: string
          title: Package Key
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        declared_in:
          type: string
          title: Declared In
        dev:
          type: boolean
          title: Dev
          default: false
      type: object
      required:
      - package_key
      - declared_in
      title: PackageUsageDeclaration
    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
    ExternalSystemsResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ExternalSystemEntry'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        prod_count:
          type: integer
          title: Prod Count
        dev_count:
          type: integer
          title: Dev Count
        ecosystems:
          items:
            type: string
          type: array
          title: Ecosystems
        manifests:
          items:
            type: string
          type: array
          title: Manifests
      type: object
      required:
      - items
      - total
      - prod_count
      - dev_count
      - ecosystems
      - manifests
      title: ExternalSystemsResponse
      description: The full dependency registry for a repository.
    ExternalSystemsSummaryResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/ExternalSystemSummaryEntry'
          type: array
          title: Items
        returned:
          type: integer
          title: Returned
        total_packages:
          type: integer
          title: Total Packages
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        truncated:
          type: boolean
          title: Truncated
        scope:
          type: string
          enum:
          - primary
          - all
          title: Scope
        excluded_declarations:
          type: integer
          title: Excluded Declarations
        total_declarations:
          type: integer
          title: Total Declarations
        runtime_packages:
          type: integer
          title: Runtime Packages
        dev_only_packages:
          type: integer
          title: Dev Only Packages
        observed_packages:
          type: integer
          title: Observed Packages
        linked_packages:
          type: integer
          title: Linked Packages
        unlinked_packages:
          type: integer
          title: Unlinked Packages
        linked_without_imports:
          type: integer
          title: Linked Without Imports
        ecosystems:
          items:
            type: string
          type: array
          title: Ecosystems
        manifest_count:
          type: integer
          title: Manifest Count
      type: object
      required:
      - items
      - returned
      - total_packages
      - limit
      - offset
      - truncated
      - scope
      - excluded_declarations
      - total_declarations
      - runtime_packages
      - dev_only_packages
      - observed_packages
      - linked_packages
      - unlinked_packages
      - linked_without_imports
      - ecosystems
      - manifest_count
      title: ExternalSystemsSummaryResponse
      description: Bounded package summaries for the external-dependency scan surface.
    PackageUsageModule:
      properties:
        name:
          type: string
          title: Name
        mapping:
          type: string
          enum:
          - declared
          - inferred
          title: Mapping
      type: object
      required:
      - name
      - mapping
      title: PackageUsageModule
      description: One module the file imports and how it was matched to the package.
    PackageUsageSite:
      properties:
        path:
          type: string
          title: Path
        modules:
          items:
            $ref: '#/components/schemas/PackageUsageModule'
          type: array
          title: Modules
        symbols:
          items:
            type: string
          type: array
          title: Symbols
        mapping:
          type: string
          enum:
          - declared
          - inferred
          title: Mapping
        line:
          anyOf:
          - type: integer
          - type: 'null'
          title: Line
        statement:
          anyOf:
          - type: string
          - type: 'null'
          title: Statement
        component:
          anyOf:
          - type: string
          - type: 'null'
          title: Component
        owners:
          items:
            type: string
          type: array
          title: Owners
        owner_counts:
          anyOf:
          - additionalProperties:
              type: integer
            type: object
          - type: 'null'
          title: Owner Counts
        reachability:
          $ref: '#/components/schemas/PackageUsageReachability'
      type: object
      required:
      - path
      - modules
      - symbols
      - mapping
      - owners
      - reachability
      title: PackageUsageSite
      description: One file importing the package.
    PackageUsageResponse:
      properties:
        package:
          type: string
          title: Package
        ecosystem:
          anyOf:
          - type: string
          - type: 'null'
          title: Ecosystem
        declared:
          items:
            $ref: '#/components/schemas/PackageUsageDeclaration'
          type: array
          title: Declared
        summary:
          $ref: '#/components/schemas/PackageUsageSummary'
        sites:
          items:
            $ref: '#/components/schemas/PackageUsageSite'
          type: array
          title: Sites
        components:
          items:
            $ref: '#/components/schemas/PackageUsageComponent'
          type: array
          title: Components
        method:
          additionalProperties:
            type: string
          type: object
          title: Method
        note:
          anyOf:
          - type: string
          - type: 'null'
          title: Note
      type: object
      required:
      - package
      - declared
      - summary
      - sites
      - components
      - method
      title: PackageUsageResponse
      description: 'Where one package is imported: sites, components, owner teams, reachability.'
    ExternalSystemRelationshipNode:
      properties:
        aggregate_key:
          type: string
          title: Aggregate Key
        label:
          type: string
          title: Label
        community_id:
          type: integer
          title: Community Id
        importing_file_count:
          type: integer
          title: Importing File Count
        import_edge_count:
          type: integer
          title: Import Edge Count
        top_file:
          anyOf:
          - type: string
          - type: 'null'
          title: Top File
      type: object
      required:
      - aggregate_key
      - label
      - community_id
      - importing_file_count
      - import_edge_count
      title: ExternalSystemRelationshipNode
      description: A first-party graph community that imports the selected package.
    PackageUsageComponent:
      properties:
        name:
          type: string
          title: Name
        files:
          type: integer
          title: Files
        owners:
          items:
            type: string
          type: array
          title: Owners
      type: object
      required:
      - name
      - files
      - owners
      title: PackageUsageComponent
    ExternalSystemRelationshipGraphResponse:
      properties:
        package_key:
          type: string
          title: Package Key
        package_name:
          type: string
          title: Package Name
        package_node_id:
          type: string
          title: Package Node Id
        match_basis:
          type: string
          enum:
          - exact
          - subpath
          - mapped
          - mixed
          - unresolved
          title: Match Basis
        matched_external_nodes:
          items:
            $ref: '#/components/schemas/ExternalSystemGraphTarget'
          type: array
          title: Matched External Nodes
        matched_external_nodes_total:
          type: integer
          title: Matched External Nodes Total
        matched_external_nodes_truncated:
          type: boolean
          title: Matched External Nodes Truncated
        evidence_target_limit:
          type: integer
          title: Evidence Target Limit
        evidence_truncated:
          type: boolean
          title: Evidence Truncated
        nodes:
          items:
            $ref: '#/components/schemas/ExternalSystemRelationshipNode'
          type: array
          title: Nodes
        edges:
          items:
            $ref: '#/components/schemas/ExternalSystemRelationshipEdge'
          type: array
          title: Edges
        aggregate_total:
          type: integer
          title: Aggregate Total
        aggregate_returned:
          type: integer
          title: Aggregate Returned
        edge_total:
          type: integer
          title: Edge Total
        edge_returned:
          type: integer
          title: Edge Returned
        importing_file_total:
          type: integer
          title: Importing File Total
        import_edge_total:
          type: integer
          title: Import Edge Total
        node_limit:
          type: integer
          title: Node Limit
        edge_limit:
          type: integer
          title: Edge Limit
        truncated:
          type: boolean
          title: Truncated
        scope:
          type: string
          enum:
          - primary
          - all
          title: Scope
      type: object
      required:
      - package_key
      - package_name
      - package_node_id
      - match_basis
      - matched_external_nodes
      - matched_external_nodes_total
      - matched_external_nodes_truncated
      - evidence_target_limit
      - evidence_truncated
      - nodes
      - edges
      - aggregate_total
      - aggregate_returned
      - edge_total
      - edge_returned
      - importing_file_total
      - import_edge_total
      - node_limit
      - edge_limit
      - truncated
      - scope
      title: ExternalSystemRelationshipGraphResponse
      description: Bounded aggregate-first relationship graph for one declared package.
    PackageUsageSummary:
      properties:
        files:
          type: integer
          title: Files
        components:
          type: integer
          title: Components
        reachability:
          additionalProperties:
            type: integer
          type: object
          title: Reachability
        inferred_files:
          type: integer
          title: Inferred Files
      type: object
      required:
      - files
      - components
      - reachability
      - inferred_files
      title: PackageUsageSummary
    ExternalSystemImportingFilesResponse:
      properties:
        package_key:
          type: string
          title: Package Key
        aggregate_key:
          type: string
          title: Aggregate Key
        items:
          items:
            $ref: '#/components/schemas/ExternalSystemImportingFile'
          type: array
          title: Items
        total:
          type: integer
          title: Total
        returned:
          type: integer
          title: Returned
        limit:
          type: integer
          title: Limit
        offset:
          type: integer
          title: Offset
        truncated:
          type: boolean
          title: Truncated
        scope:
          type: string
          enum:
          - primary
          - all
          title: Scope
      type: object
      required:
      - package_key
      - aggregate_key
      - items
      - total
      - returned
      - limit
      - offset
      - truncated
      - scope
      title: ExternalSystemImportingFilesResponse
      description: One independently bounded page of files behind an aggregate node.
    ExternalSystemSummaryEntry:
      properties:
        package_key:
          type: string
          title: Package Key
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        ecosystem:
          type: string
          title: Ecosystem
        category:
          type: string
          title: Category
        io_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Io Kind
        runtime_declared:
          type: boolean
          title: Runtime Declared
        dev_declared:
          type: boolean
          title: Dev Declared
        declaration_count:
          type: integer
          title: Declaration Count
        manifest_count:
          type: integer
          title: Manifest Count
        versions:
          items:
            type: string
          type: array
          title: Versions
        versions_total:
          type: integer
          title: Versions Total
        versions_truncated:
          type: boolean
          title: Versions Truncated
        multiple_versions:
          type: boolean
          title: Multiple Versions
        external_node_count:
          type: integer
          title: External Node Count
        import_edge_count:
          type: integer
          title: Import Edge Count
        importing_file_count:
          type: integer
          title: Importing File Count
        link_state:
          type: string
          enum:
          - linked
          - unlinked
          title: Link State
      type: object
      required:
      - package_key
      - name
      - display_name
      - ecosystem
      - category
      - runtime_declared
      - dev_declared
      - declaration_count
      - manifest_count
      - versions
      - versions_total
      - versions_truncated
      - multiple_versions
      - external_node_count
      - import_edge_count
      - importing_file_count
      - link_state
      title: ExternalSystemSummaryEntry
      description: One canonical package with declaration and graph-usage aggregates.
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization