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

# Gaps



## OpenAPI

````yaml /openapi.json post /v1/workspaces/{workspaceId}/projects/{projectId}/budget-analysis/gaps/query
openapi: 3.1.0
info:
  title: Specurate API
  description: ''
  version: 1.0.0
  contact: {}
servers:
  - url: https://app.specurate.com/api
    description: API Server
security: []
tags: []
paths:
  /v1/workspaces/{workspaceId}/projects/{projectId}/budget-analysis/gaps/query:
    post:
      tags:
        - Budget Analysis
      summary: Gaps
      operationId: BudgetAnalysisController_gaps_v1
      parameters:
        - name: workspaceId
          required: true
          in: path
          schema:
            type: string
            pattern: ^[1-9]\d{0,18}$
        - name: projectId
          required: true
          in: path
          schema:
            type: string
            pattern: ^[1-9]\d{0,18}$
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BudgetAnalysisGapQueryDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetAnalysisGapResponseDto'
      security:
        - bearer: []
components:
  schemas:
    BudgetAnalysisGapQueryDto:
      type: object
      properties:
        budgetVersion:
          anyOf:
            - type: string
              enum:
                - live
            - type: string
              pattern: ^[1-9]\d{0,18}$
        origin:
          type: string
          enum:
            - pricing
        scopeKey:
          anyOf:
            - type: string
              enum:
                - project:total
            - type: string
              enum:
                - goods:total
            - type: string
              enum:
                - soft-cost:total
            - type: string
              pattern: ^category:[1-9]\d{0,18}$
            - type: string
              enum:
                - category:none
            - type: string
              pattern: ^supplier:[1-9]\d{0,18}$
            - type: string
              enum:
                - supplier:none
            - type: string
              pattern: ^department:[1-9]\d{0,18}$
            - type: string
              enum:
                - department:none
            - type: string
              pattern: ^item:[1-9]\d{0,18}$
            - type: string
              pattern: ^soft-cost:[1-9]\d{0,18}$
            - type: string
              maxLength: 100
              pattern: ^soft-cost-family:[a-z][a-z0-9_-]*$
        comparison:
          type: string
          enum:
            - planning_itemized
            - planning_specified
            - planning_purchase
            - itemized_specified
            - itemized_purchase
            - specified_purchase
            - default_effective
            - margin_specified
            - margin_purchase
        side:
          type: string
          enum:
            - cost
            - client
        issue:
          type: string
          enum:
            - overrun
            - incomplete
            - shortfall
        filters:
          type: object
          properties:
            categoryIds:
              maxItems: 200
              type: array
              items:
                type: string
                pattern: ^[1-9]\d{0,18}$
            supplierCompanyIds:
              maxItems: 200
              type: array
              items:
                type: string
                pattern: ^[1-9]\d{0,18}$
            areaIds:
              maxItems: 200
              type: array
              items:
                type: string
                pattern: ^[1-9]\d{0,18}$
          additionalProperties: false
        cursor:
          type: string
          minLength: 1
          maxLength: 2048
        limit:
          default: 20
          type: integer
          minimum: 1
          maximum: 100
        expectedComparison:
          type: object
          properties:
            baseline:
              anyOf:
                - type: string
                  maxLength: 100
                  pattern: ^-?\d+(?:\.\d+)?$
                - type: 'null'
            compared:
              anyOf:
                - type: string
                  maxLength: 100
                  pattern: ^-?\d+(?:\.\d+)?$
                - type: 'null'
          required:
            - baseline
            - compared
          additionalProperties: false
        expectedRevision:
          type: string
          pattern: ^[A-Za-z0-9_-]{43}$
      required:
        - budgetVersion
        - scopeKey
        - comparison
        - side
      additionalProperties: false
    BudgetAnalysisGapResponseDto:
      type: object
      properties:
        budgetVersion:
          $ref: '#/components/schemas/BudgetAnalysisVersionDto'
        scope:
          $ref: '#/components/schemas/BudgetAnalysisInsightDto'
        comparison:
          type: string
          enum:
            - planning_itemized
            - planning_specified
            - planning_purchase
            - itemized_specified
            - itemized_purchase
            - specified_purchase
            - default_effective
            - margin_specified
            - margin_purchase
        side:
          type: string
          enum:
            - cost
            - client
        summary:
          $ref: '#/components/schemas/BudgetAnalysisComparisonValueDto'
        items:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisGapContributorDto'
        matchedCount:
          type: number
        totalCount:
          type: number
        nextCursor:
          type:
            - string
            - 'null'
        hasMore:
          type: boolean
        computedAt:
          type: string
        freshness:
          type: string
          enum:
            - live
        revision:
          type: string
        changed:
          type: boolean
        reconciliation:
          $ref: '#/components/schemas/BudgetAnalysisGapReconciliationDto'
      required:
        - budgetVersion
        - scope
        - comparison
        - side
        - summary
        - items
        - matchedCount
        - totalCount
        - nextCursor
        - hasMore
        - computedAt
        - freshness
        - revision
        - changed
        - reconciliation
    BudgetAnalysisVersionDto:
      type: object
      properties:
        kind:
          type: string
          enum:
            - live
            - released
        id:
          type:
            - string
            - 'null'
        number:
          type:
            - number
            - 'null'
        releasedAt:
          type:
            - string
            - 'null'
      required:
        - kind
        - id
        - number
        - releasedAt
    BudgetAnalysisInsightDto:
      type: object
      properties:
        comparisons:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BudgetAnalysisComparisonSidesDto'
        key:
          type: string
        label:
          type:
            - string
            - 'null'
        coverage:
          $ref: '#/components/schemas/BudgetAnalysisCoverageDto'
        margin:
          $ref: '#/components/schemas/BudgetAnalysisMarginsDto'
        effectiveSoftCostEstimate:
          type:
            - string
            - 'null'
        revision:
          type: string
      required:
        - comparisons
        - key
        - label
        - coverage
        - revision
    BudgetAnalysisComparisonValueDto:
      type: object
      properties:
        baseline:
          type:
            - string
            - 'null'
        compared:
          type:
            - string
            - 'null'
        variance:
          anyOf:
            - $ref: '#/components/schemas/BudgetAnalysisVarianceDto'
            - type: 'null'
        state:
          type: string
          enum:
            - incomplete
            - unavailable
            - available
        adverse:
          type: boolean
      required:
        - baseline
        - compared
        - variance
        - state
        - adverse
    BudgetAnalysisGapContributorDto:
      type: object
      properties:
        decomposition:
          $ref: '#/components/schemas/BudgetAnalysisDecompositionDto'
        margin:
          $ref: '#/components/schemas/BudgetAnalysisMarginsDto'
        coverage:
          $ref: '#/components/schemas/BudgetAnalysisCoverageDto'
        inputs:
          $ref: '#/components/schemas/BudgetAnalysisGapInputsDto'
        key:
          type: string
        slotId:
          type: string
        projectItemId:
          type:
            - string
            - 'null'
        label:
          type:
            - string
            - 'null'
        refNumber:
          type:
            - string
            - 'null'
        categoryId:
          type:
            - string
            - 'null'
        supplierName:
          type:
            - string
            - 'null'
        baseline:
          type:
            - string
            - 'null'
        compared:
          type:
            - string
            - 'null'
        contribution:
          type: string
        contributionPct:
          type:
            - string
            - 'null'
        state:
          type: string
          enum:
            - incomplete
            - unavailable
            - available
        adverse:
          type: boolean
        quantities:
          $ref: '#/components/schemas/BudgetAnalysisGapQuantitiesDto'
        softCosts:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisGapSoftCostDto'
      required:
        - decomposition
        - coverage
        - inputs
        - key
        - slotId
        - projectItemId
        - label
        - refNumber
        - categoryId
        - supplierName
        - baseline
        - compared
        - contribution
        - contributionPct
        - state
        - adverse
        - quantities
        - softCosts
    BudgetAnalysisGapReconciliationDto:
      type: object
      properties:
        allowance:
          type:
            - string
            - 'null'
        contributionTotal:
          type: string
        grossAdverse:
          type: string
        favorableOffsets:
          type: string
        matchingContributionTotal:
          type: string
        pageContributionTotal:
          type: string
        otherContributionTotal:
          type: string
      required:
        - allowance
        - contributionTotal
        - grossAdverse
        - favorableOffsets
        - matchingContributionTotal
        - pageContributionTotal
        - otherContributionTotal
    BudgetAnalysisComparisonSidesDto:
      type: object
      properties:
        cost:
          $ref: '#/components/schemas/BudgetAnalysisComparisonValueDto'
        client:
          $ref: '#/components/schemas/BudgetAnalysisComparisonValueDto'
    BudgetAnalysisCoverageDto:
      type: object
      properties:
        lineCount:
          type: number
        budgetGapCount:
          type: number
        costGapCount:
          type: number
        clientGapCount:
          type: number
        incompleteInputCount:
          type: number
        purchasingShortfallCount:
          type: number
        installedShortfallCount:
          type: number
        requiredStockShortfallCount:
          type: number
      required:
        - lineCount
        - purchasingShortfallCount
        - installedShortfallCount
        - requiredStockShortfallCount
    BudgetAnalysisMarginsDto:
      type: object
      properties:
        specified:
          $ref: '#/components/schemas/BudgetAnalysisMarginDto'
        purchase:
          $ref: '#/components/schemas/BudgetAnalysisMarginDto'
      required:
        - specified
        - purchase
    BudgetAnalysisVarianceDto:
      type: object
      properties:
        amount:
          type: string
        pct:
          type:
            - string
            - 'null'
      required:
        - amount
        - pct
    BudgetAnalysisDecompositionDto:
      type: object
      properties:
        state:
          type: string
          enum:
            - incomplete
            - unavailable
            - available
        baseline:
          type:
            - string
            - 'null'
        compared:
          type:
            - string
            - 'null'
        steps:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisDecompositionStepDto'
      required:
        - state
        - baseline
        - compared
        - steps
    BudgetAnalysisGapInputsDto:
      type: object
      properties:
        budgetPrice:
          type:
            - string
            - 'null'
        budgetQuantity:
          type:
            - string
            - 'null'
        unitCost:
          type:
            - string
            - 'null'
        unitClient:
          type:
            - string
            - 'null'
        unitsPerPackage:
          type:
            - string
            - 'null'
      required:
        - unitsPerPackage
    BudgetAnalysisGapQuantitiesDto:
      type: object
      properties:
        specified:
          type: string
        specifiedOrder:
          type:
            - string
            - 'null'
        purchase:
          type:
            - string
            - 'null'
        purchasedUnits:
          type:
            - string
            - 'null'
        shortfall:
          type: string
        requiredUnits:
          type: string
        requiredStockShortfall:
          type: string
        additionalOrderQuantity:
          type:
            - string
            - 'null'
        parLevel:
          type:
            - string
            - 'null'
        applyParToPurchaseQuantity:
          type: boolean
        extraQuantity:
          type: string
        purchasingUnit:
          type: string
          enum:
            - packages
            - units
      required:
        - specified
        - specifiedOrder
        - purchase
        - purchasedUnits
        - shortfall
        - requiredUnits
        - requiredStockShortfall
        - additionalOrderQuantity
        - parLevel
        - applyParToPurchaseQuantity
        - extraQuantity
        - purchasingUnit
    BudgetAnalysisGapSoftCostDto:
      type: object
      properties:
        id:
          type: string
        label:
          type: string
        source:
          type: string
          enum:
            - override
            - category
        mode:
          enum:
            - percentage
            - amount
            - excluded
          type: string
        rate:
          type:
            - string
            - 'null'
        defaultRate:
          type:
            - string
            - 'null'
        fixedAmount:
          type:
            - string
            - 'null'
        defaultEstimate:
          type:
            - string
            - 'null'
        effectiveEstimate:
          type:
            - string
            - 'null'
        budgetBasis:
          type:
            - string
            - 'null'
        specifiedBasis:
          type:
            - string
            - 'null'
        purchaseBasis:
          type:
            - string
            - 'null'
        specified:
          type:
            - string
            - 'null'
        purchase:
          type:
            - string
            - 'null'
      required:
        - id
        - label
        - source
        - mode
    BudgetAnalysisMarginDto:
      type: object
      properties:
        client:
          type:
            - string
            - 'null'
        cost:
          type:
            - string
            - 'null'
        profit:
          type:
            - string
            - 'null'
        marginPct:
          type:
            - string
            - 'null'
        targetPct:
          type:
            - string
            - 'null'
        belowTarget:
          type: boolean
        state:
          type: string
          enum:
            - incomplete
            - unavailable
            - available
      required:
        - client
        - cost
        - profit
        - marginPct
        - targetPct
        - belowTarget
        - state
    BudgetAnalysisDecompositionStepDto:
      type: object
      properties:
        kind:
          type: string
          enum:
            - override
            - other
            - rounding
            - scope
            - price
            - par
            - extras
        amount:
          type:
            - string
            - 'null'
      required:
        - kind
        - amount
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.