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 et raisons de blocage calculées par les prédicats runtime).

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": {
    "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 exposent des booléens et des raisons de blocage. Les seuils runtime historiques restent internes pendant leur migration vers des prédicats explicites. 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	Code de compatibilité déprécié ; les surfaces publiques utilisent désormais le statut explicite.
`CONTACT_DISABLED`	400	Le prédicat d’actionnabilité refuse le contact et expose sa raison dans blocked_because.
`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