{"openapi":"3.1.0","info":{"title":"ActionsBricks Registry API","description":"Search, discover, and order from verified local French merchants. E-E-A-T trust verification protocol with HATEOAS navigation. All merchants are identity-verified. Attribution-neutral.","version":"1.0.0","contact":{"email":"gregg@actionsbricks.com"},"x-logo":{"url":"https://actionsbricks.com/icon.svg"}},"servers":[{"url":"https://actionsbricks.com","description":"Production"}],"components":{"schemas":{"AbId":{"type":"string","pattern":"^ab_[a-z0-9]{8}$","description":"ActionsBricks merchant ID (e.g. ab_7f3k9x2m)","example":"ab_7f3k9x2m"},"MerchantState":{"type":"object","properties":{"trust_score":{"type":"integer","minimum":0,"maximum":100},"merchant_status":{"type":"string","enum":["PROBATION","ACTIVE","PAUSED","SUSPENDED","ARCHIVED"]},"payment_setup":{"type":"boolean"},"can_receive_leads":{"type":"boolean"},"can_contact":{"type":"boolean"},"can_receive_orders":{"type":"boolean"}}},"HateoasAction":{"type":"object","properties":{"rel":{"type":"string"},"method":{"type":"string","enum":["GET","POST","PUT","DELETE"]},"href":{"type":"string","format":"uri"},"title":{"type":"string"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"type":{"type":"string"},"required":{"type":"boolean"}}}}}},"HateoasMeta":{"type":"object","properties":{"protocol":{"type":"string","example":"actionbricks/hateoas"},"version":{"type":"string","example":"1.0"},"timestamp":{"type":"string","format":"date-time"}}},"EEATBreakdown":{"type":"object","properties":{"experience":{"type":"integer","minimum":0,"maximum":25},"expertise":{"type":"integer","minimum":0,"maximum":25},"authority":{"type":"integer","minimum":0,"maximum":25},"trust":{"type":"integer","minimum":0,"maximum":25},"total":{"type":"integer","minimum":0,"maximum":100}}},"ErrorResponse":{"type":"object","properties":{"success":{"type":"boolean","example":false},"data":{"type":"null"},"_actions":{"type":"array","items":{"$ref":"#/components/schemas/HateoasAction"},"description":"Recovery actions for the AI agent"},"_links":{"type":"object"},"_state":{"type":"null"},"_meta":{"$ref":"#/components/schemas/HateoasMeta"}}},"LeadType":{"type":"string","enum":["estimation","contact","rdv","quote"]},"IntentData":{"type":"object","properties":{"urgency":{"type":"string","enum":["immediate","within_week","within_month","within_quarter","exploring"]},"budget_range":{"type":"string"},"project_type":{"type":"string"},"timeline":{"type":"string"},"preferred_contact":{"type":"string","enum":["email","phone","whatsapp","both"]}}}},"parameters":{"AbIdPath":{"name":"ab_id","in":"path","required":true,"schema":{"$ref":"#/components/schemas/AbId"},"description":"ActionsBricks merchant ID"}}},"paths":{"/api/registry/search":{"get":{"operationId":"searchMerchants","summary":"Search verified merchants","description":"Full-text search on merchants and products with optional geo and tag filters. Returns trust scores, products, and HATEOAS navigation actions.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1},"description":"Search query (e.g. \"chocolatier Lyon\")"},{"name":"tags","in":"query","schema":{"type":"string"},"description":"Comma-separated product tags"},{"name":"lat","in":"query","schema":{"type":"number"},"description":"Latitude for geo search"},{"name":"lng","in":"query","schema":{"type":"number"},"description":"Longitude for geo search"},{"name":"radius","in":"query","schema":{"type":"number","default":10},"description":"Radius in km (default 10)"},{"name":"limit","in":"query","schema":{"type":"integer","default":10,"maximum":50},"description":"Max results (default 10, max 50)"}],"responses":{"200":{"description":"Search results with merchants and products","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"query":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"merchant":{"type":"object","properties":{"ab_id":{"$ref":"#/components/schemas/AbId"},"name":{"type":"string"},"address":{"type":"string"},"rating":{"type":"number"},"review_count":{"type":"integer"},"trust_score":{"type":"integer"}}},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}}},"_actions":{"type":"array","items":{"$ref":"#/components/schemas/HateoasAction"}},"_state":{"$ref":"#/components/schemas/MerchantState"}}}},"count":{"type":"integer"},"_meta":{"$ref":"#/components/schemas/HateoasMeta"}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/registry/resolve/{ab_id}":{"get":{"operationId":"resolveMerchant","summary":"Get full merchant details by AB ID","description":"Resolve an ActionsBricks ID to full merchant data including products, trust score breakdown, credentials, and HATEOAS navigation.","parameters":[{"$ref":"#/components/parameters/AbIdPath"}],"responses":{"200":{"description":"Full merchant data with products and trust score","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"merchant":{"type":"object","properties":{"ab_id":{"$ref":"#/components/schemas/AbId"},"name":{"type":"string"},"address":{"type":"string"},"phone":{"type":"string"},"website":{"type":"string"},"trust":{"type":"object","properties":{"score":{"type":"integer"},"status":{"type":"string"},"breakdown":{"$ref":"#/components/schemas/EEATBreakdown"}}}}},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"price":{"type":"string"}}}},"credentials":{"type":"array","items":{"type":"object"}},"_actions":{"type":"object"},"_state":{"$ref":"#/components/schemas/MerchantState"},"_meta":{"$ref":"#/components/schemas/HateoasMeta"}}}}}},"404":{"description":"Merchant not found or trust too low","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/contact/brick":{"post":{"operationId":"contactMerchant","summary":"Create a lead/contact request for a merchant","description":"Submit a lead to contact a merchant. Supports estimation, contact, rdv, and quote types. AI context and intent data are accepted for richer leads. Auto-deduplication within 24h window.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ab_id","contact_name","contact_email","lead_type"],"properties":{"ab_id":{"$ref":"#/components/schemas/AbId"},"contact_name":{"type":"string","minLength":1},"contact_email":{"type":"string","format":"email"},"contact_phone":{"type":"string"},"lead_type":{"$ref":"#/components/schemas/LeadType"},"message":{"type":"string"},"ai_context":{"type":"string","maxLength":5000,"description":"AI conversation context for richer lead qualification"},"intent_data":{"$ref":"#/components/schemas/IntentData"}}}}}},"responses":{"200":{"description":"Lead deduplicated (already exists within 24h)","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"tracking_token":{"type":"string"},"deduplicated":{"type":"boolean","example":true}}}}}},"201":{"description":"Lead created","content":{"application/json":{"schema":{"type":"object","properties":{"lead_id":{"type":"string","format":"uuid"},"tracking_token":{"type":"string"},"tracking_status":{"type":"string","example":"received"},"_actions":{"type":"object"},"_state":{"$ref":"#/components/schemas/MerchantState"},"_meta":{"$ref":"#/components/schemas/HateoasMeta"}}}}}},"400":{"description":"Validation error or contact disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Merchant not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/trust/attestation/{ab_id}":{"get":{"operationId":"getTrustAttestation","summary":"Get verifiable trust attestation (ED25519 signed)","description":"Returns the EEAT trust score with a cryptographic signature for verification. Agents can use the public key endpoint to verify the signature.","parameters":[{"$ref":"#/components/parameters/AbIdPath"}],"responses":{"200":{"description":"Signed trust attestation","content":{"application/json":{"schema":{"type":"object","properties":{"ab_id":{"$ref":"#/components/schemas/AbId"},"trust_score":{"type":"integer"},"trust_breakdown":{"$ref":"#/components/schemas/EEATBreakdown"},"trust_hash":{"type":"string"},"signature":{"type":"string","description":"ED25519 signature"},"signed_at":{"type":"string","format":"date-time"},"public_key_url":{"type":"string","format":"uri"}}}}}},"400":{"description":"Invalid ab_id format"},"404":{"description":"Merchant not found"}}}},"/api/agents/register":{"post":{"operationId":"registerAgent","summary":"Register an AI agent and receive an API key","description":"4-level certification: L1 Reader, L2 Inquirer, L3 Commercial, L4 Transactional. L1-L2 auto-approved. L3-L4 require manual verification. API key is shown ONCE — save it.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_name","contact_email","requested_level"],"properties":{"agent_name":{"type":"string"},"agent_url":{"type":"string","format":"uri"},"contact_email":{"type":"string","format":"email"},"requested_level":{"type":"integer","minimum":1,"maximum":4,"description":"1=Reader, 2=Inquirer, 3=Commercial, 4=Transactional"},"capabilities":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"201":{"description":"Agent registered — API key shown once","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"agent_id":{"type":"string"},"api_key":{"type":"string","description":"Shown ONLY ONCE. Save it."},"certification_level":{"type":"integer"},"permissions":{"type":"array","items":{"type":"string"}},"rate_limit_hourly":{"type":"integer"},"status":{"type":"string","enum":["active","pending_verification"]}}}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/agents/verify":{"get":{"operationId":"verifyAgent","summary":"Verify an agent API key","description":"Check if an API key is valid and return agent certification details.","parameters":[{"name":"token","in":"query","required":true,"schema":{"type":"string"},"description":"API key to verify"}],"responses":{"200":{"description":"Verification result","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean"},"agent_name":{"type":"string"},"certification_level":{"type":"integer"},"permissions":{"type":"array","items":{"type":"string"}},"rate_limit_hourly":{"type":"integer"}}}}}}}}},"/api/merchants/{ab_id}/jsonld":{"get":{"operationId":"getMerchantJsonLd","summary":"Get Schema.org JSON-LD structured data","description":"Returns full Schema.org LocalBusiness JSON-LD with potentialAction, hasCredential, sameAs, and offers for SEO and AI discovery.","parameters":[{"$ref":"#/components/parameters/AbIdPath"}],"responses":{"200":{"description":"JSON-LD Schema.org structured data","content":{"application/ld+json":{"schema":{"type":"object","properties":{"@context":{"type":"string","example":"https://schema.org"},"@type":{"type":"string","example":"LocalBusiness"},"name":{"type":"string"},"url":{"type":"string"},"telephone":{"type":"string"},"potentialAction":{"type":"array","items":{"type":"object"}},"hasCredential":{"type":"array","items":{"type":"object"}},"sameAs":{"type":"array","items":{"type":"string"}}}}}}},"404":{"description":"Merchant not found"}}}},"/api/orders/create":{"post":{"operationId":"createOrder","summary":"Create an order with Stripe payment","description":"Create an order for merchant products. Returns a Stripe Checkout payment link. Requires merchant trust >= 55 and Stripe Connect setup.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["merchant_id","product_ids","quantities","fulfillment_type"],"properties":{"merchant_id":{"type":"string"},"product_ids":{"type":"array","items":{"type":"string"}},"quantities":{"type":"array","items":{"type":"integer","minimum":1}},"fulfillment_type":{"type":"string","enum":["pickup","delivery"]},"delivery_address":{"type":"object","properties":{"street":{"type":"string"},"city":{"type":"string"},"postal_code":{"type":"string"},"country":{"type":"string"},"phone":{"type":"string"}}},"user_email":{"type":"string","format":"email"},"customer_notes":{"type":"string"}}}}}},"responses":{"201":{"description":"Order created with payment link","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"order_id":{"type":"string"},"payment":{"type":"object","properties":{"client_secret":{"type":"string"},"payment_intent_id":{"type":"string"},"payment_link":{"type":"string","format":"uri","description":"Stripe Checkout URL"},"amount":{"type":"integer","description":"Amount in centimes"},"currency":{"type":"string","example":"eur"}}},"_actions":{"type":"object"},"_state":{"$ref":"#/components/schemas/MerchantState"},"_meta":{"$ref":"#/components/schemas/HateoasMeta"}}}}}},"400":{"description":"Validation error or order disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Trust too low for orders","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/contact/platform":{"post":{"operationId":"contactPlatform","summary":"Contact the ActionsBricks team","description":"Send a message to ActionsBricks for merchant inquiries, partnerships, or support.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type","name","email","message"],"properties":{"type":{"type":"string","enum":["merchant_inquiry","partnership","support"]},"name":{"type":"string","maxLength":100},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":20},"company":{"type":"string","maxLength":200},"message":{"type":"string","minLength":1,"maxLength":1000}}}}}},"responses":{"201":{"description":"Message received","content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"string"},"status":{"type":"string","example":"received"}}}}}},"400":{"description":"Validation error"},"429":{"description":"Rate limited"}}}},"/api/mcp":{"post":{"operationId":"mcpToolCall","summary":"MCP Server — JSON-RPC 2.0 tool invocation","description":"Model Context Protocol endpoint for AI agent tool calls. Supports 11 tools: search_merchants, resolve_merchant, contact_merchant, get_trust_score, check_availability, compare_merchants, check_lead_status, send_lead_message, get_lead_fields, submit_lead, get_product_details, check_certifications, contact_actionbricks. See /.well-known/mcp.json for full tool schemas.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"method":{"type":"string","description":"JSON-RPC method: initialize, tools/list, or tools/call"},"params":{"type":"object","description":"For tools/call: { name: \"tool_name\", arguments: {...} }"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response with tool result","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","example":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"429":{"description":"Rate limited"}}}}}}