Which API should I use?

Three surfaces, one engine

https://api.askmarcel.app exposes REST v1 (lookup), REST v2 (SKU provenance + Harness Beta sessions), and an MCP server at https://mcp.askmarcel.app (protocol 2025-06-18, manifest 1.3.0-beta.1). Two distinct perimeters: global lookup (400k+ codes) vs Harness Beta (5 anchor brands, families pac_air_eau / pac_air_air, pack 0.0.1).

Decision matrix

Use this table before integrating. Listed paths and tools are the public contract (WebApp snapshot).

• [Live] Broad lookup, automations, legacy integrations
• When: You need an error code, document search, or one-shot diagnostic without strict SKU provenance.
• REST: /v1/search, /v1/error-codes/{brand}/{code}, /v1/diagnostic, /v1/diagnostic/turn
• MCP: get_error_code, diagnose, diagnose_guided, search_technical_docs
• Limit: No strict SKU provenance; diagnostic/turn = legacy Air/Water HP guided flow.
• [Live] Agents and software that must cite or abstain
• When: You must answer only from an exact manual for the SKU — otherwise abstain (not billable).
• REST: /v2/diagnostic, /v2/models/resolve, /v2/models/{model_id}/coverage
• MCP: diagnose_v2, resolve_model, get_model_coverage
• Limit: Not a stateful multi-turn session.
• [Beta] CMMS, FSM, cockpit — logged guided diagnostics
• When: You want the Harness: safe next check, session journal, and resume by session_id.
• REST: /v2/diagnostic-sessions, /v2/diagnostic-sessions/{session_id}, /v2/diagnostic-sessions/{session_id}/responses, /v2/diagnostic-sessions/{session_id}/close, /v2/diagnostic-sessions/{session_id}/summary
• MCP: start_diagnostic, respond_to_diagnostic, get_diagnostic, close_diagnostic (+1)
• Limit: Beta — 5 anchor brands, Air/Water + Air/Air HP; not full depth on 400k codes.
• [Live] ChatGPT, Claude, custom agents
• When: Your agent calls MCP tools on mcp.askmarcel.app (protocol 2025-06-18).
• REST: — (MCP only)
• MCP: search_technical_docs, get_procedure, get_error_code, get_product_sheet (+6)
• Limit: Current OAuth: no diagnostic.run scope for Beta sessions.

Harness Beta perimeter

The Harness does not cover the global error-code dictionary. Closed Beta: panasonic, daikin, atlantic, mitsubishi-electric, gree; 148/958 codes with a causal path (~15%). Beta 0.0.1 packs are mutable: a resumed session uses the current pack content. The manufacturer lookup at start remains journaled.

Abstention and billing

v2 / diagnose_v2: if no exact manual for the SKU → diagnostic null, status no_exact_source or model_ambiguous — not billable. v1 may return a broader sourced answer; for agents that must cite, prefer v2.

MCP and OAuth

Current OAuth scopes: docs.read, catalog.read, pdf.read — no diagnostic.run for Beta session tools via OAuth alone. Supported protocol: 2025-06-18 only (not 2026-07-28 until deployed).

Next steps

Quickstart → Developer key → first sourced call. For commercial evaluation or a pilot: field REST /solutions/hvac-field-service-software; support REST /solutions/hvac-support-automation; error-code API /solutions/hvac-error-code-api; MCP /solutions/hvac-mcp-server; Harness /solutions/hvac-diagnostic-harness.

• Quickstart: /api/docs/quickstart
• REST details: /api/docs/rest
• MCP: /api/docs/mcp
• Machine contract: https://api.askmarcel.app/v1/public-surface.json