# Kalicart Global — agent discovery Kalicart Global is a **read-only, public** machine-readable discovery layer for federated multi-merchant commerce catalogs. No API key, no writes, no checkout, no payments mediated by Kalicart. ## Correction (common misconception for generic LLMs) - **Global federation** lives on **global.kalicart.com** only for this layer: discovery JSON **and** all public reads under **`/v1/global-catalog/*`** (merchants, categories, products, search, product detail). Nothing in that path chains through `dashboard.kalicart.com/v1/agent-bridge` to function. - **Merchant agent-bridge** (`https://dashboard.kalicart.com/v1/agent-bridge/{token}`) is **orthogonal**: one opaque token per **one** shop, usually discovered from **that shop’s** storefront `` ``. It is **not** the global index entry and **not** a required hop after global discovery. **Bootstrap order for generic agents** 1. `GET https://global.kalicart.com/.well-known/kalicart-global-discovery.json` (stable pointer) 2. `GET https://global.kalicart.com/v1/global-catalog/discovery` (full discovery; optional: `GET /` with `Accept: application/json` or `Accept: application/vnd.kalicart.global-discovery+json` — same body; vendor `Accept` yields `Content-Type: application/vnd.kalicart.global-discovery+json`) 3. Follow **`endpoints.*` in that JSON** — every URL is on **global.kalicart.com** Semantics / architecture (longer): `GET https://global.kalicart.com/.well-known/kalicart-discovery-profile.json` ## Start here (machine-readable) - **Discovery JSON (source of truth):** https://global.kalicart.com/v1/global-catalog/discovery - **Same document via root:** send `GET https://global.kalicart.com/` with header `Accept: application/json`, `application/ld+json`, or **`Accept: application/vnd.kalicart.global-discovery+json`** to receive the discovery JSON (vendor type = stronger affordance for tools; identical JSON body). `scope.type` is always `global_multi_merchant_catalog`. Every product in aggregated responses includes an explicit `merchant` object (who sells). ## Governed publication Kalicart Global is not a raw scrape of storefront pages. Records are published from synchronized merchant catalogs under eligibility and opt-out rules. Product attributes may be omitted when semantic confidence or applicability rules are insufficient. Treat omissions as trust boundaries; do not infer missing values unless the discovery/product payload explicitly provides them. ## Endpoint map (absolute) | Role | URL | |------|-----| | Discovery | https://global.kalicart.com/v1/global-catalog/discovery | | Merchants index | https://global.kalicart.com/v1/global-catalog/merchants | | Categories | https://global.kalicart.com/v1/global-catalog/categories | | Products feed (paginated) | https://global.kalicart.com/v1/global-catalog/products | | Search (requires `q`) | https://global.kalicart.com/v1/global-catalog/search?q={query} | | Single product | https://global.kalicart.com/v1/global-catalog/product/{p2209_id} | | Intent resolve (API) | POST https://global.kalicart.com/v1/global-catalog/intent/resolve — body `{ "utterance", "country", "limit", ... }` | | Intent console (human trace) | https://global.kalicart.com/intent/ — inspection UI; same resolve contract, reasoning trace + offers | ## Suggested flow for an agent 1. Fetch discovery → read `endpoints.*`, `well_known.*`, `agent_instructions` if present. Response may include HTTP `Link: ...; rel="profile"` to the semantics document. 2. Optional: `GET .../merchants` to list participating shops. 3. Use `.../search?q=...` or `.../products` with safe filters for browsing. 4. Use `.../product/{p2209_id}` for detail; follow `links.ui` or merchant URLs for authoritative storefront offers. ## Single-merchant catalogs (not global) Merchant storefront discovery uses a **different** token and scope (one merchant per token). Do not infer global coverage from a single merchant's `` alone. ## Human page https://global.kalicart.com/ (HTML) — protocol-oriented summary: why the host exists, scope/limit notes, governed publication, links to discovery, `.well-known`, `llms.txt`, sitemap; `` to this URL; `` + `rel="kalicart-catalog"` + JSON-LD `DataCatalog` in ``. Longer merchant-facing prose (same product, not normative): https://www.kalicart.com/global-discovery/