API REST

En bref

Hôte contractuel api.askmarcel.app. v1 = lookup sourcé. v2 = provenance SKU stricte (diagnostic null si pas de manuel exact).

Choisir la bonne surface

REST v1, v2 lookup, sessions Harnais et MCP répondent à des intentions différentes.

Quelle API choisir ?

Avant d’intégrer, lisez la matrice v1 / v2 / Harnais / MCP : /api/docs/which-api

Hôte contractuel

https://api.askmarcel.app est l’hôte contractuel. Préfixes : https://api.askmarcel.app/v1 (v1) et https://api.askmarcel.app/v2 (provenance SKU). Le chemin équivalent sur le domaine app est une réécriture interne non contractuelle.

OpenAPI

Spécification machine : https://api.askmarcel.app/v1/openapi.json

Endpoints v1

POST https://api.askmarcel.app/v1/diagnostic
POST https://api.askmarcel.app/v1/diagnostic/turn
GET https://api.askmarcel.app/v1/search
GET https://api.askmarcel.app/v1/procedure/:chunkId
GET https://api.askmarcel.app/v1/error-codes/:brand/:code
GET https://api.askmarcel.app/v1/products/:brand/:model
GET https://api.askmarcel.app/v1/pdf-snapshot/:documentId/:page
GET https://api.askmarcel.app/v1/registry
GET https://api.askmarcel.app/v1/me

Provenance SKU (v2)

Répondez seulement si un manuel exact approuvé couvre ce SKU. Sinon status = no_exact_source et diagnostic = null — ce n’est pas facturable. resolve = exact ou alias, jamais un nom de gamme.

POST https://api.askmarcel.app/v2/diagnostic
POST https://api.askmarcel.app/v2/models/resolve
GET https://api.askmarcel.app/v2/models/:model_id/coverage

Harnais Beta — sessions (v2)

Boucle stateful Air/Eau + Air/Air : création (quota unique), réponses typées, clôture et synthèse. Canal Beta — hypothèses, action discriminante, citations quand applicable.

POST https://api.askmarcel.app/v2/diagnostic-sessions
GET https://api.askmarcel.app/v2/diagnostic-sessions/:session_id
POST https://api.askmarcel.app/v2/diagnostic-sessions/:session_id/responses
POST https://api.askmarcel.app/v2/diagnostic-sessions/:session_id/close
GET https://api.askmarcel.app/v2/diagnostic-sessions/:session_id/summary

SDK

npm install @askmarcel/sdk@beta — méthodes startDiagnosticSession, respondToDiagnosticSession, closeDiagnosticSession, getDiagnosticSessionSummary.

POST /diagnostic

Recherche sourcée en un aller-retour : extrait de manuel, étapes et citation. Pour un dépannage multi-tours PAC Air/Eau, utiliser POST /diagnostic/turn.

curl

curl -s https://api.askmarcel.app/v1/diagnostic \
  -H "Authorization: Bearer ak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"brand":"Mitsubishi","model":"Ecodan PUHZ-W85","error_code":"E7"}'

GET /search

Recherche documentaire dans le corpus technique. Paramètre q obligatoire.

curl

curl -s "https://api.askmarcel.app/v1/search?q=defaut+communication+mitsubishi" \
  -H "Authorization: Bearer ak_live_..."

SDK & templates

npm @askmarcel/sdk (JS/TS)
Template chatbot open-source (HVAC-Bench)