REST · CMMS · field service

Technical data where your work order needs it

The HVAC REST API for your CMMS and technicians

Return a fault-code meaning, the applicable manual, and the right abstention when the SKU is not covered. Keep your UX, work orders, and system of record; AskMarcel supplies the sourced diagnostic layer.

Harness is a separate surface for guided multi-turn sessions. Choose it only when you need to orchestrate and journal every check.

Get a Developer key Book an FSM pilot

The business problem

Your CMMS runs the job — it does not always interpret the fault

Field-service platforms excel at scheduling, parts, and billing. When a technician enters a code, they still often open a PDF or call the hotline. REST puts a sourced answer in the workflow without replacing your CMMS.

PDFs sit outside the workflow

The right manual exists, but neither the code meaning nor the source page reaches the work order.

Wrong model, wrong answer

One code may cover neighbouring ranges. v2 resolves model/SKU and abstains instead of presenting a nearby manual as exact.

Technical data is a product to maintain

OEM ingestion, normalisation, and provenance should not become a side project on your FSM roadmap.

Real scenario

A Gree E6 fault attached to the work order, with its source

From a work order, your app sends the brand, model hint, and E6. It resolves the model, calls v2 diagnostics, and displays the interpretation with the applicable manual and page.

If no exact manual is available, the API returns a structured abstention: your app opens expert escalation instead of suggesting a part. If you then need every measurement to be guided, move to Harness Beta.

REST v1: broad lookup and document search
REST v2: model resolution, SKU provenance, and explicit abstention
Attach the answer and its citation to your work order

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

Illustrative citation

Gree · Service manual · p. 201

Bench scenario: hvac-bench/field-service-e6-gree

Sourced response (illustrative redacted excerpt)

{
  "status": "sourced",
  "model_id": "mdl_…",
  "error_code": "E6",
  "diagnostic": "Communication fault (redacted)",
  "citation": {
    "manufacturer": "gree",
    "manual": "Service manual (redacted)",
    "page": 201
  },
  "billable": true
}

Abstention (not billable)

{
  "status": "no_exact_source",
  "model_id": "unknown-sku-…",
  "message": "No exact OEM manual for this SKU — route to expert review",
  "billable": false
}

HVAC-Bench protocol →Quickstart examples →

Honest limits

What the REST API does — and does not — promise

v1 is not SKU evidence

v1 supports broad lookup. Use v2 whenever the answer must rely on the exact model manual.

v2 prefers abstention

Without an exact manual, or with an ambiguous model, the correct response is structured abstention — not artificial confidence.

Not a session engine

REST enriches your CMMS. Evaluate Harness Beta when you must journal a sequence of technician checks and replies.

Two perimeters

CMMS vendor vs field operator

Perimeter A — FSM / CMMS product

You enrich an existing workflow

Software vendors want lookup and provenance inside their own experience, not a hand-off to a third-party consumer app.

REST v1/v2 from mobile, back office, or customer portal
Resolve model/SKU before answers that need to be exact
Connecteurs programme for co-selling with Marcel Inside

Perimeter B — Service operator

You deploy diagnostic help

Operations leaders need an answer inside their tool and a clear escalation path — not another interface for their teams.

Pilot on one brand, region, and work-order type
Citations and abstention status usable in your BI
Add Harness later if the workflow needs multi-turn checks

Integration flow

From work order to sourced response

1
Normalise the request
Send brand, code, and model hint from your asset registry or work order.
2
Choose v1 or v2
Use v1 for broad lookup; resolve the model and use v2 when SKU provenance is a requirement.
3
Show the source or abstention
Attach the OEM citation to the work order. Without an exact source, open your expert queue instead of forcing an answer.
4
Move to Harness only when needed
When every check must be proposed, answered, and replayed, run a Harness pilot rather than rebuilding a session in your CMMS.

Evidence

A REST surface you can verify before integration

Public documentation, the machine contract, and HVAC-Bench let product teams verify coverage, provenance, and abstention behaviour before a pilot.

See benchmark methodology

400k+

Fault codes in global lookup

v1 + v2

REST surfaces

source or abstain

v2 policy

Go deeper

REST guide

v1 lookup, v2 provenance, and the right integration surface.

Guided diagnostic Harness

Evaluate the session surface if your app must drive multi-turn checks.

Which API to use

Compare REST v1/v2, MCP, and Harness before you design the workflow.

Add diagnostic data to your CMMS without rebuilding it

Validate lookup and provenance with a Developer key, then scope a pilot around one brand and one work-order type.