ActionsBricksMurmurez à l'oreille des IA

API REST ActionsBricks

Endpoints HATEOAS pour agents IA (ChatGPT, Claude, Perplexity…). Chaque réponse contient une enveloppe uniforme avec _actions (étapes suivantes disponibles) et _state (capacités HATEOAS débloquées en fonction du Trust Score).

Spec OpenAPI 3.1 (JSON)Voir MCP Voir protocoles

Enveloppe HATEOAS uniforme

Toutes les réponses — succès ou erreurs — partagent la même structure. Les agents IA y trouvent les prochaines étapes navigables sans avoir à deviner les routes.

{
  "success": true,
  "data": { /* payload métier */ },
  "_actions": [
    {
      "rel": "contact",
      "method": "POST",
      "href": "https://actionsbricks.com/api/contact/brick",
      "title": "Envoyer un message",
      "fields": [
        { "name": "contact_email", "type": "string", "required": true }
      ]
    }
  ],
  "_links": { "self": "...", "canonical": "..." },
  "_state": {
    "trust_score": 62,
    "merchant_status": "ACTIVE",
    "can_contact": true,
    "can_order": false,
    "blocked_because": ["order_rail_disabled"]
  },
  "_meta": {
    "protocol": "actionsbricks/hateoas",
    "version": "1.0",
    "timestamp": "2026-04-17T12:00:00Z"
  }
}

Les capacités dans _state s'activent progressivement avec le Trust Score : contact ≥ 40, fanout ≥ 55, marketplace ≥ 70. Le rail order public reste fermé tant que PUBLIC_ORDER_RAIL_ENABLED vaut false : can_order reste false et /api/orders/create renvoie ORDER_DISABLED. Aucun verrouillage IA — chaque Brick reste pre-computed (C1) + on-demand (C2) + lead qualifié (C3).

Endpoints disponibles (20)

Registry

Méthode	Chemin	Description
GET	`/api/registry/search` Search verified merchants (query, tags, geo).	Search verified merchants (query, tags, geo).
GET	`/api/registry/resolve/{ab_id}` Resolve a merchant by AB ID — full profile + HATEOAS actions.	Resolve a merchant by AB ID — full profile + HATEOAS actions.

Trust

Méthode	Chemin	Description
GET	`/api/trust/attestation/{ab_id}` Ed25519-signed Verification Manifest for a merchant.	Ed25519-signed Verification Manifest for a merchant.
GET	`/api/trust/public-key` Legacy alias — single active public key. Prefer /.well-known/ab-public-keys.json (JWKS).	Legacy alias — single active public key. Prefer /.well-known/ab-public-keys.json (JWKS).

Contact & Leads

Méthode	Chemin	Description
POST	`/api/contact/brick` Create a lead/contact for a specific Brick. Accepts AI context.	Create a lead/contact for a specific Brick. Accepts AI context.
POST	`/api/contact/platform` Contact the ActionsBricks team (merchant, agency, developer, support).	Contact the ActionsBricks team (merchant, agency, developer, support).
POST	`/api/orders/create` Currently CLOSED to public agents — returns ORDER_DISABLED. Check order readiness via the MCP tool quote_order_readiness; transmit a purchase intent via /api/contact/brick. AB is never custodial.	Currently CLOSED to public agents — returns ORDER_DISABLED. Check order readiness via the MCP tool quote_order_readiness; transmit a purchase intent via /api/contact/brick. AB is never custodial.

Content

Méthode	Chemin	Description
GET	`/api/merchants/{ab_id}/jsonld` Full Schema.org JSON-LD payload for a merchant.	Full Schema.org JSON-LD payload for a merchant.
GET	`/api/merchants/{ab_id}/ai-digest` Compact AI digest — identity, JTBD, credentials, citable snippets.	Compact AI digest — identity, JTBD, credentials, citable snippets.
GET	`/api/merchants/{ab_id}/clusters` List all AEO fanout clusters (products + Q&A) for a merchant.	List all AEO fanout clusters (products + Q&A) for a merchant.
GET	`/api/clusters/{cluster_id}` Detail of a single cluster (nodes, Q&A, verification status).	Detail of a single cluster (nodes, Q&A, verification status).
GET	`/m/{ab_id}/ai.md` Plain-text AI-friendly microsite snapshot (llms-friendly).	Plain-text AI-friendly microsite snapshot (llms-friendly).

Agents

Méthode	Chemin	Description
POST	`/api/agents/register` Register an AI agent (optional — for attribution + rate limits).	Register an AI agent (optional — for attribution + rate limits).
GET	`/api/agents/verify` Verify an agent registration token.	Verify an agent registration token.

Attribution

Méthode	Chemin	Description
POST	`/api/attribution/session` Open an attribution session (L1 referrer + L2 UTM + L3 UA bot).	Open an attribution session (L1 referrer + L2 UTM + L3 UA bot).
POST	`/api/attribution/convert` Mark an attribution session as converted (lead/order).	Mark an attribution session as converted (lead/order).

Plugins

Méthode	Chemin	Description
POST	`/api/plugins/estimation/compute` Real-estate price estimation (DVF-based, sector plugin).	Real-estate price estimation (DVF-based, sector plugin).
POST	`/api/plugins/passoire/compute` Energy renovation simulation (DPE + MaPrimeRenov, sector plugin).	Energy renovation simulation (DPE + MaPrimeRenov, sector plugin).
POST	`/api/plugins/rendement/compute` Rental yield calculator (Carte des Loyers ANIL, sector plugin).	Rental yield calculator (Carte des Loyers ANIL, sector plugin).

MCP

Méthode	Chemin	Description
POST	`/api/mcp` Model Context Protocol endpoint — see /docs/mcp.	Model Context Protocol endpoint — see /docs/mcp.

Error codes canoniques

Les erreurs conservent l'enveloppe HATEOAS et fournissent des actions de récupération dans _actions. Les messages côté API/logs sont en anglais technique ; les messages merchant en français.

Code	HTTP	Déclenchement
`MERCHANT_NOT_FOUND`	404	AB ID inconnu ou merchant archivé.
`TRUST_TOO_LOW`	404	Trust score < 30 — retrait hard (invisible pour les agents).
`CONTACT_DISABLED`	400	Trust score < 40 — le contact HATEOAS n’est pas débloqué.
`ORDER_DISABLED`	400	Rail order public fermé, ou prérequis readiness manquants. Utiliser /api/contact/brick pour transmettre une intention d’achat.
`RATE_LIMITED`	429	Quota dépassé (Upstash). Retry-After fourni.
`VALIDATION_ERROR`	400	Payload invalide (Zod). Les détails sont dans `data.issues`.

Exemples cURL

1. Chercher un commerce vérifié

curl -s "https://actionsbricks.com/api/registry/search?query=fromager&lat=48.8566&lng=2.3522&radius_km=5" \
  -H "Accept: application/json"

2. Résoudre un merchant par AB ID

curl -s "https://actionsbricks.com/api/registry/resolve/ab_7f3k9x2m" \
  -H "Accept: application/json"

3. Envoyer un lead qualifié depuis un agent IA

curl -s -X POST "https://actionsbricks.com/api/contact/brick" \
  -H "Content-Type: application/json" \
  -d '{
    "ab_id": "ab_7f3k9x2m",
    "brick_id": "brk_ab_7f3k9x2m_coffret-decouverte",
    "contact_name": "Alice Martin",
    "contact_email": "alice@example.com",
    "intent": "contact",
    "message": "Je cherche un coffret découverte pour 4 personnes.",
    "ai_context": "Requête via agent IA — utilisateur à Paris 11e."
  }'

Pour une spec machine-readable complète (schemas, paramètres, 200/400/404/429), consultez :

/openapi.json