{"name":"Youflorist Product API","version":"1.5.0","description":"API for AI agents to browse the Youflorist catalog and discover original editorial-data tools. All prices in EUR. Supports JSON and Markdown content negotiation.","base_url":"/api/aeo","content_negotiation":{"description":"Product detail negotiates JSON or Markdown using Accept quality weights and Vary: Accept. Product lists and categories return JSON; category FAQ returns Markdown.","formats":{"application/json":"JSON response (default)","text/markdown":"Structured Markdown response (product endpoints)"}},"endpoints":{"products":{"method":"GET","path":"/api/aeo/products","description":"List products with filters and pagination. Prices include current storefront discounts; regular_price fields preserve the catalogue reference. Price filters and sorting retain their regular-catalogue basis (price_filter_basis).","params":{"q":{"type":"string","description":"Word-AND search over product names and slugs"},"category":{"type":"string","description":"SEO category slug or legacy category ID"},"color":{"type":"string","description":"Filter by color name"},"min_price":{"type":"number","description":"Minimum regular catalogue price in EUR"},"max_price":{"type":"number","description":"Maximum regular catalogue price in EUR"},"sort":{"type":"string","enum":["name","price_asc","price_desc"],"default":"name"},"locale":{"type":"string","enum":["es","fr","pt","ca","gl","eu"],"default":"es"},"page":{"type":"number","default":1},"per_page":{"type":"number","default":20,"max":50},"mode":{"type":"string","enum":["seo","legacy"],"default":"seo"}}},"product_detail":{"method":"GET","path":"/api/aeo/products/{id}","description":"Get full details for a single product by slug or ID. Supports content negotiation (Accept: text/markdown for Markdown).","params":{"locale":{"type":"string","default":"es"},"mode":{"type":"string","enum":["seo","legacy"],"default":"seo"}},"content_types":{"application/json":"JSON product data (default)","text/markdown":"Same published product data: localized canonical URL, product and variant IDs, retail prices, availability, supplier minimum and declared measure. Supplier minimum can describe lot content or a purchase minimum: do not interpret it as order quantity or pieces per sales unit. Unknown fields stay unknown; no care claims are inferred from category IDs."}},"product_markdown":{"method":"GET","path":"/api/aeo/products/{id}/markdown","description":"Dedicated Markdown endpoint for a single product. Always returns text/markdown.","params":{"locale":{"type":"string","default":"es"},"mode":{"type":"string","enum":["seo","legacy"],"default":"seo"}}},"categories":{"method":"GET","path":"/api/aeo/categories","description":"List all product categories","params":{"locale":{"type":"string","default":"es"},"mode":{"type":"string","enum":["seo","legacy"],"default":"seo"}}},"category_faq":{"method":"GET","path":"/api/aeo/categories/{id}/faq","description":"The same FAQ shown on the category page and in FAQPage, in Markdown. Supports es, fr, pt, ca, gl and eu via locale (default es); unsupported locales return 400. Legacy-only category IDs have no published FAQ items.","params":{"locale":{"type":"string","default":"es"}},"content_types":{"text/markdown":"Always returns Markdown (no JSON variant)"}},"docs":{"method":"GET","path":"/api/aeo/docs","description":"This documentation"}},"editorial_tools":{"description":"Public JSON tools backed by the live catalog or Youflorist's documented plant datasets.","endpoints":{"wedding_event_budget":{"method":"GET","path":"/api/herramientas/presupuesto-evento","params":["personal_bouquets","guest_tables","table_size","bud_vases","ceremony_pieces","greenery_percent","room_length","room_width","guests","layout"],"caveat":"Room layout is indicative; material PVP excludes design, labour, vessels, transport, installation and removal."},"wedding_scene_render":{"method":"POST","path":"/api/herramientas/escena-boda","params":["length","width","guests","tableCount","layout","style"],"authentication":"User session required","caveat":"The image is returned only after a second model verifies exact visible table count, layout and floral presence; maximum 24 tables per scene."},"pet_safe_available_plants":{"method":"GET","path":"/api/herramientas/pet-friendly","params":["environment","max_price","locale"],"response":"Versioned JSON with query, observation time, sources and live product links.","caveat":"Closed safe-genus whitelist; unidentified mixes are excluded and non-toxic never means edible."},"plant_photoperiod":{"method":"GET","path":"/api/herramientas/fotoperiodo","params":["city","latitude","longitude","location_name","plant","date","locale"],"response":"Versioned JSON with explicit units, calculation timestamp, sources, biological threshold and catalog search URL.","caveat":"Solar calculation plus documented plant thresholds, not a flowering guarantee."},"window_direct_sun":{"method":"GET","path":"/api/herramientas/sol-ventana","params":["latitude","longitude","date","time_zone","orientation","depth","lateral_offset","window_width","sill_height","top_height","leaf_height","overhang_depth","obstacle_elevation","include_samples","format"],"response":"Version 2. Five-minute geometric direct-sun intervals in solar and local civil time, plus Solana's clear-sky outdoor DLI reference. include_samples=1 returns 288 calculated rows; format=csv downloads them with all input dimensions.","caveat":"An idealized uniform skyline and horizontal overhang are supported. Outdoor DLI is an FAO-56 estimate for a horizontal surface, not indoor DLI. Diffuse indoor light, clouds, glazing, PPFD and species suitability are not calculated."},"vase_bouquet_preflight":{"method":"GET","path":"/api/herramientas/encaje-jarron","params":["flower","stems","stem_length_cm","vase_height_cm","mouth_diameter_cm","base_diameter_cm","dry_vase_g","water_ml","locale"],"response":"Versioned JSON with measured median flower weight, an optional physical preflight, a closed 12-vase geometry study and currently available variants with supplier-declared dimensions and product URLs.","caveat":"The declared-geometry study calculates areas and dimensionless ratios without inferring vessel weight or capacity. A promising physical preflight is not a stability certificate."}},"mcp_endpoint":"/api/mcp"},"agent_commerce":{"manifest":"/agents.json","mcp_endpoint":"/api/mcp","tool_inventory":"Call MCP tools/list for the current tool names and input schemas.","registration":"POST /api/agent/register returns a partner API key once. Registration limits are separate from catalog read limits.","policies":"/api/agent/policies","shipping_quote":"/api/shipping/quote","orders":"POST /api/agent/orders with Authorization: Bearer <api_key>. Use variant IDs and keep the same Idempotency-Key when retrying the same REST submission.","mcp_order_retries":"Supply create_order.idempotency_key (1–128 printable ASCII characters) before submission and reuse it unchanged for retries, including after a timeout. Keep the buyer-confirmed items and recipient unchanged; use a new key for a new order. The result returns the key. Without a supplied key each call generates a fresh key and must not be repeated blindly. REST accepts the same key in the Idempotency-Key header.","mcp_order_locale":"create_order.locale accepts es, fr, pt, ca, gl or eu for the buyer's payment link (default es).","payment":"Read policies.payment at runtime for availability, network and asset. x402 v1 uses X-PAYMENT and X-PAYMENT-RESPONSE; the 402 challenge supplies exact requirements. Never assume testnet or mainnet."},"rate_limits":{"requests_per_minute":60,"headers":{"X-RateLimit-Remaining":"Requests left in current window","X-RateLimit-Reset":"Unix timestamp when the window resets"}},"examples":{"browse_roses":"GET /api/aeo/products?category=rosas","red_flowers_under_50":"GET /api/aeo/products?color=rojo&max_price=50","product_detail_json":"GET /api/aeo/products/ramo-rosas-rojas","product_detail_markdown":"curl -H 'Accept: text/markdown' /api/aeo/products/ramo-rosas-rojas","product_markdown_endpoint":"GET /api/aeo/products/ramo-rosas-rojas/markdown","category_faq":"GET /api/aeo/categories/1/faq","all_categories":"GET /api/aeo/categories","wedding_material":"GET /api/herramientas/presupuesto-evento?guest_tables=12&table_size=medium","pet_safe_indoor":"GET /api/herramientas/pet-friendly?environment=interior&max_price=50","chrysanthemum_photoperiod":"GET /api/herramientas/fotoperiodo?city=madrid&plant=crisantemo&date=2026-10-15","custom_location_photoperiod":"GET /api/herramientas/fotoperiodo?latitude=41.3874&longitude=2.1686&plant=Dalia&date=2026-08-26","window_direct_sun":"GET /api/herramientas/sol-ventana?latitude=39.4699&longitude=-0.3763&date=2026-10-15&orientation=165&depth=1&window_width=1.4&time_zone=Europe%2FMadrid","vase_bouquet_preflight":"GET /api/herramientas/encaje-jarron?flower=alstroemeria&stems=12&stem_length_cm=45&vase_height_cm=24&mouth_diameter_cm=8&base_diameter_cm=16&dry_vase_g=900&water_ml=900"}}