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 (17)

Registry

Méthode	Chemin	Description
GET	`/api/registry/search` Search local merchants by query, location or tags. Available information and actions depend on each result. With semantic=true (hybrid full-text + vector search), the response carries retrieval_degraded (embedding_unavailable \| embedding_disabled) when only the full-text search ran: an empty result then does not show that no merchant matches.	Search local merchants by query, location or tags. Available information and actions depend on each result. With semantic=true (hybrid full-text + vector search), the response carries retrieval_degraded (embedding_unavailable \| embedding_disabled) when only the full-text search ran: an empty result then does not show that no merchant matches.
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/registry/verify/{ab_id}` Ed25519-signed Verification Manifest for a merchant — the signature attests the integrity of the envelope, not the truth of each claim. The server builds and signs a fresh manifest (date, nonce) on each execution and records the generation time; the response may be served from a public cache for at most 300 s, never past its expiry (86400 s with ?snapshot=1).	Ed25519-signed Verification Manifest for a merchant — the signature attests the integrity of the envelope, not the truth of each claim. The server builds and signs a fresh manifest (date, nonce) on each execution and records the generation time; the response may be served from a public cache for at most 300 s, never past its expiry (86400 s with ?snapshot=1).
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).

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.
`SERVICE_SUSPENDED`	503	Accès agents IA suspendu (kill-switch). Durée non mesurée : pas de retry chronométré.
`REQUEST_REFUSED`	selon le gateway	Refus gateway à statut non mappé (ni 429 ni 503) : code neutre, recovery support/home. Aucun refus émis aujourd’hui ne le déclenche — gatewayCheck() ne renvoie que 429 et 503.
`VALIDATION_ERROR`	400	Payload invalide (Zod). Les détails sont dans `data.issues`.
`TRUST_ATTESTATION_WITHDRAWN`	410	Ancienne route d’attestation trust retirée : elle exposait un score interne sous une signature non vérifiable. Recovery : manifest signé /api/registry/verify/{ab_id} + JWKS.

Exemples cURL

1. Chercher un commerce local

curl -s "https://actionsbricks.com/api/registry/search?q=fromager&lat=48.8566&lng=2.3522&radius=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