REST · OpenAPI

Lookup infrastructure, not a chat wrapper

The HVAC error code API your backend can audit

Mobile apps, portals, and middleware need HTTP — not MCP. AskMarcel REST returns normalised codes, diagnostic trees where available, and explicit abstention on v2 when the manual cannot be bound to the SKU.

Not a scraped forum aggregator — responses are tied to manufacturer documentation with billable vs non-billable abstention spelled out in the contract.

Get a Developer key Book an API pilot

The business problem

Your app still ships PDF links — users want answers in the API

Developers integrate Google first, then realise HVAC codes are ambiguous across brands. Building an in-house error-code database duplicates a decade of OEM ingestion — and still drifts every firmware season.

Ambiguous codes

“E07” spans dozens of meanings. You need brand-scoped lookup, not full-text search over installation manuals.

Billable trust

Finance asks which API calls were “real answers” vs abstentions. v2 makes that distinction machine-readable.

Dual velocity

Product wants v1 breadth today; compliance wants v2 provenance tomorrow — on the same API key.

Real scenario

Portal lookup: Atlantic code 01 on a known model

A manufacturer portal calls GET /v1/error-codes/atlantic/01 for legacy widgets, then migrates premium accounts to POST /v2/diagnostic with model_id from the registration database.

v1 returns meaning + related docs for broad search; v2 returns only steps whose manual page matches the registered SKU — otherwise abstention with reason code for the UI.

OpenAPI published at api.askmarcel.app — synced to /api/docs/reference
Developer tier: 500 monthly / 50 daily calls for integration
Same key powers MCP tools for teams that add agents later

Redacted excerpt for illustration only. The live API returns full manufacturer, manual, page and section — see the HVAC-Bench protocol.

Illustrative citation

Toshiba · SHRMi service manual · p. 56

Bench scenario: hvac-bench/lookup-toshiba-1c

Sourced response (illustrative redacted excerpt)

{
  "brand": "toshiba",
  "code": "1C",
  "title": "Communication fault (redacted)",
  "source": {
    "manual": "SHRMi service manual",
    "page": 56
  },
  "billable": true
}

Abstention (not billable)

{
  "brand": "toshiba",
  "code": "1C",
  "status": "no_exact_source",
  "billable": false
}

HVAC-Bench protocol →Quickstart examples →

Honest limits

API scope you should plan for

v1 vs v2 semantics

v1 diagnostic/turn is legacy Air/Water HP guided flow without strict SKU provenance — document which endpoint your product sells.

Harness is separate

Multi-turn sessions live under /v2/diagnostic-sessions (Beta) — not inside a single /v2/diagnostic POST.

Rate limits

Developer tier quotas suit QA and pilots — production volumes need a commercial plan.

Two perimeters

Platform engineer vs product owner

Perimeter A — Backend & API team

You own OpenAPI clients and SLAs

You need stable paths, typed errors, and a public surface contract validated in CI — not a PDF integration guide from 2022.

GA paths: /v1/search, /v1/error-codes/{brand}/{code}, /v2/diagnostic
public-surface.snapshot.json validated in CI before deployment
Scalar reference embedded on /api/docs/reference

Perimeter B — Product & monetisation

You package lookup for end customers

You decide whether the portal shows “meaning only” or charged diagnostic depth — AskMarcel gives you abstention signals to align COGS.

Non-billable abstention on v2 reduces surprise invoices
Which-api guide for sales engineering
Pilot pricing before list publish

Integration flow

From OpenAPI to production keys

1
Read which-api
Choose v1 breadth, v2 provenance, or Harness sessions before writing code — avoids refactoring in week three.
2
Smoke test with Developer key
Hit /v1/search and one brand code from your top traffic list; log latency and citation fields.
3
Add v2 when SKU is available
Wire model_id from your asset DB; handle abstention in UI as first-class state.
4
Promote to commercial quota
Contact pilot when call volume exceeds Developer tier — same endpoints, higher limits.

Evidence

Public surface contract, CI-validated

REST GA paths and MCP tools are enumerated in public-surface.snapshot.json — validated in CI against the live public surface endpoint before each deployment.

Open corpus & bench details

REST GA paths

400k+

Brand-normalised codes

94%

Manual reference retrieval (bench)

Go deeper

OpenAPI reference

Interactive Scalar docs with try-it-out.

Which API guide

Decision matrix for v1, v2, Harness, and MCP.

MCP for agents

Same backend, agent-native transport.

Integrate HVAC lookup in days, not quarters

Pull OpenAPI, issue a Developer key, and ship v1 — add v2 provenance when your asset registry is ready.