> ## 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.

# Dead code analysis

> Upload a zipped repository snapshot to identify dead (unreachable) code candidates by combining parse graph declarations with call graph relationships.



## OpenAPI

````yaml /openapi.yaml post /v1/analysis/dead-code
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/dead-code:
    post:
      tags:
        - Data Plane
      summary: Dead code analysis
      description: >-
        Upload a zipped repository snapshot to identify dead (unreachable) code
        candidates by combining parse graph declarations with call graph
        relationships.
      operationId: generateDeadCodeAnalysis
      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: Dead code 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/DeadCodeAnalysisResponseAsync'
              example:
                status: completed
                jobId: abc-123-def
                result:
                  metadata:
                    totalDeclarations: 162
                    deadCodeCandidates: 102
                    aliveCode: 60
                    analysisMethod: parse_graph + call_graph
                    analysisStartTime: '2025-02-05T15:42:05Z'
                    analysisEndTime: '2025-02-05T15:42:10Z'
                  deadCodeCandidates:
                    - file: src/utils/idGenerator.ts
                      name: generateSequentialId
                      line: 8
                      type: function
                      confidence: high
                      reason: No callers found in codebase
                  aliveCode:
                    - file: src/index.ts
                      name: main
                      line: 10
                      type: function
                      callerCount: 3
                  entryPoints:
                    - file: src/index.ts
                      name: main
                      line: 10
                      type: function
                      reason: Module export
        '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/DeadCodeAnalysisResponseAsync'
              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/dead-code'
            \
              -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:
    DeadCodeAnalysisResponseAsync:
      allOf:
        - $ref: '#/components/schemas/JobStatus'
        - type: object
          description: Async response envelope for dead code analysis operations.
          properties:
            result:
              $ref: '#/components/schemas/DeadCodeAnalysisResponse'
              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).
    DeadCodeAnalysisResponse:
      type: object
      description: Dead code analysis result containing candidates and alive code.
      required:
        - metadata
        - deadCodeCandidates
        - aliveCode
        - entryPoints
      properties:
        metadata:
          $ref: '#/components/schemas/DeadCodeAnalysisMetadata'
        deadCodeCandidates:
          type: array
          description: Code elements with no detected callers or references.
          items:
            $ref: '#/components/schemas/DeadCodeCandidate'
        aliveCode:
          type: array
          description: Code elements with at least one caller or reference.
          items:
            $ref: '#/components/schemas/AliveCodeItem'
        entryPoints:
          type: array
          description: Detected entry points (exports, route handlers, main functions).
          items:
            $ref: '#/components/schemas/EntryPoint'
    DeadCodeAnalysisMetadata:
      type: object
      description: Summary statistics for the dead code analysis.
      required:
        - totalDeclarations
        - deadCodeCandidates
        - aliveCode
        - analysisMethod
      properties:
        totalDeclarations:
          type: integer
          format: int64
          description: Total number of declarations (functions, classes, methods) analyzed.
        deadCodeCandidates:
          type: integer
          format: int64
          description: Number of dead code candidates found.
        aliveCode:
          type: integer
          format: int64
          description: Number of code elements with active references.
        rootFilesCount:
          type: integer
          format: int64
          description: >-
            Number of root files detected (files with no importers, used as
            entry points).
        transitiveDeadCount:
          type: integer
          format: int64
          description: >-
            Number of functions detected as dead via transitive propagation (all
            callers are dead).
        symbolLevelDeadCount:
          type: integer
          format: int64
          description: >-
            Number of exports detected as dead via symbol-level import analysis
            (exported but never imported by name).
        analysisMethod:
          type: string
          description: Method used for analysis (e.g., 'dependency_graph_reachability').
        analysisStartTime:
          type: string
          format: date-time
          description: Timestamp when analysis started.
        analysisEndTime:
          type: string
          format: date-time
          description: Timestamp when analysis completed.
    DeadCodeCandidate:
      type: object
      description: A code element identified as potentially dead (unreachable).
      required:
        - file
        - name
        - line
        - type
        - confidence
        - reason
      properties:
        file:
          type: string
          description: File path relative to repository root.
        name:
          type: string
          description: Name of the function, class, or method.
        line:
          type: integer
          format: int32
          description: Line number where the declaration starts.
        type:
          type: string
          description: Type of code element.
          enum:
            - function
            - class
            - method
            - interface
            - type
            - variable
            - constant
        confidence:
          type: string
          description: Confidence level of dead code detection.
          enum:
            - high
            - medium
            - low
        reason:
          type: string
          description: Explanation of why this was flagged as dead code.
    AliveCodeItem:
      type: object
      description: A code element with active callers or references.
      required:
        - file
        - name
        - line
        - type
        - callerCount
      properties:
        file:
          type: string
          description: File path relative to repository root.
        name:
          type: string
          description: Name of the function, class, or method.
        line:
          type: integer
          format: int32
          description: Line number where the declaration starts.
        type:
          type: string
          description: Type of code element.
          enum:
            - function
            - class
            - method
            - interface
            - type
            - variable
            - constant
        callerCount:
          type: integer
          format: int32
          description: Number of unique callers or references.
    EntryPoint:
      type: object
      description: A detected entry point that should not be flagged as dead code.
      required:
        - file
        - name
        - line
        - type
        - reason
      properties:
        file:
          type: string
          description: File path relative to repository root.
        name:
          type: string
          description: Name of the entry point.
        line:
          type: integer
          format: int32
          description: Line number where the entry point is declared.
        type:
          type: string
          description: Type of code element.
          enum:
            - function
            - class
            - method
            - interface
            - type
            - variable
            - constant
        reason:
          type: string
          description: >-
            Reason this is considered an entry point (e.g., 'Module export',
            'Route handler', 'Main function').
  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.

````