Reference for AI agents
Clarypull for AI agents
Operational reference for an AI agent that searches Clarypull's free catalog beta for a person: how to search the catalog exactly and completely, every tool it serves with its arguments and results, and what this deployment does not offer. It sells nothing: there is no quote, order, payment or offer.
Identifiers, times, amounts and counts in the examples are illustrative.
Read this first
This deployment is a free catalog beta. Sellers publish their own catalogs for free, and you search and read them. Nothing can be bought here: there is no quote, order, checkout, payment, payout or paid plan, and no market check or offer. A listed price is the seller's published term, never an offer or a quote.
- What you can do
- Search the catalog exactly, read a product and every seller's published listing of it, browse the categories and find products by their words, read a seller's disclosure, and report suspicious activity. These are the seven tools below, each also a REST operation.
- What you cannot do
- Obtain a quote, prepare or pay for a purchase, read an order, create a market check, ask sellers for offers or select one. None of these tools is advertised, and a REST request for any of them is answered
403 PURCHASING_NOT_AVAILABLE: a final answer, not a retry. Nothing was created or charged. - How to tell
tools/listreturns only the seven tools below, and the server's instructions andclarypull_shopping_guidesay this is a free catalog beta. Every REST answer of a catalog operation carriesClarypull-Service-Mode: FREE_CATALOG_BETAandClarypull-Purchasing: unavailable, and an MCP result carries the same statement in its text beside the document, which is not altered.- A result's `market_check_scope`
- A search result still carries it, because the result document is the contract's, but there is no market check to create here. Do not use it.
- Never claim a purchase
- Tell the person plainly that this service lists products and that buying is not available in this beta. Do not say you can reserve, hold, buy or pay.
Connect and discover
- Transport: MCP over Streamable HTTP at the deployment's connection address. The person copies it from Connect an agent and adds it to their agent app.
- Authorization: OAuth 2.0 with the person's own Clarypull account. The protected resource metadata (RFC 9728) is served without authentication at the well-known location derived from the address, and every
401names it inWWW-Authenticate. - Only agent apps that Clarypull has enabled can connect. Your token acts for one person.
- Decide what you can do from the tool names
tools/listreturns and from each tool's input schema. Each result document states its ownschema_version.
{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}Search and explore the catalog
- Read
clarypull_describe_catalogfor the category: whichattr.<key>fields exist, their units, and how many products state each (product_coverage). - Turn each of the person's real requirements into a
whereclause with its unit. Keep preferences out ofwhere. - Search in the exact mode. Read
membership,facets,near_missesandclause_impactbefore suggesting the person relax anything, and never relax a requirement silently. - Follow
next_cursoruntil it isnullwhenever you count, enumerate or claim completeness. - Read
clarypull_get_catalog_productfor the stated facts and every listing of the products the person cares about; it lists all of them, matching or not (see Paging and completeness).
{
"name": "clarypull_describe_catalog",
"arguments": {
"country": "US",
"categories": [
"amazon.dishwasher"
],
"limit": 50
}
}{
"field": "attr.width",
"type_source": "OBSERVED_VALUES",
"types": [
{
"type": "quantity",
"dimension": "length",
"listings": 37
}
],
"operators": [
"eq",
"ne",
"lt",
"lte",
"gt",
"gte",
"between",
"exists",
"missing"
],
"products_with_value": 31,
"listings_with_value": 37,
"product_coverage": 0.62,
"canonical_unit": "mm",
"stated_units": [
"cm",
"in",
"inches"
],
"minimum": "596",
"maximum": "610",
"top_values": [
{
"value": "609.6",
"products": 12
},
{
"value": "606",
"products": 7
}
],
"distinct_values": 9,
"top_values_truncated": true
}A field with product_coverage 0.62 is stated for 62 % of the products in scope. A clause on it excludes the rest as unknown unless you admit unknowns, so tell the person when coverage is low.
Exact search
A product is a member when one of its listings satisfies every where clause and the text matches. All clauses of a where hold on the same listing. Membership is exhaustive and exact; ranking (CATALOG_RANKING_V1) orders members and decides none of them.
{
"name": "clarypull_search_catalog",
"arguments": {
"text": "built-in dishwasher",
"categories": [
"amazon.dishwasher"
],
"ship_to": {
"country": "US",
"postal_code": "94110"
},
"where": {
"all": [
{
"field": "attr.width",
"op": "between",
"values": [
23.5,
24.25
],
"unit": "in"
},
{
"field": "attr.noise_level",
"op": "lte",
"value": 46,
"unit": "dB"
},
{
"field": "price",
"op": "lte",
"value": {
"amount_minor": 90000,
"currency": "USD"
}
},
{
"not": {
"field": "title",
"op": "contains_words",
"value": "refurbished"
}
}
]
},
"facets": [
{
"field": "attr.finish"
},
{
"field": "attr.width",
"unit": "in",
"edges": [
20,
24,
30
]
}
],
"include_near_misses": true,
"explain": "full",
"page": {
"size": 25
}
}
}{
"schema_version": "1.0.0",
"capability": "CATALOG_SEARCH",
"notice": "Catalog search reads the published catalog only: each listing's terms are what its seller published, as observed at observed_at, and each product fact is what that listing's seller stated. Nothing here is an offer, no seller was contacted, and nothing was reserved or bought. Read a product's every visible listing and stated fact with getCatalogProduct, and a field's coverage with describeCatalog; searching and reading never need a market check. market_check_scope only names how a result could scope an optional market check later; when it is null the product has no GTIN or ASIN, and none is to be invented.",
"as_of": "2026-10-26T15:04:05.000Z",
"ranking_policy": "CATALOG_RANKING_V1",
"ship_to": {
"country": "US",
"postal_code": "94110"
},
"membership": {
"mode": "EXHAUSTIVE_FILTERED",
"exhaustive": true,
"total_products": 1,
"total_listings": 1,
"rule": "Every product with at least one visible listing on which every hard constraint holds and the text matches, as of as_of; every member is reachable by following next_cursor, and ranking orders members without deciding any. An UNKNOWN value never satisfies a constraint."
},
"text_interpretation": {
"mode": "WORDS",
"applied_text": "built-in dishwasher",
"text_mode": "all_terms",
"not_applied": [],
"warnings": []
},
"results": [
{
"product_id": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a64",
"category": "amazon.dishwasher",
"product_type": "DISHWASHER",
"title": "Example 24 in built-in dishwasher, stainless steel",
"brand": "Example Brand",
"model": "EX-24B",
"identifiers": {
"gtins": [
"00012345678905"
],
"asins": [],
"mpns": [
"EX-24B"
]
},
"score": 1.5,
"matched_by": "WORDS",
"qualifying_listings": 1,
"listings_shown": 1,
"listings": [
{
"listing_id": "c41e7b20-9d3a-4b5c-8f61-2e0a7d9b3c15",
"seller_id": "5e8a1f3c-7b2d-4c90-a6e4-9f0b3d2c1a78",
"seller_name": "Example Appliance Store",
"content_origin": "SELLER_FEED",
"published_price": {
"item": {
"amount_minor": 84900,
"currency": "USD"
},
"total_before_tax": {
"amount_minor": 89900,
"currency": "USD"
},
"basis": "ITEM_AND_EVERY_MANDATORY_CHARGE_KNOWN_TAX_STATED_SEPARATELY",
"tax": "KNOWN"
},
"availability": {
"value": "AVAILABLE",
"authoritative": false,
"observed_at": "2026-10-26T14:30:00.000Z"
},
"delivery_window": {
"earliest": "2026-10-29",
"latest": "2026-11-03"
},
"deliverable_to_postal_code": "SATISFIED",
"observed_at": "2026-10-26T14:30:00.000Z",
"clauses": [
{
"path": "/where/all/0",
"field": "attr.width",
"op": "between",
"negated": false,
"status": "SATISFIED",
"admitted_unknown": false,
"values": [
{
"kind": "QUANTITY",
"stated": "{\"unit\": \"inches\", \"value\": 23.875}",
"stated_unit": "inches",
"canonical": "606.425",
"canonical_unit": "mm",
"derived_by_unit_conversion": true,
"source": "SELLER_FEED"
}
]
},
{
"path": "/where/all/1",
"field": "attr.noise_level",
"op": "lte",
"negated": false,
"status": "SATISFIED",
"admitted_unknown": false,
"values": [
{
"kind": "QUANTITY",
"stated": "{\"unit\": \"dB\", \"value\": 44}",
"stated_unit": "dB",
"canonical": "44",
"canonical_unit": "dB",
"source": "SELLER_FEED"
}
]
},
{
"path": "/where/all/2",
"field": "price",
"op": "lte",
"negated": false,
"status": "SATISFIED",
"admitted_unknown": false,
"values": [
{
"kind": "MONEY",
"stated": "84900",
"canonical": "84900",
"canonical_unit": "USD"
}
]
},
{
"path": "/where/all/3/not",
"field": "title",
"op": "contains_words",
"negated": true,
"status": "SATISFIED",
"admitted_unknown": false,
"values": [
{
"kind": "TEXT",
"stated": "Example 24 in built-in dishwasher, stainless steel",
"canonical": "Example 24 in built-in dishwasher, stainless steel"
}
]
}
]
}
],
"market_check_scope": {
"category": "amazon.dishwasher",
"hard_constraint": {
"field": "gtin",
"operator": "eq",
"value": "00012345678905"
},
"note": "Optional, and never needed to search or read the catalog: a market check scoped by this category and hard constraint would ask every eligible seller of this exact product for personalized offers. Catalog search did not create one."
}
}
],
"facets": [
{
"field": "attr.finish",
"type": "text",
"excluded_clauses": [],
"products_in_scope": 1,
"products_with_value": 1,
"products_unknown": 0,
"values": [
{
"value": "stainless steel",
"products": 1
}
],
"distinct_values": 1,
"complete": true
},
{
"field": "attr.width",
"type": "quantity",
"excluded_clauses": [
"/where/all/0"
],
"products_in_scope": 2,
"products_with_value": 1,
"products_unknown": 1,
"complete": true,
"canonical_unit": "mm",
"minimum": "606.425",
"maximum": "606.425",
"buckets": [
{
"to": "20",
"products": 0
},
{
"from": "20",
"to": "24",
"products": 1
},
{
"from": "24",
"to": "30",
"products": 0
},
{
"from": "30",
"products": 0
}
]
}
],
"near_misses": [
{
"product_id": "0d5e7f91-3a2b-4c6d-9e8f-7a1b2c3d4e5f",
"title": "Example 24 in built-in dishwasher, black",
"brand": "Example Brand",
"listing_id": "6b8d0f2a-4c6e-4a1b-8d3f-5e7a9c1b3d26",
"seller_id": "5e8a1f3c-7b2d-4c90-a6e4-9f0b3d2c1a78",
"failed": {
"path": "/where/all/1",
"field": "attr.noise_level",
"op": "lte",
"negated": false,
"status": "VIOLATED",
"admitted_unknown": false
}
}
],
"clause_impact": [
{
"path": "/where/all/0",
"additional_products_without_it": 1
},
{
"path": "/where/all/1",
"additional_products_without_it": 1
},
{
"path": "/where/all/2",
"additional_products_without_it": 0
},
{
"path": "/where/all/3",
"additional_products_without_it": 1
}
],
"suggested_filters": [],
"withdrawn_since_snapshot": 0,
"withdrawn_products_since_snapshot": 0,
"next_cursor": null
}clause_impactsays how many more products each top-level clause excludes: here, dropping the width, the noise or the exclusion clause would each add one product.- The near miss is kept out by its noise level alone (
VIOLATED). The width facet sets its own clause aside (excluded_clauses), so it counts the alternatives to the person's choice too. explain: fullshows the stated value behind each clause: 23.875 inches, compared as 606.425 mm.summary(the default) shows statuses only, andnoneomits them.- Use
product_idexactly as returned when you read a product again. There is no market check or purchase to continue to here.
Constraints, units and unknown values
- Three values
- Each clause is
SATISFIED,VIOLATEDorUNKNOWNon a listing. A value nobody stated isUNKNOWN, andUNKNOWNnever satisfies a clause. - Admitting unknowns
if_unknown: include(per clause or for the request) admits a listing whose value is unknown, labelledUNKNOWNwithadmitted_unknown: true. Use it only after the person accepts unconfirmed fit, and say which results are unconfirmed.- Negation
- Write exclusions as
notclauses or withne,not_inandmissing. AnotoverUNKNOWNstaysUNKNOWN. An exclusion written into the text ("-refurbished", "without wifi") is reported intext_interpretation.not_appliedand not applied. - Units
- State the unit of every quantity. Values compare exactly across units in their dimension's canonical unit. Spellings are case-sensitive:
MBis megabytes andMbis not a unit;dBAis its own dimension, notdB. The accepted spellings are inclarypull_describe_catalog'sunits. - Several stated values
- A value a seller stated several times (compatible devices, features) matches on any of them.
- Sources
- Each stated value names its source:
SELLER_FEED,AMAZON_LISTING,AMAZON_CATALOG(Amazon's shared catalog, which may merge other contributors' data),SELLER_COMPLETION,DEVELOPMENT_FIXTUREorUNKNOWN. Clarypull never states an inferred value as a fact. - Money
- A price clause takes money:
{"amount_minor": 90000, "currency": "USD"}is $900.00. Sorting bypricecompares one currency: statecurrencywhen the deployment asks for it. - Published price
itemis the item price.total_before_taxis present only when every mandatory charge is known (basis), andtaxsays separately whether tax is known. These are published terms withobserved_at, not offers or quotes.- Availability
AVAILABLE,UNAVAILABLEorUNKNOWN, withobserved_atand whether the observation is authoritative. Unknown availability is not availability.
{
"name": "clarypull_search_catalog",
"arguments": {
"categories": [
"amazon.dishwasher"
],
"ship_to": {
"country": "US",
"postal_code": "94110"
},
"where": {
"all": [
{
"field": "attr.width",
"op": "between",
"values": [
23.5,
24.25
],
"unit": "in",
"if_unknown": "include"
},
{
"field": "attr.noise_level",
"op": "lte",
"value": 46,
"unit": "dB"
}
]
},
"sort": [
{
"by": "price",
"direction": "asc"
}
],
"currency": "USD"
}
}Identifiers, models and variants
A text that is exactly a GTIN, UPC-A, EAN-13 or GTIN-8 with a correct check digit, or an ASIN, matches exactly that product (an ASIN only in the destination's marketplace). One token of letters and digits also matches a model or MPN with or without punctuation. A wrong check digit is searched as words, with a warning.
{
"name": "clarypull_search_catalog",
"arguments": {
"text": "00012345678905",
"ship_to": {
"country": "US",
"postal_code": "94110"
}
}
}variant_family names a product's variation family. Its siblings (other sizes, colors or capacities) are other products with their own product_id; filter on the family to list them.
{
"name": "clarypull_search_catalog",
"arguments": {
"ship_to": {
"country": "US",
"postal_code": "94110"
},
"where": {
"field": "variant_family",
"op": "eq",
"value": "ASIN:ATVPDKIKX0DER:B0EXAMPL00"
}
}
}Paging and completeness
- An exact page states
total_productsandtotal_listingsfor the whole traversal. Repeat the identical request withpage.cursorset tonext_cursoruntilnext_cursorisnull; every member then appears exactly once. - Every later page reads the snapshot of the first page, so concurrent publications neither add nor duplicate members. A seller suspended or disconnected meanwhile is removed, and
withdrawn_since_snapshotandwithdrawn_products_since_snapshotcount what left. - A cursor is bound to the person, the tenant and the request apart from
page, and lasts fifteen minutes from the first page. Change anything else and you must start again.CURSOR_EXPIREDorCURSOR_INVALIDmeans start again from the first page. - A search result shows up to ten of a product's listings that satisfy the search; its
qualifying_listingscounts all that do, and no search cursor reaches the rest. clarypull_get_catalog_productdoes not continue a search. It applies no text orwhere, lists every listing of the product visible for the destination in price order, and reads its own snapshot, with its ownas_of, count and cursor. A listing it returns may break the person's requirements, so check each one against them, with the same unknown-value policy, using the stated values it shows; present only those that pass as matches, and never as the search's total.- Directory pages continue with
next_afteruntil it is empty.
{
"name": "clarypull_search_catalog",
"arguments": {
"text": "built-in dishwasher",
"categories": [
"amazon.dishwasher"
],
"ship_to": {
"country": "US",
"postal_code": "94110"
},
"where": {
"all": [
{
"field": "attr.width",
"op": "between",
"values": [
23.5,
24.25
],
"unit": "in"
},
{
"field": "attr.noise_level",
"op": "lte",
"value": 46,
"unit": "dB"
},
{
"field": "price",
"op": "lte",
"value": {
"amount_minor": 90000,
"currency": "USD"
}
},
{
"not": {
"field": "title",
"op": "contains_words",
"value": "refurbished"
}
}
]
},
"facets": [
{
"field": "attr.finish"
},
{
"field": "attr.width",
"unit": "in",
"edges": [
20,
24,
30
]
}
],
"include_near_misses": true,
"explain": "full",
"page": {
"size": 25,
"cursor": "c2VhcmNoLWN1cnNvci1leGFtcGxl"
}
}
}{
"name": "clarypull_get_catalog_product",
"arguments": {
"product_id": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a64",
"country": "US",
"postal_code": "94110",
"page_size": 50
}
}Exploration by meaning
When the person describes a need in words a listing may not use, add retrieval: {"mode": "hybrid"} (words and meaning) or "semantic" (meaning). The answer is one page of at most candidates products per lane, ranked by meaning, each still satisfying every hard constraint.
{
"name": "clarypull_search_catalog",
"arguments": {
"text": "quiet dishwasher for a small apartment kitchen",
"ship_to": {
"country": "US",
"postal_code": "94110"
},
"where": {
"field": "attr.width",
"op": "lte",
"value": 24,
"unit": "in"
},
"retrieval": {
"mode": "hybrid",
"candidates": 50
}
}
}{
"mode": "RANKED_CANDIDATES",
"exhaustive": false,
"total_products": 12,
"total_listings": 15,
"rule": "Not every member: at most candidate_budget_per_lane products from each of two lanes, the products whose text matches in any-terms mode and the products whose documents are nearest the text's meaning, each with at least one visible listing on which every hard constraint holds, ranked by meaning in one page with no next page. An UNKNOWN value never satisfies a constraint. Search without retrieval to enumerate every member.",
"ranked": {
"mode": "hybrid",
"model": "google/embeddinggemma-2@58faf90940886df2d62be555c8765d00dac362c5:bf16:768",
"candidate_budget_per_lane": 50,
"lexical_lane_products": 4,
"dense_lane_products": 10,
"dense_documents_examined": 40,
"dense_listing_rows": 44,
"dense_termination": "SCAN_STOPPED_EARLY_COVERAGE_UNKNOWN",
"candidates_without_embedding": 0
}
}- A ranked answer is not every member:
membership.exhaustiveis false andnext_cursoris alwaysnull. Never call it the complete set or count from it. - A ranked request refuses
page.cursor,facets,include_near_misses,preferand any order but relevance. Use the exact mode to enumerate, count, facet or sort. dense_termination: SCAN_STOPPED_EARLY_COVERAGE_UNKNOWNmeans the index stopped at its own limits. It does not mean nothing else is near.- A text that is an identifier or a model number is answered by the exact mode whatever mode you ask for, and is answered even without an embedding model.
The catalog directory
The directory is the simple lookup every deployment with manifest 1.2.0 or later serves: categories with counts, and one category's products by words in the title, brand or model, with identifiers. It carries no price, stock or offer. Where catalog search is listed, use search for anything more than an identity lookup.
{
"name": "clarypull_list_catalog_categories",
"arguments": {}
}{
"name": "clarypull_find_catalog_products",
"arguments": {
"category": "amazon.dishwasher",
"q": "EX-24B"
}
}Authorization and boundaries
- The server enforces authentication, scopes, ownership and constraint validation. A denial is final for that call; never try to bypass it.
- You may search and read. A search is not an offer, and nothing here is a purchase.
- Search results cover the sellers who have published here, not every product on the market. An empty result means nothing suitable was found here, not that nothing exists.
- A listing keeps its
listing_idwhen its seller updates it, and gains a version. A product is merged only on an exact GTIN, marketplace ASIN, or brand, MPN and variant together; a seller's own item that states none of them is never merged with another publication of itself, so if its seller publishes again itsproduct_idchanges. A read of the oldproduct_idis then answeredCATALOG_PRODUCT_NOT_FOUND: search again for the currentproduct_idrather than holding or guessing one. - A deployment that is not live says so on its website. Its stores are test stores; never present its prices or stock as real.
Calling the REST API
Every tool is also a REST operation that answers the same document under the same scopes. Use it when your runtime makes HTTPS requests rather than MCP tool calls. A REST request is not a tool call: never send a JSON-RPC envelope, or a {"name", "arguments"} object, to a REST path.
- Origin: send requests to the API origin the deployment publishes for its REST API. This reference names none.
- Authentication:
Authorization: Bearer <access token>, with a token the deployment's authorization server issued for that API and the operation's scopes. - Responses: the same documents a tool returns as
structuredContent. A refusal isapplication/problem+jsonwith the same members, and aRetry-Afterheader carries any retry interval.
| Tool | Request | Arguments over REST |
|---|---|---|
clarypull_describe_catalog | GET /v1/catalog/fields | country → query country; categories → query categories (one value, comma-separated); limit → query limit; after → query after |
clarypull_search_catalog | POST /v1/catalog/search | every argument → a JSON body member of the same name |
clarypull_get_catalog_product | GET /v1/catalog/products/{product_id} | product_id → path {product_id}; country → query country; postal_code → query postal_code; page_size → query page_size; cursor → query cursor |
clarypull_list_catalog_categories | GET /v1/catalog/categories | after → query after |
clarypull_find_catalog_products | GET /v1/catalog/products | category → query category; q → query q; after → query after |
clarypull_get_seller_disclosure | GET /v1/sellers/{seller_id}/disclosure | seller_id → path {seller_id} |
clarypull_report_marketplace_activity | POST /v1/marketplace-reports | idempotency_key → header Idempotency-Key; request → the whole JSON body |
POST /v1/catalog/search HTTP/1.1
Host: <API host>
Authorization: Bearer <access token>
Accept: application/json
Content-Type: application/json
{
"text": "built-in dishwasher",
"categories": [
"amazon.dishwasher"
],
"ship_to": {
"country": "US",
"postal_code": "94110"
},
"where": {
"all": [
{
"field": "attr.width",
"op": "between",
"values": [
23.5,
24.25
],
"unit": "in"
},
{
"not": {
"field": "title",
"op": "contains_words",
"value": "refurbished"
}
}
]
},
"page": {
"size": 25
}
}GET /v1/catalog/fields?country=US&categories=amazon.dishwasher,amazon.refrigerator&limit=50 HTTP/1.1
Host: <API host>
Authorization: Bearer <access token>
Accept: application/jsonTool reference
clarypull_describe_catalog
Every searchable field: the core fields with their types, operators and level, and the attributes sellers state, with observed types, units, coverage, range and top values; and the units each dimension accepts.
- Effect
- Read only; repeat freely
- Scopes
market_checks:create- REST
GET /v1/catalog/fields(describeCatalog)- Served from
- manifest 1.3.0 and later
| Argument | Required | Meaning |
|---|---|---|
country | yes | Destination country (ISO 3166-1 alpha-2, for example US). |
categories | no | Up to 20 served categories to describe; all visible categories when absent. |
limit | no | Attribute fields per page, 1 to 200. |
after | no | The next_after of the previous page. |
Returns
core_fields: Fixed fields with type, level (productorlisting), operators and whether a listing may leave them unknown.attribute_fields: Eachattr.<key>withproduct_coverage,stated_units,canonical_unit, range and top values.units: Each dimension's canonical unit and every accepted spelling.next_after: Field key to continue after;nullon the last page.
- Contacts no seller. Read it before constraining a field you have not seen in this deployment.
clarypull_search_catalog
Search every published listing visible to the person, under exact hard constraints, and return every member ranked and explained; or, with retrieval, one bounded page of candidates found by meaning.
- Effect
- Read only; repeat freely
- Scopes
market_checks:create- REST
POST /v1/catalog/search(searchCatalog)- Served from
- manifest 1.3.0 and later
| Argument | Required | Meaning |
|---|---|---|
ship_to | yes | {country, postal_code?}. The country decides which sellers and marketplaces apply; a postal code excludes sellers whose coverage does not reach it. |
text | no | Up to 256 characters. A whole GTIN, UPC, EAN or ASIN matches that product exactly; one token of letters and digits also matches a model or MPN. |
text_mode | no | all_terms (default), any_terms or phrase. |
categories | no | Up to 20 served categories. |
where | no | Hard constraints: a clause, or all / any / not over clauses, four levels and 64 nodes at most. |
if_unknown | no | exclude (default) or include, for every clause that does not set its own. |
prefer | no | Up to 8 clauses that only add to the rank of the exact mode. Never a filter. |
sort | no | Up to 3 keys: relevance, price, delivery_latest, title or an attr.<key>, each asc or desc. |
currency | no | The currency price sorting compares in, when the deployment has no single launch currency. |
facets | no | Up to 16 fields to count values or numeric buckets for (unit, edges, limit, after). |
page | no | {size, cursor}: 1 to 100 products per page, and the previous page's next_cursor. |
explain | no | none, summary (default: each clause's status per listing) or full (also the stated values compared). |
include_near_misses | no | Up to 10 products kept out by exactly one clause, with the clause that failed. |
retrieval | no | {mode, candidates?}: exact (default), hybrid or semantic, with up to 100 candidates per lane. |
Returns
membership:EXHAUSTIVE_FILTEREDwith exacttotal_productsandtotal_listings, orRANKED_CANDIDATESwith what was examined.results: Products with identifiers, the qualifying listings' published terms, clause statuses andmarket_check_scope.text_interpretation: How the text was read: identifier, model or words, and any exclusion it did not apply.facets: Value counts or buckets, unknown counts, and the clauses each facet set aside.near_misses: What one clause keeps out.clause_impact: How many more products each top-level clause excludes.suggested_filters: Words of the text that equal a field value, or a near spelling of one.next_cursor: Cursor of the next page;nullwhen there is none.
- Takes no idempotency key: it changes nothing and contacts no seller.
- Prices in results are published terms with their observation time, never offers.
clarypull_get_catalog_product
Every listing of one product visible for the destination, a page at a time in price order, with each seller's published terms and every attribute each seller states, exactly as stated with its unit and the canonical value it is compared as. It applies no search constraint.
- Effect
- Read only; repeat freely
- Scopes
market_checks:create- REST
GET /v1/catalog/products/{product_id}(getCatalogProduct)- Served from
- manifest 1.3.0 and later
| Argument | Required | Meaning |
|---|---|---|
product_id | yes | A product_id from search or the directory. |
country | yes | Destination country. |
postal_code | no | US ZIP code; limits listings to sellers whose coverage reaches it. |
page_size | no | Listings per page, 1 to 50 (default 20). |
cursor | no | The previous page's next_cursor. |
Returns
product: The product withqualifying_listings(here every visible listing of it, not a search's matches),listings_shownand the listings of this page.next_cursor: Cursor of the next page of listings;nullon the last.
- A separate read with its own snapshot,
as_ofand cursor, not a continuation of a search. Re-check each listing against the person's hard constraints and unknown-value policy before calling it a match. - Statements that differ between sellers are shown side by side; none is chosen or merged.
clarypull_list_catalog_categories
The served categories that hold a product the person can reach, with product and seller counts, in category order.
- Effect
- Read only; repeat freely
- Scopes
market_checks:create- REST
GET /v1/catalog/categories(listCatalogCategories)- Served from
- manifest 1.2.0 and later
| Argument | Required | Meaning |
|---|---|---|
after | no | The previous page's next_after. |
Returns
categories: Each withcategory,product_type,scope_category,productsandsellers.next_after: Category to continue after; empty on the last page.
- Identity only: no price, stock, offer or ranking.
clarypull_find_catalog_products
A simple lookup of one served category's products whose title, brand or model contain the words, fifty a page by title, each with the identifiers a market check is scoped by.
- Effect
- Read only; repeat freely
- Scopes
market_checks:create- REST
GET /v1/catalog/products(findCatalogProducts)- Served from
- manifest 1.2.0 and later
| Argument | Required | Meaning |
|---|---|---|
category | yes | A served category, as clarypull_list_catalog_categories names it. |
q | no | Up to 128 characters; empty lists every product of the category. |
after | no | The previous page's next_after. |
Returns
products: Each withproduct_id,scope_category, title, brand, model,asinsandgtins.next_after: Cursor to continue after; empty on the last page.
- Identity only. Where
clarypull_search_catalogis listed, use it for constraints, units, ranking and facets.
clarypull_get_seller_disclosure
What the INFORM Consumers Act requires disclosed of a seller, by the seller_id a listing, search result or purchase carries: whether it is a high-volume seller, whether identity disclosure is required of it, the verification standing of what is shown, its identity where required, and how to report suspicious activity.
- Effect
- Read only; repeat freely
- Scopes
market_checks:create- REST
GET /v1/sellers/{seller_id}/disclosure(getSellerDisclosure)- Served from
- manifest 1.7.0 and later
| Argument | Required | Meaning |
|---|---|---|
seller_id | yes | The seller, from seller_id on a listing, a search result or a purchase. |
Returns
high_volume: Whether the seller is a high-volume seller under the statute's thresholds.disclosure_required: Whether the seller's identity must be shown to the person; showidentitywhenever it is true.verification:VERIFIED,PENDING,REJECTEDorNONE: the standing of the identity shown.identity: The seller's legal name and entity type, its address as its certification allows (in full, a returns address, or country and state with a statement that no business address is available), its phone or the statement that none is available, and its email;nullwhen not required or not provided.reporting: The marketplace's email address and telephone number for reporting suspicious activity, besideclarypull_report_marketplace_activity;nulluntil the operator registers them.
- Read it before the person buys from a seller and show the identity and reporting members when they are present; they are not terms of the purchase.
- Never state how the seller's bank, tax or identity elements are held: the document does not say, and neither do you.
clarypull_report_marketplace_activity
Report suspicious marketplace activity to Clarypull's operator when the person asks to: a suspected counterfeit, fraud, an unsafe or recalled product, stolen goods, a misrepresented seller identity, or anything else, with the seller, product, listing or purchase it concerns where known.
- Effect
- Creates a resource; takes an idempotency key
- Scopes
market_checks:create- REST
POST /v1/marketplace-reports(reportMarketplaceActivity)- Served from
- manifest 1.7.0 and later
| Argument | Required | Meaning |
|---|---|---|
idempotency_key | yes | Unique per report; a retry with the same key and request answers the same receipt. |
request | yes | {schema_version: "1.0.0", category, seller_id?, product_id?, listing_id?, purchase_id?, description}; description is the person's own words, up to 2000 characters. |
Returns
report_id: The report, for the person's records.replayed:truewhen the same key answered an earlier report.reporting: The marketplace's email address and telephone number, for reporting by other means;nulluntil registered.
- A report changes no order, refund or listing on its own; the operator reviews it. Never promise an outcome.
- Send only what the person said about the activity; never a transcript, and never their own contact details, which the credential already identifies.
