# KAIBEAUTY - AI Agent Interface

> KAIBEAUTY (kaibeauty.me) sells Korean beauty products to customers outside Korea, with AI skin analysis and ingredient-based recommendations.
> This document describes the endpoints AI agents can use to search products, read ingredient information with its source, get item prices and create Shopify checkout links.

## How to read our product data

- **Every product has a fact sheet.** Ingredient data, derived properties, skin goals and country findings come from it. A value we cannot back with a recorded source is `unknown`, never an empty "free of" answer.
- **Ingredients come with their source or not at all.** `ingredients_status` is `known` (recorded source: see `evidence` and `ingredients_source_url`), `unknown`, `conflict` (the source contradicts the product, e.g. a sunscreen list without any UV filter; not shown) or `not_applicable` (sets: each component has its own list). Many products are still `unknown`.
- **Evidence:** `evidence.review` is `reviewed` (a person compared it with the source), `machine_checked` (code verified it against the source) or `source_listed` (as the retailer lists it). `evidence.method` names the source kind, e.g. `official_mall_page`.
- **INCI names come from the Korean standard ingredient dictionary**, not from translation. `ingredients_label_text` is the source text; items the dictionary does not know are counted in `unmatched_count` and shown as printed.
- **Properties** (`fragrance`, `fragrance_allergens`, `essential_oils`, `ethanol`, `retinoids`, `aha`, `bha`, `uv_filters`, `propellant_gas`) are `present`, `absent` or `unknown`. `absent` is given only for a complete list with every item matched; essential oils are never asserted absent.
- **Country findings:** pass `country` to get that country's finding. `sellable_with_warning` means an ingredient is outside that country's list (warning only). No finding does not mean a product meets every rule of that country. Currently loaded: US sunscreen active ingredients (FDA, as of 2026-10-16).
- **Purchase to order:** items are sourced from suppliers in Korea after the order is placed, so dispatch includes a sourcing period and availability is confirmed after ordering.
- **Shipping, taxes and duties** are calculated at Shopify checkout for the delivery address and shown before payment. Our quote covers item prices only.

## MCP server

- **Endpoint:** `POST https://platform.kaibeauty.me/mcp` (Model Context Protocol, Streamable HTTP, no sign-in). Protocol versions 2026-07-28 (stateless, `server/discover`) and 2025-03-26 through 2025-11-25 (`initialize`) are both served.
- **Tools:** `search_products`, `get_product` (complete fact sheet), `get_price_quote`, `create_checkout_link`. The first three are read-only; `create_checkout_link` only returns a payment link and charges nothing.
- The tools return exactly what the REST API below returns, including `ingredients_status` and `evidence`. Rate limits apply (60 reads and 10 checkout links per minute per client).

## Agent API Endpoints

- `GET /api/agent/products`: Search by keyword, category, skin concern, an ingredient or group to avoid, and destination country. Ingredient filters only return products whose fact sheet establishes the answer.
- `GET /api/agent/products/{id}`: One product with its complete fact sheet document.
- `POST /api/agent/quote`: Item prices in USD for products on sale.
- `POST /api/agent/checkout`: Create a Shopify checkout link with the cart pre-filled; the customer reviews the final total before paying.
- `GET /api/agent/tools.json`: Tool schemas for OpenAI Function Calling and Claude Tool Use.

For request and response details, see `/llms-full.txt` or `/api/agent/tools.json`.