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

# Query



## OpenAPI

````yaml /openapi.json post /v1/workspaces/{workspaceId}/projects/{projectId}/budget-analysis/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/query:
    post:
      tags:
        - Budget Analysis
      summary: Query
      operationId: BudgetAnalysisController_query_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/BudgetAnalysisQueryDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BudgetAnalysisQueryResponseDto'
      security:
        - bearer: []
components:
  schemas:
    BudgetAnalysisQueryDto:
      type: object
      properties:
        budgetVersion:
          anyOf:
            - type: string
              enum:
                - live
            - type: string
              pattern: ^[1-9]\d{0,18}$
        groupBy:
          type: string
          enum:
            - category
            - supplier
            - area
            - department
        issue:
          type: string
          enum:
            - overrun
            - incomplete
            - shortfall
            - line_overrun_specified
            - line_overrun_purchase
        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
      required:
        - budgetVersion
        - groupBy
      additionalProperties: false
    BudgetAnalysisQueryResponseDto:
      type: object
      properties:
        matchingCounts:
          type: object
          additionalProperties:
            type: integer
        attention:
          $ref: '#/components/schemas/BudgetAnalysisAttentionDto'
        matchedCount:
          type: number
        insights:
          $ref: '#/components/schemas/BudgetAnalysisInsightsDto'
        budgetVersion:
          $ref: '#/components/schemas/BudgetAnalysisVersionDto'
        itemizedBudgetsAreLive:
          type: boolean
        groupBy:
          enum:
            - category
            - area
            - supplier
            - department
          type: string
        rows:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisRowDto'
        projectTotal:
          $ref: '#/components/schemas/BudgetAnalysisFiguresDto'
        softCosts:
          $ref: '#/components/schemas/BudgetAnalysisSoftCostsDto'
        materials:
          $ref: '#/components/schemas/BudgetAnalysisMaterialsDto'
        grandTotal:
          $ref: '#/components/schemas/BudgetAnalysisFiguresDto'
        reconciliation:
          $ref: '#/components/schemas/BudgetAnalysisReconciliationDto'
        context:
          $ref: '#/components/schemas/BudgetAnalysisContextDto'
        capabilities:
          $ref: '#/components/schemas/BudgetAnalysisCapabilitiesDto'
        computedAt:
          type: string
        freshness:
          type: string
          enum:
            - live
      required:
        - matchingCounts
        - attention
        - matchedCount
        - insights
        - budgetVersion
        - itemizedBudgetsAreLive
        - groupBy
        - rows
        - projectTotal
        - softCosts
        - materials
        - grandTotal
        - reconciliation
        - context
        - capabilities
        - computedAt
        - freshness
    BudgetAnalysisAttentionDto:
      type: object
      properties:
        overrunCount:
          type: number
        lineOverrunCount:
          $ref: '#/components/schemas/BudgetAnalysisMarginAttentionDto'
        categoryOverrunCount:
          $ref: '#/components/schemas/BudgetAnalysisMarginAttentionDto'
        softCostOverrunCount:
          $ref: '#/components/schemas/BudgetAnalysisMarginAttentionDto'
        incompleteInputCount:
          type: number
        purchasingShortfallCount:
          type: number
        installedShortfallCount:
          type: number
        requiredStockShortfallCount:
          type: number
        belowTargetMarginCount:
          $ref: '#/components/schemas/BudgetAnalysisMarginAttentionDto'
      required:
        - purchasingShortfallCount
        - installedShortfallCount
        - requiredStockShortfallCount
    BudgetAnalysisInsightsDto:
      type: object
      properties:
        scopes:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BudgetAnalysisInsightDto'
      required:
        - scopes
    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
    BudgetAnalysisRowDto:
      type: object
      properties:
        key:
          type: string
        kind:
          type: string
          enum:
            - extra
            - item
            - unassigned
            - group
            - bucket
        label:
          type:
            - string
            - 'null'
        parentKey:
          type:
            - string
            - 'null'
        depth:
          type: number
        effectiveInstanceCount:
          type:
            - number
            - 'null'
        categoryId:
          type:
            - string
            - 'null'
        supplierCompanyId:
          type:
            - string
            - 'null'
        supplierName:
          type:
            - string
            - 'null'
        departmentId:
          type:
            - string
            - 'null'
        areaId:
          type:
            - string
            - 'null'
        slotId:
          type:
            - string
            - 'null'
        projectItemId:
          type:
            - string
            - 'null'
        refNumber:
          type:
            - string
            - 'null'
        allocatedCost:
          type:
            - string
            - 'null'
        categoryPlan:
          anyOf:
            - $ref: '#/components/schemas/BudgetAnalysisCategoryPlanDto'
            - type: 'null'
        areaClientCeiling:
          type:
            - string
            - 'null'
        areaPlan:
          anyOf:
            - $ref: '#/components/schemas/BudgetAnalysisAreaPlanDto'
            - type: 'null'
        estimated:
          type: boolean
        budget:
          $ref: '#/components/schemas/BudgetAnalysisBudgetDto'
        specified:
          $ref: '#/components/schemas/BudgetAnalysisTrackDto'
        purchase:
          $ref: '#/components/schemas/BudgetAnalysisTrackDto'
        gaps:
          $ref: '#/components/schemas/BudgetAnalysisGapsDto'
        incomplete:
          $ref: '#/components/schemas/BudgetAnalysisIncompleteDto'
        itemCount:
          type: number
      required:
        - key
        - kind
        - label
        - parentKey
        - depth
        - effectiveInstanceCount
        - categoryId
        - supplierCompanyId
        - supplierName
        - departmentId
        - areaId
        - slotId
        - projectItemId
        - refNumber
        - categoryPlan
        - areaPlan
        - estimated
        - budget
        - specified
        - purchase
        - gaps
        - incomplete
        - itemCount
    BudgetAnalysisFiguresDto:
      type: object
      properties:
        budget:
          $ref: '#/components/schemas/BudgetAnalysisBudgetDto'
        specified:
          $ref: '#/components/schemas/BudgetAnalysisTrackDto'
        purchase:
          $ref: '#/components/schemas/BudgetAnalysisTrackDto'
        gaps:
          $ref: '#/components/schemas/BudgetAnalysisGapsDto'
        incomplete:
          $ref: '#/components/schemas/BudgetAnalysisIncompleteDto'
        itemCount:
          type: number
      required:
        - budget
        - specified
        - purchase
        - gaps
        - incomplete
        - itemCount
    BudgetAnalysisSoftCostsDto:
      type: object
      properties:
        filtered:
          type: boolean
        rows:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisSoftCostRowDto'
        families:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisSoftCostRowDto'
        total:
          $ref: '#/components/schemas/BudgetAnalysisSoftCostRowDto'
      required:
        - filtered
        - rows
        - families
        - total
    BudgetAnalysisMaterialsDto:
      type: object
      properties:
        availability:
          type: string
          enum:
            - available
            - filtered
        freshness:
          type: string
          enum:
            - live
        rows:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisMaterialRowDto'
      required:
        - availability
        - freshness
        - rows
    BudgetAnalysisReconciliationDto:
      type: object
      properties:
        unallocatedHard:
          type:
            - string
            - 'null'
        categoriesOnlyInVersion:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisVersionCategoryDto'
        categoriesOnlyLive:
          type: array
          items:
            $ref: '#/components/schemas/BudgetAnalysisLiveCategoryDto'
      required:
        - categoriesOnlyInVersion
        - categoriesOnlyLive
    BudgetAnalysisContextDto:
      type: object
      properties:
        categoryMarginMeaning:
          type: string
          enum:
            - target
            - equivalent
        ceiling:
          type:
            - string
            - 'null'
        hardAvailable:
          type:
            - string
            - 'null'
        contingency:
          type:
            - string
            - 'null'
        method:
          type: string
          enum:
            - manual
            - area_rates
      required:
        - categoryMarginMeaning
        - method
    BudgetAnalysisCapabilitiesDto:
      type: object
      properties:
        itemizedBudget:
          type: boolean
        softCosts:
          type: boolean
        taxInclusive:
          type: boolean
        departments:
          type: boolean
      required:
        - itemizedBudget
        - softCosts
        - taxInclusive
        - departments
    BudgetAnalysisMarginAttentionDto:
      type: object
      properties:
        specified:
          type: number
        purchase:
          type: number
      required:
        - specified
        - purchase
    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
    BudgetAnalysisCategoryPlanDto:
      type: object
      properties:
        sharePct:
          type:
            - string
            - 'null'
        clientAllocation:
          type:
            - string
            - 'null'
        effectiveMarginPct:
          type:
            - string
            - 'null'
        marginMeaning:
          type: string
          enum:
            - target
            - equivalent
        effectiveMarkupPct:
          type:
            - string
            - 'null'
      required:
        - marginMeaning
    BudgetAnalysisAreaPlanDto:
      type: object
      properties:
        effectiveInstanceCount:
          type: number
        squareArea:
          type:
            - string
            - 'null'
        rate:
          type:
            - string
            - 'null'
        amount:
          type:
            - string
            - 'null'
        inputMissing:
          type: boolean
      required:
        - effectiveInstanceCount
        - squareArea
    BudgetAnalysisBudgetDto:
      type: object
      properties:
        itemizedCost:
          type:
            - string
            - 'null'
        itemizedClient:
          type:
            - string
            - 'null'
    BudgetAnalysisTrackDto:
      type: object
      properties:
        extendedCost:
          type:
            - string
            - 'null'
        extendedClient:
          type:
            - string
            - 'null'
        itemizedCostVariance:
          anyOf:
            - $ref: '#/components/schemas/BudgetAnalysisVarianceDto'
            - type: 'null'
        itemizedClientVariance:
          anyOf:
            - $ref: '#/components/schemas/BudgetAnalysisVarianceDto'
            - type: 'null'
        allocatedCostVariance:
          anyOf:
            - $ref: '#/components/schemas/BudgetAnalysisVarianceDto'
            - type: 'null'
    BudgetAnalysisGapsDto:
      type: object
      properties:
        budgetPrice:
          type: number
        budgetQuantity:
          type: number
        costInput:
          type: number
    BudgetAnalysisIncompleteDto:
      type: object
      properties:
        budget:
          type: boolean
        specified:
          type: boolean
        purchase:
          type: boolean
    BudgetAnalysisSoftCostRowDto:
      type: object
      properties:
        budget:
          $ref: '#/components/schemas/BudgetAnalysisBudgetDto'
        specified:
          $ref: '#/components/schemas/BudgetAnalysisTrackDto'
        purchase:
          $ref: '#/components/schemas/BudgetAnalysisTrackDto'
        gaps:
          $ref: '#/components/schemas/BudgetAnalysisGapsDto'
        incomplete:
          $ref: '#/components/schemas/BudgetAnalysisIncompleteDto'
        itemCount:
          type: number
        key:
          type: string
        softCostId:
          type:
            - string
            - 'null'
        groupId:
          type:
            - string
            - 'null'
        label:
          type:
            - string
            - 'null'
        archived:
          type: boolean
        softCostBudget:
          type:
            - string
            - 'null'
      required:
        - budget
        - specified
        - purchase
        - gaps
        - incomplete
        - itemCount
        - key
        - softCostId
        - groupId
        - label
        - archived
    BudgetAnalysisMaterialRowDto:
      type: object
      properties:
        materialId:
          type: string
        materialName:
          type: string
        shortfallUnits:
          type: string
        supplierCompanyId:
          type:
            - string
            - 'null'
        supplierName:
          type:
            - string
            - 'null'
        requiredUnits:
          type: string
        unitsPerPackage:
          type:
            - string
            - 'null'
        purchaseQuantity:
          type: string
        purchaseQuantityOverride:
          type:
            - string
            - 'null'
        purchasedUnits:
          type: string
        consumptionCost:
          type:
            - string
            - 'null'
        purchasingCost:
          type:
            - string
            - 'null'
        balanceCost:
          type:
            - string
            - 'null'
        incomplete:
          type: boolean
      required:
        - materialId
        - materialName
        - shortfallUnits
        - supplierCompanyId
        - supplierName
        - requiredUnits
        - unitsPerPackage
        - purchaseQuantity
        - purchaseQuantityOverride
        - purchasedUnits
    BudgetAnalysisVersionCategoryDto:
      type: object
      properties:
        categoryId:
          type: string
        label:
          type: string
        allocation:
          type:
            - string
            - 'null'
      required:
        - categoryId
        - label
    BudgetAnalysisLiveCategoryDto:
      type: object
      properties:
        categoryId:
          type: string
        label:
          type: string
      required:
        - categoryId
        - label
    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
    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
    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
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````

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