> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supermodeltools.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Circular dependency detection

> Upload a zipped repository snapshot to detect circular dependencies (dependency cycles) at the file level using Tarjan's strongly connected components algorithm.



## OpenAPI

````yaml /openapi.yaml post /v1/analysis/circular-dependencies
openapi: 3.0.0
info:
  title: Supermodel
  description: Code Graphing & Analysis API
  version: 0.9.6
  license:
    name: Supermodel API Terms of Service
    url: https://supermodeltools.com/legal/api-terms
servers:
  - url: https://api.supermodeltools.com
    description: Production server
security: []
tags:
  - name: Data Plane
    description: >-
      Calls the data plane to retrieve Supermodel analysis artifacts derived
      from repositories.
paths:
  /v1/analysis/circular-dependencies:
    post:
      tags:
        - Data Plane
      summary: Circular dependency detection
      description: >-
        Upload a zipped repository snapshot to detect circular dependencies
        (dependency cycles) at the file level using Tarjan's strongly connected
        components algorithm.
      operationId: generateCircularDependencyAnalysis
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - file
              properties:
                file:
                  type: string
                  format: binary
                  description: Zipped repository archive containing the code to analyze.
      responses:
        '200':
          description: Circular dependency analysis (job completed)
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-API-Version:
              $ref: '#/components/headers/X-API-Version'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            X-Usage-Units:
              $ref: '#/components/headers/X-Usage-Units'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircularDependencyResponseAsync'
              example:
                status: completed
                jobId: abc-123-def
                result:
                  metadata:
                    totalFiles: 142
                    totalImports: 487
                    cycleCount: 7
                    analysisMethod: tarjan_scc
                    analysisStartTime: '2026-02-09T12:00:00Z'
                    analysisEndTime: '2026-02-09T12:00:05Z'
                  cycles:
                    - id: cycle-1
                      severity: high
                      files:
                        - src/services/billingService.ts
                        - src/services/orderService.ts
                        - src/services/userService.ts
                      edges:
                        - source: src/services/userService.ts
                          target: src/services/orderService.ts
                          importedSymbols:
                            - getOrders
                            - OrderStatus
                        - source: src/services/orderService.ts
                          target: src/services/billingService.ts
                          importedSymbols:
                            - calculateTotal
                        - source: src/services/billingService.ts
                          target: src/services/userService.ts
                          importedSymbols:
                            - getUserDiscount
                      breakingSuggestion: >-
                        src/services/billingService.ts ->
                        src/services/userService.ts
                  summary:
                    totalCycles: 7
                    filesInCycles: 18
                    highSeverityCount: 2
                    mediumSeverityCount: 3
                    lowSeverityCount: 2
        '202':
          description: Job accepted and processing
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            X-API-Version:
              $ref: '#/components/headers/X-API-Version'
            Retry-After:
              description: Recommended wait time in seconds before polling again.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CircularDependencyResponseAsync'
              example:
                status: processing
                jobId: abc-123-def
                retryAfter: 5
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: >
            curl -X POST
            'https://api.supermodeltools.com/v1/analysis/circular-dependencies'
            \
              -H 'Idempotency-Key: <idempotency-key>' \
              -H 'X-Api-Key: <api-key>' \
              -F 'file=@/path/to/your/repo-snapshot.zip;type=application/zip'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      description: Unique identifier for this request for idempotency and tracing.
      schema:
        type: string
  headers:
    X-Request-Id:
      description: Unique request identifier echoed back from the Idempotency-Key header.
      schema:
        type: string
    X-API-Version:
      description: Semantic version of the API service handling the request.
      schema:
        type: string
    RateLimit-Limit:
      description: Maximum number of requests allowed in the current rate limit window.
      schema:
        type: integer
        format: int32
    RateLimit-Remaining:
      description: Remaining number of requests available in the current rate limit window.
      schema:
        type: integer
        format: int32
    RateLimit-Reset:
      description: UTC epoch seconds when the current rate limit window resets.
      schema:
        type: integer
        format: int64
    X-Usage-Units:
      description: Metered usage units consumed by this request.
      schema:
        type: number
        format: float
  schemas:
    CircularDependencyResponseAsync:
      allOf:
        - $ref: '#/components/schemas/JobStatus'
        - type: object
          description: Async response envelope for circular dependency analysis operations.
          properties:
            result:
              $ref: '#/components/schemas/CircularDependencyResponse'
              description: The result (present when status is completed).
    Error:
      type: object
      description: Standardized error payload returned by the API.
      required:
        - status
        - code
        - message
        - timestamp
      properties:
        status:
          type: integer
          format: int32
          description: HTTP status code associated with the error.
          minimum: 100
          maximum: 599
        code:
          type: string
          description: Stable, machine-readable error identifier.
        message:
          type: string
          description: Human-readable description of the error.
        timestamp:
          type: string
          format: date-time
          description: ISO-8601 timestamp indicating when the error occurred.
        requestId:
          type: string
          description: Correlation identifier for tracing the failing request.
        details:
          type: array
          description: Optional list of contextual error details.
          items:
            type: object
            required:
              - field
              - issue
            properties:
              field:
                type: string
                description: Name of the field or parameter related to the error.
              issue:
                type: string
                description: Description of the specific issue encountered.
              location:
                type: string
                description: Where the field resides (e.g., query, path, body).
    JobStatus:
      type: object
      description: Common fields for async job status tracking.
      required:
        - status
        - jobId
      properties:
        status:
          type: string
          description: Current status of the job.
          enum:
            - pending
            - processing
            - completed
            - failed
        jobId:
          type: string
          description: Unique identifier for the job.
        retryAfter:
          type: integer
          format: int32
          description: Recommended seconds to wait before polling again.
        error:
          type: string
          description: Error message (present when status is failed).
    CircularDependencyResponse:
      type: object
      description: >-
        Circular dependency analysis result containing detected cycles and
        summary.
      required:
        - metadata
        - cycles
        - summary
      properties:
        metadata:
          $ref: '#/components/schemas/CircularDependencyMetadata'
        cycles:
          type: array
          description: Detected dependency cycles.
          items:
            $ref: '#/components/schemas/CircularDependencyCycle'
        summary:
          $ref: '#/components/schemas/CircularDependencySummary'
    CircularDependencyMetadata:
      type: object
      description: Summary statistics for the circular dependency analysis.
      required:
        - totalFiles
        - totalImports
        - cycleCount
        - analysisMethod
      properties:
        totalFiles:
          type: integer
          format: int32
          description: Total number of files in the dependency graph.
        totalImports:
          type: integer
          format: int32
          description: Total number of import relationships.
        cycleCount:
          type: integer
          format: int32
          description: Number of cycles found.
        analysisMethod:
          type: string
          description: Algorithm used for cycle detection (e.g., tarjan_scc).
        analysisStartTime:
          type: string
          format: date-time
          description: Timestamp when analysis started.
        analysisEndTime:
          type: string
          format: date-time
          description: Timestamp when analysis completed.
    CircularDependencyCycle:
      type: object
      description: A single dependency cycle (strongly connected component).
      required:
        - id
        - files
        - edges
        - severity
      properties:
        id:
          type: string
          description: Unique identifier for this cycle (e.g., cycle-1).
        files:
          type: array
          description: Files involved in this cycle, sorted alphabetically.
          items:
            type: string
        edges:
          type: array
          description: Import edges that form this cycle.
          items:
            $ref: '#/components/schemas/CycleEdge'
        severity:
          type: string
          description: Severity of this cycle based on cross-directory span and size.
          enum:
            - low
            - medium
            - high
        breakingSuggestion:
          type: string
          description: Suggested edge to break to resolve this cycle.
    CircularDependencySummary:
      type: object
      description: Aggregate summary of circular dependency analysis.
      required:
        - totalCycles
        - filesInCycles
        - highSeverityCount
        - mediumSeverityCount
        - lowSeverityCount
      properties:
        totalCycles:
          type: integer
          format: int32
          description: Total number of cycles found.
        filesInCycles:
          type: integer
          format: int32
          description: Number of unique files involved in at least one cycle.
        highSeverityCount:
          type: integer
          format: int32
          description: Number of high-severity cycles.
        mediumSeverityCount:
          type: integer
          format: int32
          description: Number of medium-severity cycles.
        lowSeverityCount:
          type: integer
          format: int32
          description: Number of low-severity cycles.
    CycleEdge:
      type: object
      description: A directed import edge within a cycle.
      required:
        - source
        - target
        - importedSymbols
      properties:
        source:
          type: string
          description: File path of the importing file.
        target:
          type: string
          description: File path of the imported file.
        importedSymbols:
          type: array
          description: Symbols imported along this edge.
          items:
            type: string
  responses:
    BadRequest:
      description: The request could not be processed because of a client error.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-API-Version:
          $ref: '#/components/headers/X-API-Version'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Usage-Units:
          $ref: '#/components/headers/X-Usage-Units'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 400
            code: invalid_request
            message: Missing required query parameter 'repo'.
            timestamp: '2025-02-05 16:35:12.000000000 Z'
            requestId: req_01HZYJ9CE0ABCDEF1234
            details:
              - field: repo
                issue: This field is required.
                location: query
    Unauthorized:
      description: Authentication failed or was not provided.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-API-Version:
          $ref: '#/components/headers/X-API-Version'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Usage-Units:
          $ref: '#/components/headers/X-Usage-Units'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 401
            code: unauthorized
            message: Provide a valid OAuth token to access this resource.
            timestamp: '2025-02-05 16:35:12.000000000 Z'
            requestId: req_01HZYJ9CE0ABCDEFXYZ1
    Forbidden:
      description: The authenticated principal lacks the required permissions.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-API-Version:
          $ref: '#/components/headers/X-API-Version'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Usage-Units:
          $ref: '#/components/headers/X-Usage-Units'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 403
            code: forbidden
            message: The token lacks the required keys:write scope.
            timestamp: '2025-02-05 16:35:12.000000000 Z'
            requestId: req_01HZYJ9CE0ABCDEFFORB
    TooManyRequests:
      description: The rate limit for the resource has been exceeded.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-API-Version:
          $ref: '#/components/headers/X-API-Version'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Usage-Units:
          $ref: '#/components/headers/X-Usage-Units'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 429
            code: rate_limit_exceeded
            message: Too many requests. Try again after the reset window.
            timestamp: '2025-02-05 16:35:12.000000000 Z'
            requestId: req_01HZYJ9CE0ABCDEFRATE
    InternalError:
      description: The server encountered an unexpected condition.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
        X-API-Version:
          $ref: '#/components/headers/X-API-Version'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        X-Usage-Units:
          $ref: '#/components/headers/X-Usage-Units'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            status: 500
            code: internal_error
            message: Unexpected error processing request. Please retry.
            timestamp: '2025-02-05 16:35:12.000000000 Z'
            requestId: req_01HZYJ9CE0ABCDEFFAIL
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
      description: API key issued by the control plane for accessing data plane resources.

````