{"human_readable_summary":"Kalicart Global is a public read-only federated product index. Use it to find candidate products and merchants; preserve merchant identity and final merchant URLs. Kalicart does not process checkout or payments.","profile":"light","full_discovery_url":"https://global.kalicart.com/v1/global-catalog/discovery?profile=full","reading_contract":{"schema_version":"1.1","principles":[{"code":"RESULTS_ARE_CANDIDATES","meaning":"Check name, category and match evidence against the user goal. A text or category match does not prove relevance."},{"code":"SNAPSHOT_NOT_LIVE","meaning":"provenance.fetched_at dates the indexed snapshot. Missing timestamps mean freshness is unknown. Verify the selected offer on the merchant Bridge."},{"code":"PRESERVE_REQUIREMENTS","meaning":"Broader searches are diagnostic. Do not describe candidates that lack a required property as satisfying it; disclose missing evidence and ask before substituting."}]},"handoff_protocol":{"FETCH_BRIDGE_PRODUCT":"Verify the selected candidate at handoff.bridge_product_url. Global price and stock are snapshots; final variant, price and availability require merchant verification.","OPEN_STOREFRONT_URL":"Direct the user to handoff.storefront_product_url. Disclose that live verification was unavailable; do not present snapshot price or stock as confirmed.","access_scope":"bridge_access describes the latest Global probe at observed_at, not reachability from your client. It does not verify this product.","on_verification_failure":"A timeout, denied request, challenge page, non-JSON body or unrelated product does not verify the offer. Use OPEN_STOREFRONT_URL; do not loop through retries or change user-agent to bypass the failure."},"intent_flags":{"single_merchant_only":false,"global_indexable":true,"federated_search_source":true,"agent_read_surface":true},"crawler_policy":{"allow_llm_training":false,"allow_live_agent_reads":true,"allow_global_indexing":true},"capabilities":{"search":true,"offers":true,"availability":true,"cart":false,"checkout":false,"payments":false,"mutations":false,"read_only":true},"freshness":{"inventory_freshness":"kalicart_sync_snapshot_aggregated","price_freshness":"merchant_authoritative","is_realtime_pos":false,"discovery_cache_ttl_seconds":900,"typical_index_cache_max_age_seconds":300},"provider":"kalicart","schema_version":"1.3","catalog_contract_version":"0.3-global-draft","discovery_kind":"kalicart_global","link_relation":"kalicart-catalog","discovery_document_url":"https://global.kalicart.com/v1/global-catalog/discovery","recommended_head_link_html":"<link rel=\"kalicart-catalog\" type=\"application/json\" href=\"https://global.kalicart.com/v1/global-catalog/discovery\" />","scope":{"type":"global_multi_merchant_catalog","invariant":"Federated read-only catalog pointers. Each product response must include explicit merchant identity. Kalicart does not mediate checkout or payments."},"discovery":{"catalog_kind":"global_multi_merchant","status":"draft","inclusion_policy":"Active synchronized merchant catalogs are included. Storefront head verification is reported as storefront_discovery status, not used as the sole inclusion gate.","updated_at":"2026-09-11T11:41:29.565Z"},"trust":{"read_only":true,"data":"aggregated snapshots from merchant catalogs","merchant_authority":"merchant-scoped bridge and merchant storefront","checkout_authority":"merchant_storefront","safe_for":["multi_merchant_search","merchant_discovery","offer_comparison","budget_filter"],"not_for":["payment","order_creation","checkout_execution","merchant_specific_final_validation"]},"agent_decision":{"use_global_for":"finding candidate products or merchants across the network","then_use":"merchant-scoped bridge/product URL for final merchant-specific verification","rule":"Do not treat global as checkout authority. Always preserve merchant identity and final merchant URL.","do_not_scrape_merchants":"Use the linked merchant product endpoint for verification. If unavailable or conflicting, disclose the unverified facts and direct the user to the storefront; do not reconstruct a catalog or guess which observation is current."},"how_to_query":{"start_with":"endpoints.products_search_url_template","search_url":"https://global.kalicart.com/v1/global-catalog/search?q={query}&fields=summary","meta_url":"https://global.kalicart.com/v1/global-catalog/meta","suggest_url":"https://global.kalicart.com/v1/global-catalog/suggest?q={term}","discovery_url":"https://global.kalicart.com/v1/global-catalog/discovery","rule":"Use q plus documented filters and fields=summary. Keep unsupported requirements for merchant verification. REST uses category/price_min/price_max; the global MCP uses leaf/min_price/max_price. A single-merchant MCP searches only its named store."},"answering_rules":{"flow":["search global","group by merchant","pick candidates under budget","preserve merchant identity","use merchant URL/bridge for final verification if needed","report total and limits"],"do_not_invent":"Missing facts are unverified on this surface, not necessarily unpublished by the merchant. Do not assert a match or a commercial fact without its evidence."},"well_known":{"bootstrap_json":"https://global.kalicart.com/.well-known/kalicart-global-discovery.json","discovery_profile_json":"https://global.kalicart.com/.well-known/kalicart-discovery-profile.json","note":"RFC 8615 .well-known; stable paths for crawlers and LLM toolchains without parsing HTML."},"endpoints":{"discovery_url":"https://global.kalicart.com/v1/global-catalog/discovery","meta_url":"https://global.kalicart.com/v1/global-catalog/meta","facets_url":"https://global.kalicart.com/v1/global-catalog/meta","suggest_url_template":"https://global.kalicart.com/v1/global-catalog/suggest?q={term}","merchants_index_url":"https://global.kalicart.com/v1/global-catalog/merchants","products_url":"https://global.kalicart.com/v1/global-catalog/products","products_search_url_template":"https://global.kalicart.com/v1/global-catalog/search?q={query}&fields=summary","categories_url":"https://global.kalicart.com/v1/global-catalog/categories","categories_tree_url_template":"https://global.kalicart.com/v1/global-catalog/categories/tree?root={category}","product_url_template":"https://global.kalicart.com/v1/global-catalog/product/{p2209_id}","merchants_lookup_url_template":"https://global.kalicart.com/v1/global-catalog/merchants/lookup?domain={domain}","merchants_lookup_hint":"Bridge Registry: ask whether a domain has exposed KaliCart Bridge. bridge_detected is historical, not proof of current reachability. Read federation_status separately from bridge_access; observed_at timestamps the latest Global probe. A miss schedules an async probe.","semantic_deltas_url_template":"https://global.kalicart.com/v1/global-catalog/semantic-deltas?since={cursor}","product_substitutes_url_template":"https://global.kalicart.com/v1/global-catalog/product/{p2209_id}/substitutes","product_checkout_ready_url_template":"https://global.kalicart.com/v1/global-catalog/product/{p2209_id}/checkout-ready"},"introspection":{"meta_url":"https://global.kalicart.com/v1/global-catalog/meta","facets_url":"https://global.kalicart.com/v1/global-catalog/meta","suggest_url_template":"https://global.kalicart.com/v1/global-catalog/suggest?q={term}","rule":"Search directly when the parameters are known. Use meta for available vocabulary, categories/tree?root=... to narrow a category, and suggest for filter vocabulary (not product autocomplete). Reuse these responses within the session; follow declared totals/pagination instead of treating a partial list as exhaustive."},"search_filters":{"q":"Bare product spine ONLY (single product noun), e.g. costume, t-shirt, boxer, prosecco. NEVER put brand, color, gender, size or price in q — use dedicated filters. Multi-word q is accepted but is an AND candidate search and may return accidental or routing-only matches; extract the noun and inspect match_origin/terms_in_name. See query_construction.","brand":"Brand facet, e.g. nike, zeybra. Use this for brand requests; do not put the brand in q.","category":"Kalicart category id or prefix, e.g. apparel.tops or apparel.swimwear.","gender":"Audience gender facet, e.g. male, female.","color":"Bridge color-family facet. Common IT/EN aliases are resolved to a value that exists in the active federated index. This is a broad family match, not proof of an exact shade: verify exact color on handoff.bridge_product_url.","price_min":"Lower bound of a price interval; matches overlapping variant price ranges in each offer currency. No FX conversion.","price_max":"Upper bound of a price interval; some variants of a matching product may exceed it. Verify the chosen variant and currency.","in_stock":"Product-level availability as of provenance.fetched_at — NOT a live guarantee and NOT per-variant. A product can be in_stock overall while the variant you want is not. Confirm on the merchant Bridge before quoting.","merchant":"Optional merchant_id to restrict results to one store; omit to search across all merchants.","fields":"Use fields=summary for shortlisting: identity, match evidence, snapshot price/stock, provenance and handoff. Verify only candidates needing additional evidence on their merchant Bridge. A summary with missing facts does not establish suitability. Alias: view=compact.","attr":"Semantic attribute filter, repeatable: attr=key:value (e.g. attr=material_primary:cotton&attr=color:black). AND across different keys, OR across values of the same key. Vocabulary is catalog-derived and exact: GET meta_url -> supported_filters.attr.accepted_values; use its listed canonical values, not top-level color aliases such as blu/azzurro unless they are listed there. Out-of-vocabulary values return an empty set."},"filters_not_on_this_surface":{"note":"These narrow a purchase, not a store choice: their truth is live on the merchant Bridge, never here. Follow handoff.bridge_product_url from any offer.","moved_to_bridge":["size","agent_size","availability (exact per-variant)","delivery_country","delivery_days_max","price_currency","material"],"guidance_code":"REFINE_ON_BRIDGE"},"query_construction":{"rule":"Use a concise product term in q and only documented structured filters. Preserve size, shipping and other unsupported requirements for merchant verification. A multi-term search can return relaxed candidates: read text_match and match_origin, then judge relevance to the original goal.","language_contract":{"canonical_values":"Use the canonical facet values published by meta, regardless of the user language.","index_language":"Text follows each merchant catalog language. Categories are canonical paths. A known category can retrieve across languages; a translation or equivalent term is a diagnostic retry, not proof of absence.","normalization_duty":"Normalizing from the user language to canonical tokens and to an Italian/English spine is the AGENT responsibility. The Italian aliases listed in accepted_values are server-side conveniences for the dominant traffic, not the coverage boundary of the system."},"color_contract":{"match_level":"bridge_color_family","exact_shade_guaranteed":false,"rule":"Use meta.supported_filters.color.accepted_values or suggest. An alias may be broadened to the available Bridge family; read filter_semantics.color in search results and verify an exact shade on the merchant Bridge."},"examples_note":"Wrong-query examples below are real Italian user utterances copied verbatim into q — the most common agent mistake on this catalog. The fix is always the same: extract the bare spine, move every attribute into its structured filter.","correct_examples":["?q=t-shirt&brand=nike&price_max=50&fields=summary   (verify offer currency and chosen variant)","?q=costume&gender=male&color=blue   (user said: \"costume da bagno blu da uomo\")","?q=boxer&brand=zeybra","?q=t-shirt&attr=material_primary:cotton   (user said: \"t-shirt di cotone\")"],"wrong_examples":["?q=t-shirt nike sotto i 50 euro  -> unreliable/usually zero (Italian utterance pasted into q; attributes stacked)","?q=costume da bagno blu da uomo  -> may return weak or routing-only candidates; use ?q=costume&gender=male&color=blue (attributes stacked in q)"],"cross_merchant_note":"To compare across stores, search once with the bare spine (no merchant filter) and group/compare the returned offers by merchant_id and price.","zero_results_recovery":"Zero means no results for this query and filters in the served snapshot. Use result_guidance for an evidence-based retry. Broader results do not satisfy removed requirements; disclose alternatives. Stop when no new evidence supports a retry and report no verified match, not product absence.","accepted_values":{"gender":{"canonical":["male","female","unisex"],"accepted_aliases":{"male":["male","men","man","uomo","m","maschio","maschile","homme","hommes","herren","herr","hombre","hombres"],"female":["female","women","woman","donna","f","femmina","femminile","femme","femmes","damen","dame","mujer","mujeres"],"unisex":["unisex","unisexe","unisesso"]},"match":"exact_token"},"color":{"note":"Use meta or suggest for active color-family values; filter_semantics declares the resolution actually used. Exact shade needs merchant verification."}}},"legacy_surfaces":{"note":"The legacy commerce_intent/* natural-language layer is RETIRED — those endpoints answer 410 Gone. Agents interpret the human request themselves and use products_search_url_template with structured filters (see query_construction)."},"authentication":{"required":false,"scheme":"none","global_public_catalog":"none","merchant_private_rest_and_mcp":"X-Api-Key (not used for global public reads)","notes":"Global /v1/global-catalog/* public reads require no API key. Merchant private REST/MCP on dashboard.kalicart.com uses X-Api-Key — not part of this federation surface."},"content_negotiation":{"default_content_type":"application/json; charset=utf-8","kalicart_vendor_content_type":"application/vnd.kalicart.global-discovery+json; charset=utf-8","how_to_request_vendor":"Send Accept: application/vnd.kalicart.global-discovery+json on GET https://global.kalicart.com/v1/global-catalog/discovery or GET https://global.kalicart.com/ — same JSON body; Content-Type echoes Kalicart global discovery semantics."}}