HVAC Builder API

openapi: 3.1.0
info:
  title: HVAC Builder API
  version: '2026-11-12'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-12: 36 operation(s) read from 3 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; HVAC Builder has published no machine-readable contract that
    the pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 0
    documentation: 36
    pages-with-code: 0
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-12'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://hvacbuilder.app/reference
  - https://hvacbuilder.app/reference/mcp
  - https://hvacbuilder.app/reference/rest
paths:
  /api/catalog:
    get:
      operationId: get_api_catalog
      tags:
      - Api
      summary: Download the whole catalog document (gzipped); signed‑in and metered, costing tokens per request.
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiCatalogResponse'
      x-evidence:
        kind: documentation
  /api/catalog/compressors:
    get:
      operationId: get_api_catalog_compressors
      tags:
      - Api
      summary: Retrieve all compressors with full coefficient sets; signed‑in and metered, costing tokens.
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiCatalogCompressorsResponse'
      x-evidence:
        kind: documentation
  /api/catalog/compressors/{id}:
    get:
      operationId: get_api_catalog_compressors_id
      tags:
      - Api
      summary: Get a compressor with its coefficient sets, steps and envelope; free for any signed‑in account.
      x-source: https://hvacbuilder.app/reference/rest
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiCatalogCompressorsIdResponse'
      x-evidence:
        kind: documentation
  /api/catalog/index:
    get:
      operationId: get_api_catalog_index
      tags:
      - Api
      summary: List every catalog kind in full except compressors and published curves.
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiCatalogIndexResponse'
      x-evidence:
        kind: documentation
  /api/catalog/items/{id}:
    get:
      operationId: get_api_catalog_items_id
      tags:
      - Api
      summary: Retrieve one catalog item of any kind, with curves for signed‑in accounts.
      x-source: https://hvacbuilder.app/reference/rest
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiCatalogItemsIdResponse'
      x-evidence:
        kind: documentation
  /api/catalog/refrigerants:
    get:
      operationId: get_api_catalog_refrigerants
      tags:
      - Api
      summary: GET /api/catalog/refrigerants
      x-source: https://hvacbuilder.app/reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/health:
    get:
      operationId: get_api_health
      tags:
      - Api
      summary: Health status of the service
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiHealthResponse'
      x-evidence:
        kind: documentation
  /api/layout:
    post:
      operationId: post_api_layout
      tags:
      - Api
      summary: The graph laid out in rows the way the examples are
      x-source: https://hvacbuilder.app/reference/rest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiLayoutRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiLayoutResponse'
      x-evidence:
        kind: documentation
  /api/me:
    get:
      operationId: get_api_me
      tags:
      - Api
      summary: Identity, limits, capability flags, and token balance for the caller.
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiMeResponse'
      x-evidence:
        kind: documentation
  /api/presets:
    get:
      operationId: get_api_presets
      tags:
      - Api
      summary: The published supplier systems, the examples among them
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/presets/{id}/solution:
    get:
      operationId: get_api_presets_id_solution
      tags:
      - Api
      summary: A published system's design point, public and uncharged
      x-source: https://hvacbuilder.app/reference/rest
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/rate/ieer:
    post:
      operationId: post_api_rate_ieer
      tags:
      - Api
      summary: Rate a machine (IEER) using a graph and optional boundary and component settings.
      x-source: https://hvacbuilder.app/reference/rest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiRateIeerRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiRateIeerResponse'
      x-evidence:
        kind: documentation
  /api/report:
    post:
      operationId: post_api_report
      tags:
      - Api
      summary: POST /api/report – the spec report as HTML, PDF, or schedule CSV
      x-source: https://hvacbuilder.app/reference/rest
      parameters:
      - name: format
        in: query
        required: false
        schema:
          type: string
        description: pdf|schedule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiReportRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/report/building:
    post:
      operationId: post_api_report_building
      tags:
      - Api
      summary: POST /api/report/building – the building report for a finished job ({jobId})
      x-source: https://hvacbuilder.app/reference/rest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiReportBuildingRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/report/chart:
    post:
      operationId: post_api_report_chart
      tags:
      - Api
      summary: POST /api/report/chart – the psychrometric chart tab's own drawing ({svg, source?, pressureKpa?, legend?}) printed in the report
        shell
      x-source: https://hvacbuilder.app/reference/rest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiReportChartRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/rfq:
    post:
      operationId: post_api_rfq
      tags:
      - Api
      summary: POST /api/rfq
      x-source: https://hvacbuilder.app/reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/rfq/match:
    post:
      operationId: post_api_rfq_match
      tags:
      - Api
      summary: Preview the suppliers a design matches
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/rfq/match-accessories:
    post:
      operationId: post_api_rfq_match_accessories
      tags:
      - Api
      summary: POST /api/rfq/match-accessories
      x-source: https://hvacbuilder.app/reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/simulate:
    get:
      operationId: get_api_simulate
      tags:
      - Api
      summary: GET /api/simulate – list your runs with status rows
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_api_simulate
      tags:
      - Api
      summary: POST /api/simulate – a system against a weather year, with or without a control; returns a job id
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/simulate/building:
    post:
      operationId: post_api_simulate_building
      tags:
      - Api
      summary: POST /api/simulate/building – exactly one of buildingId (stored) or building (inline {name, zones, systems})
      x-source: https://hvacbuilder.app/reference/rest
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiSimulateBuildingRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/simulate/{id}:
    delete:
      operationId: delete_api_simulate_id
      tags:
      - Api
      summary: DELETE /api/simulate/{id} – delete a finished run or cancel a run in progress
      x-source: https://hvacbuilder.app/reference/rest
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_api_simulate_id
      tags:
      - Api
      summary: GET /api/simulate/{id} – polls a simulation job
      x-source: https://hvacbuilder.app/reference/rest
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/solve:
    post:
      operationId: post_api_solve
      tags:
      - Api
      summary: Solve a graph at a design point.
      x-source: https://hvacbuilder.app/reference/mcp
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/systems:
    post:
      operationId: post_api_systems
      tags:
      - Api
      summary: POST /api/systems
      x-source: https://hvacbuilder.app/reference
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/taxonomy:
    get:
      operationId: get_api_taxonomy
      tags:
      - Api
      summary: GET /api/taxonomy
      x-source: https://hvacbuilder.app/reference
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/weather:
    get:
      operationId: get_api_weather
      tags:
      - Api
      summary: List weather libraries (years) owned by the account or shared city years.
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiWeatherResponse'
      x-evidence:
        kind: documentation
  /api/weather/cities:
    get:
      operationId: get_api_weather_cities
      tags:
      - Api
      summary: Retrieve the list of TMY cities and one city's PVGIS year by cityId.
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiWeatherCitiesResponse'
      x-evidence:
        kind: documentation
  /api/weather/generate:
    post:
      operationId: post_api_weather_generate
      tags:
      - Api
      summary: POST /api/weather/generate – a labelled synthetic year; an hourly CSV, {name, altitudeM?, mapping, csv}
      x-source: https://hvacbuilder.app/reference/rest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiWeatherGenerateRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/weather/import:
    post:
      operationId: post_api_weather_import
      tags:
      - Api
      summary: Import weather CSV mapped by column names.
      x-source: https://hvacbuilder.app/reference/mcp
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/weather/tmy:
    post:
      operationId: post_api_weather_tmy
      tags:
      - Api
      summary: POST /api/weather/tmy – the TMY cities, and one city's PVGIS year by {cityId}
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/weather/{id}:
    delete:
      operationId: delete_api_weather_id
      tags:
      - Api
      summary: DELETE /api/weather/{id} – delete a dataset of your own
      x-source: https://hvacbuilder.app/reference/rest
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/weather/{id}/preview:
    get:
      operationId: get_api_weather_id_preview
      tags:
      - Api
      summary: GET /api/weather/{id}/preview – a dataset's listing row and its first hours ( ?limit= , a month at most)
      x-source: https://hvacbuilder.app/reference/rest
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/workspace:
    delete:
      operationId: delete_api_workspace
      tags:
      - Api
      summary: The caller's workspace and what it holds
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_api_workspace
      tags:
      - Api
      summary: The caller's workspace and what it holds
      x-source: https://hvacbuilder.app/reference/rest
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/workspace/invite:
    post:
      operationId: post_api_workspace_invite
      tags:
      - Api
      summary: A new invite link, for the owner or a manager
      x-source: https://hvacbuilder.app/reference/rest
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiWorkspaceInviteRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiCatalogResponse:
      type: object
      properties:
        catalog:
          type: object
    GetApiCatalogCompressorsResponse:
      type: object
      properties:
        compressors:
          type: array
    GetApiCatalogCompressorsIdResponse:
      type: object
      properties:
        compressor:
          type: object
          description: Compressor data including coefficients and envelope.
    GetApiCatalogIndexResponse:
      type: object
      properties:
        items:
          type: array
          description: Catalog entries with kind, facets, and rating point.
    GetApiCatalogItemsIdResponse:
      type: object
      properties:
        kind:
          type: string
        item:
          type: object
    GetApiHealthResponse:
      type: object
      properties:
        status:
          type: string
        properties:
          type: object
        storage:
          type: string
        auth:
          type: string
    PostApiLayoutRequest:
      type: object
      properties:
        graph:
          type: object
      required:
      - graph
    PostApiLayoutResponse:
      type: object
      properties:
        graph:
          type: object
        stacked:
          type: object
    GetApiMeResponse:
      type: object
      properties:
        identity:
          type: object
        limits:
          type: object
        capabilityFlags:
          type: object
        tokenBalance:
          type: object
    PostApiRateIeerRequest:
      type: object
      properties:
        graph:
          type: object
        boundary:
          type: object
        supplyComponentId:
          type: string
        mzvav:
          type: boolean
      required:
      - graph
    PostApiRateIeerResponse:
      type: object
      properties:
        ieer:
          type: number
          description: IEER in W/W.
        ieerBtuWh:
          type: number
          description: IEER in Btu/(W·h).
        fullLoadEer:
          type: number
        points:
          type: array
          description: Array of rating points with capacity, power, EER, etc.
    PostApiReportRequest:
      type: object
      properties:
        graph:
          type: object
        boundary:
          type: object
        name:
          type: string
        annual:
          type: boolean
        datasetName:
          type: string
        designPoints:
          type: array
      required:
      - graph
      - boundary
    PostApiReportBuildingRequest:
      type: object
      properties:
        jobId:
          type: string
      required:
      - jobId
    PostApiReportChartRequest:
      type: object
      properties:
        svg:
          type: string
        source:
          type: string
        pressureKpa:
          type: number
        legend:
          type: boolean
      required:
      - svg
    PostApiSimulateBuildingRequest:
      type: object
      properties:
        buildingId:
          type: string
        building:
          type: object
          description: '{name, zones, systems}'
    GetApiWeatherResponse:
      type: object
      properties:
        libraries:
          type: array
    GetApiWeatherCitiesResponse:
      type: object
      properties:
        cities:
          type: array
    PostApiWeatherGenerateRequest:
      type: object
      properties:
        name:
          type: string
        altitudeM:
          type: number
        mapping:
          type: object
        csv:
          type: string
      required:
      - name
      - csv
    PostApiWorkspaceInviteRequest:
      type: object
      properties:
        inviteToken:
          type: string
      required:
      - inviteToken
tags:
- name: Api