repowise-dev C4 API

openapi: 3.2.0
info:
  title: repowise C4 API
  description: REST API for repowise — codebase documentation engine
  version: 0.59.0
tags:
- name: c4
paths:
  /api/graph/{repo_id}/c4/l1:
    get:
      tags:
      - c4
      summary: Get C4 L1
      operationId: get_c4_l1_api_graph__repo_id__c4_l1_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/C4L1Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/graph/{repo_id}/c4/l2:
    get:
      tags:
      - c4
      summary: Get C4 L2
      operationId: get_c4_l2_api_graph__repo_id__c4_l2_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: co_changes
        in: query
        required: false
        schema:
          type: boolean
          description: Overlay co-change relations on the dependency edges
          default: false
          title: Co Changes
        description: Overlay co-change relations on the dependency edges
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/C4L2Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/graph/{repo_id}/c4/l3:
    get:
      tags:
      - c4
      summary: Get C4 L3
      operationId: get_c4_l3_api_graph__repo_id__c4_l3_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: container_id
        in: query
        required: true
        schema:
          type: string
          description: Container id from L2 (e.g., pkg:packages/core)
          title: Container Id
        description: Container id from L2 (e.g., pkg:packages/core)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/C4L3Response'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/graph/{repo_id}/c4/mermaid:
    get:
      tags:
      - c4
      summary: Get C4 Mermaid
      description: 'Mermaid C4 source for the requested level — paste into mermaid.live or

        embed in markdown. Same data source as the JSON endpoints, so what you

        see in the diagram view matches what you export.'
      operationId: get_c4_mermaid_api_graph__repo_id__c4_mermaid_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: level
        in: query
        required: false
        schema:
          type: integer
          maximum: 3
          minimum: 1
          description: 'C4 level: 1, 2, or 3'
          default: 2
          title: Level
        description: 'C4 level: 1, 2, or 3'
      - name: container_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Required when level=3
          title: Container Id
        description: Required when level=3
      responses:
        '200':
          description: Successful Response
          content:
            text/plain:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/graph/{repo_id}/c4/structurizr:
    get:
      tags:
      - c4
      summary: Get C4 Structurizr
      description: 'Structurizr DSL for this repository — open it in Structurizr Lite.


        By default this is the contents of a ``model`` block, meant to be included

        from the caller''s own ``workspace.dsl`` so their views and styles survive

        regeneration. ``standalone=true`` returns a workspace that renders on its

        own.


        Built on demand from the persisted graph, like the other C4 endpoints —

        nothing is written at index time.


        An unknown ``repo_id`` returns 200 and an empty-but-valid model rather

        than 404, matching the l1/l2/mermaid routes beside it: they all build from

        whatever rows the id matches, and none of them looks the repository up

        first. Deliberate rather than drift — a lone 404 here would make this the

        one C4 route with its own contract. The CLI does guard the case, because

        there a wrong path is a typo worth naming.'
      operationId: get_c4_structurizr_api_graph__repo_id__c4_structurizr_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: standalone
        in: query
        required: false
        schema:
          type: boolean
          description: Emit a complete runnable workspace instead of a model fragment
          default: false
          title: Standalone
        description: Emit a complete runnable workspace instead of a model fragment
      - name: components
        in: query
        required: false
        schema:
          type: boolean
          description: Include the component (L3) level
          default: false
          title: Components
        description: Include the component (L3) level
      - name: externals
        in: query
        required: false
        schema:
          type: boolean
          description: Include third-party dependencies
          default: true
          title: Externals
        description: Include third-party dependencies
      responses:
        '200':
          description: Successful Response
          content:
            text/plain:
              schema:
                type: string
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/graph/{repo_id}/architecture-view:
    get:
      tags:
      - c4
      summary: Get Architecture View
      operationId: get_architecture_view_api_graph__repo_id__architecture_view_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: include_symbols
        in: query
        required: false
        schema:
          type: boolean
          description: Include symbol-level nodes
          default: false
          title: Include Symbols
        description: Include symbol-level nodes
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ArchitectureViewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
  /api/graph/{repo_id}/zoom-map:
    get:
      tags:
      - c4
      summary: Get Zoom Map
      description: 'The continuous-zoom containment tree (system -> layer -> ... -> file).


        Derived on demand from the persisted graph, like the C4 views. ``focus`` +

        ``max_depth`` let the canvas fetch deeper subtrees lazily for large repos.'
      operationId: get_zoom_map_api_graph__repo_id__zoom_map_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: repo_id
        in: path
        required: true
        schema:
          type: string
          title: Repo Id
      - name: max_depth
        in: query
        required: false
        schema:
          anyOf:
          - type: integer
            minimum: 1
          - type: 'null'
          description: Cap levels served below the (focus) root; omit for full
          title: Max Depth
        description: Cap levels served below the (focus) root; omit for full
      - name: focus
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Node id to scope the served subtree to (lazy drill-down)
          title: Focus
        description: Node id to scope the served subtree to (lazy drill-down)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ZoomMapResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-repowise-stability: stable
components:
  schemas:
    C4L1Response:
      properties:
        system:
          $ref: '#/components/schemas/C4SystemResponse'
        people:
          items:
            $ref: '#/components/schemas/C4PersonResponse'
          type: array
          title: People
        external_systems:
          items:
            $ref: '#/components/schemas/C4ExternalSystemResponse'
          type: array
          title: External Systems
        relations:
          items:
            $ref: '#/components/schemas/C4RelationResponse'
          type: array
          title: Relations
      type: object
      required:
      - system
      - people
      - external_systems
      - relations
      title: C4L1Response
    ZoomNodeResponse:
      properties:
        id:
          type: string
          title: Id
        parent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Parent Id
        level:
          type: integer
          title: Level
        kind:
          type: string
          title: Kind
        name:
          type: string
          title: Name
        path:
          type: string
          title: Path
          default: ''
        children:
          items:
            type: string
          type: array
          title: Children
        importance:
          type: number
          title: Importance
          default: 0.0
        sibling_rank:
          type: integer
          title: Sibling Rank
          default: 0
        metrics:
          $ref: '#/components/schemas/ZoomMetricsResponse'
        summary:
          type: string
          title: Summary
          default: ''
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        page_id:
          type: string
          title: Page Id
          default: ''
        health_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Health Score
        is_entry_point:
          type: boolean
          title: Is Entry Point
          default: false
        is_hotspot:
          type: boolean
          title: Is Hotspot
          default: false
        is_dead:
          type: boolean
          title: Is Dead
          default: false
        is_test:
          type: boolean
          title: Is Test
          default: false
        on_flow:
          type: boolean
          title: On Flow
          default: false
      type: object
      required:
      - id
      - level
      - kind
      - name
      title: ZoomNodeResponse
    ArchSubGroupResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        node_ids:
          items:
            type: string
          type: array
          title: Node Ids
      type: object
      required:
      - id
      - name
      - node_ids
      title: ArchSubGroupResponse
    ArchEdgeResponse:
      properties:
        source:
          type: string
          title: Source
        target:
          type: string
          title: Target
        edge_type:
          type: string
          title: Edge Type
        direction:
          type: string
          title: Direction
        weight:
          type: number
          title: Weight
        confidence:
          type: number
          title: Confidence
      type: object
      required:
      - source
      - target
      - edge_type
      - direction
      - weight
      - confidence
      title: ArchEdgeResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ArchNodeResponse:
      properties:
        id:
          type: string
          title: Id
        node_type:
          type: string
          title: Node Type
        name:
          type: string
          title: Name
        file_path:
          anyOf:
          - type: string
          - type: 'null'
          title: File Path
        line_range:
          anyOf:
          - items:
              type: integer
            type: array
          - type: 'null'
          title: Line Range
        summary:
          type: string
          title: Summary
        complexity:
          type: string
          title: Complexity
        tags:
          items:
            type: string
          type: array
          title: Tags
        language:
          anyOf:
          - type: string
          - type: 'null'
          title: Language
        pagerank:
          type: number
          title: Pagerank
        pagerank_percentile:
          type: number
          title: Pagerank Percentile
        betweenness:
          type: number
          title: Betweenness
        in_degree:
          type: integer
          title: In Degree
        out_degree:
          type: integer
          title: Out Degree
        community_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Community Id
        is_entry_point:
          type: boolean
          title: Is Entry Point
        is_test:
          type: boolean
          title: Is Test
        is_hotspot:
          type: boolean
          title: Is Hotspot
        is_dead:
          type: boolean
          title: Is Dead
        has_doc:
          type: boolean
          title: Has Doc
        primary_owner:
          anyOf:
          - type: string
          - type: 'null'
          title: Primary Owner
        primary_owner_pct:
          anyOf:
          - type: number
          - type: 'null'
          title: Primary Owner Pct
        bus_factor:
          anyOf:
          - type: integer
          - type: 'null'
          title: Bus Factor
      type: object
      required:
      - id
      - node_type
      - name
      - file_path
      - line_range
      - summary
      - complexity
      - tags
      - language
      - pagerank
      - pagerank_percentile
      - betweenness
      - in_degree
      - out_degree
      - community_id
      - is_entry_point
      - is_test
      - is_hotspot
      - is_dead
      - has_doc
      - primary_owner
      - primary_owner_pct
      - bus_factor
      title: ArchNodeResponse
    C4RelationResponse:
      properties:
        source_id:
          type: string
          title: Source Id
        target_id:
          type: string
          title: Target Id
        label:
          type: string
          title: Label
          default: ''
        edge_count:
          type: integer
          title: Edge Count
          default: 1
        edge_types:
          items:
            type: string
          type: array
          title: Edge Types
        coupling:
          type: string
          title: Coupling
          default: ''
      type: object
      required:
      - source_id
      - target_id
      title: C4RelationResponse
    ZoomRelationResponse:
      properties:
        parent_id:
          type: string
          title: Parent Id
        source_id:
          type: string
          title: Source Id
        target_id:
          type: string
          title: Target Id
        label:
          type: string
          title: Label
          default: ''
        edge_count:
          type: integer
          title: Edge Count
          default: 1
        coupling:
          type: string
          title: Coupling
          default: ''
      type: object
      required:
      - parent_id
      - source_id
      - target_id
      title: ZoomRelationResponse
    C4ContainerResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        path:
          type: string
          title: Path
        language:
          type: string
          title: Language
        file_count:
          type: integer
          title: File Count
        symbol_count:
          type: integer
          title: Symbol Count
        hotspot_count:
          type: integer
          title: Hotspot Count
          default: 0
        dead_count:
          type: integer
          title: Dead Count
          default: 0
      type: object
      required:
      - id
      - name
      - path
      - language
      - file_count
      - symbol_count
      title: C4ContainerResponse
    C4L3Response:
      properties:
        container:
          $ref: '#/components/schemas/C4ContainerResponse'
        components:
          items:
            $ref: '#/components/schemas/C4ComponentResponse'
          type: array
          title: Components
        external_systems:
          items:
            $ref: '#/components/schemas/C4ExternalSystemResponse'
          type: array
          title: External Systems
        relations:
          items:
            $ref: '#/components/schemas/C4RelationResponse'
          type: array
          title: Relations
      type: object
      required:
      - container
      - components
      - external_systems
      - relations
      title: C4L3Response
    ArchTourStepResponse:
      properties:
        order:
          type: integer
          title: Order
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        node_ids:
          items:
            type: string
          type: array
          title: Node Ids
        target_path:
          anyOf:
          - type: string
          - type: 'null'
          title: Target Path
        layer_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Layer Id
        reason:
          type: string
          title: Reason
          default: ''
        depth:
          anyOf:
          - type: integer
          - type: 'null'
          title: Depth
        kind:
          type: string
          title: Kind
          default: ''
        page_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Page Type
      type: object
      required:
      - order
      - title
      - description
      - node_ids
      title: ArchTourStepResponse
    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
    ArchLayerResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
        node_ids:
          items:
            type: string
          type: array
          title: Node Ids
        file_count:
          type: integer
          title: File Count
        complexity_distribution:
          additionalProperties:
            type: integer
          type: object
          title: Complexity Distribution
        health_score:
          anyOf:
          - type: number
          - type: 'null'
          title: Health Score
        sub_groups:
          items:
            $ref: '#/components/schemas/ArchSubGroupResponse'
          type: array
          title: Sub Groups
          default: []
        display_order:
          type: integer
          title: Display Order
          default: 0
      type: object
      required:
      - id
      - name
      - description
      - node_ids
      - file_count
      - complexity_distribution
      - health_score
      title: ArchLayerResponse
    C4ExternalSystemResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        display_name:
          type: string
          title: Display Name
        category:
          type: string
          title: Category
        ecosystem:
          type: string
          title: Ecosystem
        version:
          anyOf:
          - type: string
          - type: 'null'
          title: Version
        io_kind:
          anyOf:
          - type: string
          - type: 'null'
          title: Io Kind
      type: object
      required:
      - id
      - name
      - display_name
      - category
      - ecosystem
      title: C4ExternalSystemResponse
    ZoomMetricsResponse:
      properties:
        file_count:
          type: integer
          title: File Count
          default: 0
        descendant_count:
          type: integer
          title: Descendant Count
          default: 0
        hotspot_count:
          type: integer
          title: Hotspot Count
          default: 0
        dead_count:
          type: integer
          title: Dead Count
          default: 0
        entry_point_count:
          type: integer
          title: Entry Point Count
          default: 0
        on_flow_count:
          type: integer
          title: On Flow Count
          default: 0
      type: object
      title: ZoomMetricsResponse
    C4ComponentResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        path:
          type: string
          title: Path
        container_id:
          type: string
          title: Container Id
        file_count:
          type: integer
          title: File Count
        symbol_count:
          type: integer
          title: Symbol Count
      type: object
      required:
      - id
      - name
      - path
      - container_id
      - file_count
      - symbol_count
      title: C4ComponentResponse
    ArchitectureViewResponse:
      properties:
        project_name:
          type: string
          title: Project Name
        project_description:
          type: string
          title: Project Description
        layers:
          items:
            $ref: '#/components/schemas/ArchLayerResponse'
          type: array
          title: Layers
        nodes:
          items:
            $ref: '#/components/schemas/ArchNodeResponse'
          type: array
          title: Nodes
        edges:
          items:
            $ref: '#/components/schemas/ArchEdgeResponse'
          type: array
          title: Edges
        tour:
          items:
            $ref: '#/components/schemas/ArchTourStepResponse'
          type: array
          title: Tour
        total_files:
          type: integer
          title: Total Files
        total_symbols:
          type: integer
          title: Total Symbols
        total_edges:
          type: integer
          title: Total Edges
        languages:
          items:
            type: string
          type: array
          title: Languages
        frameworks:
          items:
            type: string
          type: array
          title: Frameworks
        external_systems:
          items:
            $ref: '#/components/schemas/C4ExternalSystemResponse'
          type: array
          title: External Systems
        entry_points:
          items:
            type: string
          type: array
          title: Entry Points
          default: []
        entry_candidates:
          items:
            type: string
          type: array
          title: Entry Candidates
          default: []
      type: object
      required:
      - project_name
      - project_description
      - layers
      - nodes
      - edges
      - tour
      - total_files
      - total_symbols
      - total_edges
      - languages
      - frameworks
      - external_systems
      title: ArchitectureViewResponse
    C4SystemResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
          default: ''
      type: object
      required:
      - id
      - name
      title: C4SystemResponse
    C4L2Response:
      properties:
        containers:
          items:
            $ref: '#/components/schemas/C4ContainerResponse'
          type: array
          title: Containers
        external_systems:
          items:
            $ref: '#/components/schemas/C4ExternalSystemResponse'
          type: array
          title: External Systems
        relations:
          items:
            $ref: '#/components/schemas/C4RelationResponse'
          type: array
          title: Relations
      type: object
      required:
      - containers
      - external_systems
      - relations
      title: C4L2Response
    C4PersonResponse:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          type: string
          title: Description
          default: ''
        kind:
          type: string
          title: Kind
          default: user
      type: object
      required:
      - id
      - name
      title: C4PersonResponse
    ZoomMapResponse:
      properties:
        root_id:
          type: string
          title: Root Id
        project_name:
          type: string
          title: Project Name
        total_files:
          type: integer
          title: Total Files
        unclaimed_files:
          type: integer
          title: Unclaimed Files
          default: 0
        max_depth:
          type: integer
          title: Max Depth
        truncated:
          type: boolean
          title: Truncated
          default: false
        nodes:
          items:
            $ref: '#/components/schemas/ZoomNodeResponse'
          type: array
          title: Nodes
        relations:
          items:
            $ref: '#/components/schemas/ZoomRelationResponse'
          type: array
          title: Relations
      type: object
      required:
      - root_id
      - project_name
      - total_files
      - max_depth
      - nodes
      - relations
      title: ZoomMapResponse
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: Authorization