search_products
Search or browse Kifly's product catalog across every seller on the network. Multilingual semantic search (100+ languages); omit q to browse recent listings. Several items? Pass q as an array (up to 5), one query per item, in the shopper's words: each gets its share of the page, labelled kifly:matchedQuery ; kifly:queryResults says which found nothing. Too many hits? Ask once with facets: true , then narrow with delivers to , price, category or seller handle ; page with cursor when kifly:hasMore . Returns a JSON-LD ItemList. Rules that matter before you read the response: - Cart every product
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"q": {
"anyOf": [
{
"type": "string",
"maxLength": 500,
"minLength": 1
},
{
"type": "array",
"items": {
"type": "string",
"maxLength": 500,
"minLength": 1
},
"maxItems": 5,
"minItems": 1
}
],
"description": "Query, or up to 5: one per item the shopper wants, in their words. Omit to browse."
},
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 64,
"minLength": 1
},
"maxItems": 20,
"minItems": 1,
"description": "Instead of q: these products whole, with full description and care/ingredients"
},
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"size": {
"type": "string",
"maxLength": 200,
"description": "With q: only products whose recorded size matches"
},
"color": {
"type": "string",
"maxLength": 200,
"description": "With q: only products whose recorded colour matches; commas list alternatives"
},
"limit": {
"type": "integer",
"maximum": 20,
"minimum": 1,
"description": "Max results per page (default 10)."
},
"cursor": {
"type": "string",
"description": "kifly:nextCursor from the previous page; carries q and filters"
},
"facets": {
"type": "boolean",
"description": "Add kifly:facets counts over all matches"
},
"sort_by": {
"enum": [
"relevance",
"price_asc",
"price_desc",
"newest"
],
"type": "string",
"description": "Sort order (default: relevance)"
},
"category": {
"type": "string",
"description": "Category, e.g. a kifly:facets value"
},
"material": {
"type": "string",
"maxLength": 200,
"description": "With q: only products whose recorded material matches"
},
"delivers_to": {
"type": "object",
"required": [
"country"
],
"properties": {
"city": {
"type": "string"
},
"region": {
"type": "string"
},
"country": {
"type": "string",
"maxLength": 2,
"minLength": 2
},
"postal_code": {
"type": "string"
}
},
"description": "Only sellers delivering here, e.g. {country:'US',region:'CA'}",
"additionalProperties": false
},
"in_stock_only": {
"type": "boolean",
"description": "In-stock only"
},
"seller_handle": {
"type": "string",
"description": "Scope to one seller's catalog"
},
"max_price_cents": {
"type": "integer",
"minimum": 0,
"description": "Max price, cents"
},
"min_price_cents": {
"type": "integer",
"minimum": 0,
"description": "Min price, cents"
}
},
"additionalProperties": false
}
create_cart
Create a new shopping cart on Kifly. For network (cross-seller) tokens you MUST pass seller handle — each cart is bound to exactly one seller. Get the handle from search products results (every item's kifly:seller IS the handle in network results) or get seller. Seller-scoped tokens may omit the handle — their own seller is implicit. Returns a cart id to use with add to cart and checkout. The response's seller.kifly purchasable (and seller.fulfillment ) tells you upfront where the buyer pays — false / "external" means the buyer pays on the seller's own site: build the cart as usual; checkout h
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"seller_handle": {
"type": "string",
"description": "Seller handle (e.g. 'bay-clothing-district'). Required for network tokens; ignored for seller-scoped tokens."
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
}
},
"additionalProperties": false
}
add_to_cart
Requires cart:write , or no key: send meta.ucp-agent.profile . Add a product variant to an existing cart. Use the variant id from search products results. Returns full cart state including item ids you can use with update cart item. Max quantity per item and max cart total are enforced — call get platform limits to check the current limits before building a large cart. Exceeding the per-item limit returns 400 QUANTITY EXCEEDS LIMIT ; exceeding the cart total returns 400 CART TOTAL EXCEEDS LIMIT at checkout. cart.kifly purchasable (and cart.fulfillment ) carries the same signal as create cart's
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id",
"variant_id"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"quantity": {
"type": "integer",
"default": 1,
"minimum": 1,
"description": "Quantity to add"
},
"variant_id": {
"type": "string",
"description": "Product variant ID from search_products results"
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
}
},
"additionalProperties": false
}
get_cart
Inspect the current state of a cart — line items, quantities, prices, and shipping address. Each item includes an item id you can pass to update cart item to change quantity or remove the item. Call this after add to cart to review the cart before checkout, or any time the buyer asks what's in the cart. kifly purchasable: false ( fulfillment: "external" ) means checkout on this cart hands the buyer to the seller's own site to pay: say so, so the buyer knows where they will pay.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
}
},
"additionalProperties": false
}
update_cart_item
Requires cart:write , or no key: send meta.ucp-agent.profile . Change the quantity of a line item in an open cart, or remove it entirely. Set quantity to 0 to remove the item. Get the item id from get cart or the cart field in the add to cart response. Returns the updated cart state. The per-item quantity ceiling applies here too — call get platform limits to check the current limit. Exceeding it returns 400 QUANTITY EXCEEDS LIMIT .
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id",
"item_id",
"quantity"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"item_id": {
"type": "string",
"description": "Item ID from get_cart or add_to_cart response"
},
"quantity": {
"type": "integer",
"minimum": 0,
"description": "New quantity (0 removes the item)"
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
}
},
"additionalProperties": false
}
set_shipping_address
Requires cart:write , or no key: send meta.ucp-agent.profile . Persist a shipping address on the cart and confirm the seller can deliver to it. Call BEFORE checkout . Returns delivery eligible . When true it also returns cart total with delivery cents — quote that full price before sending the buyer to pay, unless shipping priced at is merchant checkout : then fee and total are null because the seller's own checkout prices shipping; say so, never call shipping free. When false, no address is saved and delivery coverage says where the seller does cover, so you can retry with a covered address.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id",
"shipping_address"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
},
"shipping_address": {
"type": "object",
"required": [
"name",
"line1",
"city",
"region",
"postal_code"
],
"properties": {
"city": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"name": {
"type": "string",
"maxLength": 150,
"minLength": 1,
"description": "Buyer's full name"
},
"line1": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Street address line 1"
},
"line2": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Street address line 2 (apt, suite)"
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Optional contact phone for delivery"
},
"region": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "US state code (e.g. 'CA', 'NE') — matched against seller's delivery_coverage.states"
},
"country": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "ISO 3166-1 alpha-2 country code"
},
"postal_code": {
"type": "string",
"maxLength": 20,
"minLength": 3,
"description": "Postal/ZIP code"
}
},
"description": "Structured shipping address collected conversationally from the buyer",
"additionalProperties": false
}
},
"additionalProperties": false
}
quick_buy
Requires cart:write scope. Create a cart, add items, and set the shipping address in ONE call — the fast path when you already know the seller, the exact variant(s), and the buyer's address (e.g. a reorder, or a buyer who has decided). Prefer this over the create cart → add to cart → set shipping address sequence to save round trips; those granular tools stay available for exploratory, multi-step carts. You must call search products first so Kifly knows each variant's seller (quick buy returns 422 VARIANT SNAPSHOT MISSING otherwise). One cart = one seller: every item must belong to the same se
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"items",
"shipping_address"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"variant_id",
"quantity"
],
"properties": {
"quantity": {
"type": "integer",
"minimum": 1,
"description": "Quantity to add"
},
"variant_id": {
"type": "string",
"minLength": 1,
"description": "Product variant ID from search_products results"
},
"measure_amount": {
"type": "number",
"description": "Sold-by-measure amount (e.g. 0.4 oz) for variants priced by measure; omit for fixed-price variants",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"maxItems": 50,
"minItems": 1,
"description": "Line items to add — all must belong to the same seller"
},
"seller_handle": {
"type": "string",
"pattern": "^[a-z0-9-]+$",
"maxLength": 40,
"minLength": 3,
"description": "Seller handle from search_products. REQUIRED for network tokens; omit for seller-scoped tokens (their own seller is implicit)."
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
},
"shipping_address": {
"type": "object",
"required": [
"name",
"line1",
"city",
"region",
"postal_code"
],
"properties": {
"city": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"name": {
"type": "string",
"maxLength": 150,
"minLength": 1,
"description": "Buyer's full name"
},
"line1": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Street address line 1"
},
"line2": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Street address line 2 (apt, suite)"
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
],
"description": "Optional contact phone for delivery"
},
"region": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "US state code (e.g. 'CA', 'NE') — matched against seller's delivery_coverage.states"
},
"country": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "ISO 3166-1 alpha-2 country code"
},
"postal_code": {
"type": "string",
"maxLength": 20,
"minLength": 3,
"description": "Postal/ZIP code"
}
},
"description": "Structured shipping address collected conversationally from the buyer",
"additionalProperties": false
},
"external_customer_ref": {
"type": "string",
"maxLength": 255,
"minLength": 1,
"description": "Embedded-commerce pass-through: the seller's own opaque customer id for a cart from their embed widget. Omit unless you are the embed flow."
}
},
"additionalProperties": false
}
checkout
Requires checkout:write or checkout:link , or no key: send meta.ucp-agent.profile for the same payment link. Checkout is always human-in-the-loop: it returns a link the buyer opens and confirms — it never charges a card or completes an order on its own. Call set shipping address first unless fulfillment is "external" (the seller's site collects the address). Cart total must not exceed the platform cap ( kifly://platform/limits ). To pre-fill the buyer's email on the payment page, pass email — ask the buyer for it in plain language ('what email should the receipt go to?'). Never ask the buyer t
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"cart_id"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"email": {
"type": "string",
"format": "email",
"description": "Buyer's email, collected conversationally. Pre-fills the Stripe Checkout email field so the buyer doesn't retype it. This is ALL you need to pre-fill email — ask the buyer for their email, never for a token."
},
"cart_id": {
"type": "string",
"description": "Cart ID from create_cart"
},
"buyer_token": {
"type": "string",
"description": "INTERNAL token (kfb_live_...) minted by register_buyer / verify_buyer — resolves the buyer's saved profile and pre-fills their email on the payment link. NEVER ask the buyer to paste this. Omit it unless you already obtained one programmatically this session; to pre-fill email, use `email` instead."
},
"idempotency_key": {
"type": "string",
"maxLength": 64,
"minLength": 16,
"description": "Your own retry key (16-64 chars). Resend the SAME key to retry safely."
}
},
"additionalProperties": false
}
register_buyer
Start registering a buyer so they can be recognized across future purchases without re-entering their details. Takes the buyer's email and name and always emails a 6-digit verification code — the response is { verification required: true } whether the email is brand new or already has an account (so this call alone never reveals which). Ask the buyer to read you the code from their inbox, then call verify buyer with the same email + code to get a buyer token ( kfb live ... ). Store that token and pass it to checkout on every future order — it pre-fills the buyer's email on the secure Stripe pa
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email",
"name"
],
"properties": {
"name": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Buyer's full name"
},
"email": {
"type": "string",
"format": "email",
"description": "Buyer's email address"
}
},
"additionalProperties": false
}
request_buyer_code
Send a 6-digit verification code to a returning buyer's email so they can prove the account is theirs and recover their saved name + shipping address on this connection — without pasting any token or re-entering their name. Call this when the buyer says they've shopped with Kifly before and gives you their email; then ask them to read you the code from their inbox and call verify buyer . Always returns { sent: true } , whether or not the email has a Kifly account. If the buyer never receives a code, they likely don't have an account yet: call register buyer instead, which creates one and email
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email"
],
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "The returning buyer's email address"
}
},
"additionalProperties": false
}
verify_buyer
Verify the 6-digit code a returning buyer received by email (from request buyer code ). On success returns { buyer token, buyer profile id } — pass the buyer token to get buyer profile to auto-fill their saved name + shipping address, and to checkout to pre-fill their email on the payment link. Fails with invalid otp if the code is wrong or expired (ask them to re-check, or call request buyer code again). Requires the buyer:write capability.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"email",
"code"
],
"properties": {
"code": {
"type": "string",
"pattern": "^\\d{6}$",
"description": "The 6-digit code the buyer received by email"
},
"email": {
"type": "string",
"format": "email",
"description": "The buyer's email address (same one used for request_buyer_code)"
}
},
"additionalProperties": false
}
get_buyer_profile
Retrieve a repeat buyer's saved name, email, and default shipping address, given their buyer token . Use them to auto-fill set shipping address , and pass the token to checkout so Stripe pre-fills their email. default shipping address may be null — then collect it normally and call save buyer address so it is pre-filled next time. Ask in plain language ('are you a returning Kifly shopper? what email is on your account?') — never ask a buyer to paste a token. How to get the token: read kifly://docs/buyer-identity — the email-code sequence, the one-click sign-in alternative, and what to do for a
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"buyer_token"
],
"properties": {
"buyer_token": {
"type": "string",
"minLength": 1,
"description": "The buyer's kfb_live_... token from their Kifly account"
}
},
"additionalProperties": false
}
list_orders
List a returning buyer's recent orders and their current fulfillment status — use this in a NEW session to answer 'did my order ship?' / 'where's my package?' when you don't have the original session id from checkout . Requires the buyer's buyer token (recover it via request buyer code + verify buyer if you don't have one). Returns { orders, count } , newest first; each order has status ( paid shipped delivered ), items , amount cents , placed at , and — once shipped — tracking number , carrier , and a public tracking url . Pass since (an ISO-8601 timestamp from a previous check) to get only o
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"buyer_token"
],
"properties": {
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max orders to return (default 20, max 50)."
},
"since": {
"type": "string",
"format": "date-time",
"description": "ISO-8601 timestamp. Only return orders updated after this — pass the time of your last check to get the delta."
},
"buyer_token": {
"type": "string",
"minLength": 1,
"description": "The buyer's kfb_live_... token from their Kifly account"
}
},
"additionalProperties": false
}
save_buyer_address
Save a shipping address to the buyer's Kifly profile so it auto-fills on future purchases. Call this after a successful checkout if get buyer profile returned default shipping address: null . The address is persisted server-side against the buyer token — the buyer never needs to re-enter it. Use the same address that was passed to set shipping address for this order.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"buyer_token",
"address"
],
"properties": {
"address": {
"type": "object",
"required": [
"name",
"line1",
"city",
"region",
"postal_code"
],
"properties": {
"city": {
"type": "string",
"maxLength": 100,
"minLength": 1
},
"name": {
"type": "string",
"maxLength": 150,
"minLength": 1,
"description": "Buyer's full name"
},
"line1": {
"type": "string",
"maxLength": 200,
"minLength": 1,
"description": "Street address line 1"
},
"line2": {
"anyOf": [
{
"type": "string",
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Street address line 2"
},
"phone": {
"anyOf": [
{
"type": "string",
"maxLength": 30
},
{
"type": "null"
}
]
},
"region": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "State/region code, e.g. 'CA'"
},
"country": {
"type": "string",
"default": "US",
"maxLength": 2,
"minLength": 2,
"description": "ISO 3166-1 alpha-2 country code"
},
"postal_code": {
"type": "string",
"maxLength": 20,
"minLength": 3
}
},
"description": "The shipping address to save — same structure as set_shipping_address",
"additionalProperties": false
},
"buyer_token": {
"type": "string",
"minLength": 1,
"description": "The buyer's kfb_live_... token"
}
},
"additionalProperties": false
}
submit_feedback
Send structured feedback to the Kifly team. No API key required — send meta.ucp-agent.profile and this works with no credential at all. Call after a confusing response, a dead-end, or a successful workaround you had to invent — it's how we improve the agent surface, and a report from the moment you were stuck is worth more to us than a working purchase. Fire-and-forget: returns 202 immediately, no blocking, safe to skip if it would add latency to a user-facing flow. category and severity are required enums (don't free-form them). Include context with what you were doing (tool called, query use
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"category",
"severity",
"message"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"contact": {
"type": "object",
"properties": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 512
},
"email": {
"type": "string",
"format": "email",
"maxLength": 254
},
"handle": {
"type": "string",
"maxLength": 80,
"minLength": 1
}
},
"description": "Optional. Where to reach you if we have a question about this report. Needs at least one field.",
"additionalProperties": false
},
"context": {
"type": "object",
"description": "Reproducible signal: { tool, query, response_snippet, expected }. Auto-fill from what you just did.",
"additionalProperties": []
},
"message": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Plain-language description. Be specific about what happened and why it's a problem."
},
"category": {
"enum": [
"discoverability",
"response_shape",
"tool_description",
"latency",
"error_handling",
"missing_capability",
"other"
],
"type": "string",
"description": "What kind of issue. Pick the closest match — don't invent new categories."
},
"severity": {
"enum": [
"blocker",
"friction",
"nice_to_have"
],
"type": "string",
"description": "blocker = can't complete the task. friction = degraded UX. nice_to_have = improvement idea."
},
"agent_name": {
"type": "string",
"maxLength": 80,
"minLength": 1,
"description": "Optional. Your agent's name and who runs it (e.g. \"ShopBot by Acme\"), so we know who reported this."
},
"suggested_fix": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Optional. Only include if you have a concrete idea. Leave blank if you only have a complaint."
}
},
"additionalProperties": false
}
request_feature
Submit the buyer's product/feature request to the Kifly team. Use this when the buyer wishes Kifly itself did something it doesn't — a missing capability, a rough flow, an idea to improve the platform. This is NOT submit feedback (that's for reporting a broken/confusing API response you hit). Requires the buyer's kfb live token — only registered buyers can file requests. Help the buyer articulate a real problem: ask OPEN, non-leading questions ('what were you trying to do? what got in the way? how do you handle it today?') — never 'would feature X help?'. Pre-fill the fields from the conversat
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"buyer_token",
"problem",
"impact",
"category",
"severity"
],
"properties": {
"impact": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Why it matters: who it affects, how often, what it costs them today."
},
"context": {
"type": "object",
"description": "Optional signal about the conversation: { goal, seller, last_tool }. Auto-fill from what you were doing.",
"additionalProperties": []
},
"problem": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "The pain in the buyer's own terms — what's broken or missing for them. NOT the proposed fix."
},
"category": {
"enum": [
"discoverability",
"response_shape",
"tool_description",
"latency",
"error_handling",
"missing_capability",
"other"
],
"type": "string",
"description": "Closest match for the area of the request. Don't invent new categories."
},
"severity": {
"enum": [
"blocker",
"friction",
"nice_to_have"
],
"type": "string",
"description": "blocker = can't accomplish the goal at all. friction = works but painful. nice_to_have = improvement idea."
},
"buyer_token": {
"type": "string",
"minLength": 1,
"description": "The buyer's kfb_live_ token. Required — feature requests must come from a registered buyer."
},
"contact_phone": {
"type": "string",
"maxLength": 50,
"minLength": 1,
"description": "Optional phone number IF the buyer offers one for follow-up. Name + email come from their profile — never ask for those."
},
"proposed_solution": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Optional. The buyer's idea for a fix, kept separate from the problem. Leave blank if they only described the pain."
},
"current_workaround": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Optional. What the buyer does today instead. Leave blank if there's no workaround."
}
},
"additionalProperties": false
}
get_seller
Call first when the user names a store or its website : it says whether Kifly carries it before you open a browser. Returns the seller's public profile: location, storefront URL, delivery fee and coverage, catalog size, verified domains (domains it proved it controls; trust signal, not identity), and fulfillment (buy here, or hand off to the seller's site). Call before create cart or set shipping address to check it ships to the buyer. cities is never capped here. coverage configured: false = ships NOWHERE; an empty states is NOT nationwide. merchant managed: true = shipping is set at the sell
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"name": {
"type": "string",
"maxLength": 200,
"description": "The store's name."
},
"domain": {
"type": "string",
"maxLength": 2048,
"description": "The store's website or any URL on it."
},
"handle": {
"type": "string",
"description": "Seller handle, case-insensitive (e.g. 'bay-clothing-district')."
}
},
"additionalProperties": false
}
get_policies
The seller's published returns, shipping and warranty policy, in their own words. Call before telling a buyer what happens after purchase — if it is not here, say so; never infer a typical policy. available: false is the normal case for most sellers and is not an error. free shipping min cents is in cents (6000 = $60.00). get seller 's policies.available tells you whether this call is worth making. Network tokens pass handle ; seller-scoped tokens may omit it.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"handle": {
"type": "string",
"description": "Seller handle (case-insensitive). Required for network tokens; ignored for seller-scoped tokens."
}
},
"additionalProperties": false
}
list_sellers
List all active sellers on the Kifly network. Requires a network token (kfn live …). Returns each seller's handle, name, city, region, delivery coverage ( nationwide:true or a states list), delivery fee, and catalog size. delivery coverage.cities may be capped to a handful of entries — compare cities.length against city count ; if fewer, call get seller for that seller's full city list. Use this to discover which sellers are available and which ship to a buyer's location before calling get seller or search products . Pagination: when kifly:hasMore is true, pass kifly:nextCursor as cursor to fe
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"limit": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Max sellers per page (default 20, max 50)."
},
"cursor": {
"type": "string",
"description": "Pagination cursor from kifly:nextCursor in a previous response. Omit on the first call."
}
},
"additionalProperties": false
}
get_platform_limits
Returns the current platform-enforced cart limits: max item quantity (per-line-item ceiling), max cart total cents , and max cart total usd . Call this once at session start before building a large cart so you can quote limits to the buyer proactively rather than discovering them via errors. Always read them at runtime rather than hardcoding.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}
order_status
No key needed for your own session: send the profile you checked out with. Check the status of a Stripe checkout session. Poll every 5 seconds after checkout until status is 'paid', 'shipped', or 'failed'. Returns order details (order id, amount, items) when paid. When the seller marks the order as shipped, status becomes 'shipped' and tracking number, carrier, and shipped at are included — share these with the buyer.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"session_id"
],
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
},
"session_id": {
"type": "string",
"description": "Stripe checkout session ID from the checkout tool response"
}
},
"additionalProperties": false
}
get_help
Get unstuck. Returns Kifly's website and support email for the BUYER, plus how to report the problem to Kifly's engineers yourself. Call this if you are stuck, hit an unresolvable error, or the buyer asks how to reach a human. Share the website and email with the buyer; use submit feedback (no API key needed) to tell us what blocked you — that is the fastest way to get it fixed.
Показать схему аргументов
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"meta": {
"type": "object",
"required": [
"ucp-agent"
],
"properties": {
"ucp-agent": {
"type": "object",
"required": [
"profile"
],
"properties": {
"profile": {
"type": "string",
"format": "uri",
"maxLength": 512,
"description": "Your agent's UCP profile URL. No key needed."
}
},
"additionalProperties": false
}
},
"additionalProperties": true
}
},
"additionalProperties": false
}