--- name: api.purch.xyz description: api.purch.xyz provides two search-oriented skills: one for discovering purchasable AI assets (skills, knowledge bases, personas) within the Purch Vault, and one for finding physical or digital consumer products via a natural-language AI shopping assistant sourcing results from Amazon and Shopify. Neither skill executes transactions or retrieves full item content. host: api.purch.xyz --- # api.purch.xyz Purch is a discovery and browsing platform serving two distinct use cases: agents looking to find and evaluate AI tools available for purchase in the Purch Vault, and agents or users seeking consumer product recommendations via conversational queries. It covers both AI-asset marketplaces and general e-commerce product search under one host, but is strictly a search and recommendation layer with no transactional or fulfillment capabilities. ## When to use this host Use api.purch.xyz when an agent needs to discover AI tools available for purchase in the Purch Vault (use search-purch-vault), or when a user wants product recommendations from Amazon or Shopify via a plain-language query (use search-products-with-ai-shopping-assistant). Do not use this host for completing purchases, checking inventory, tracking orders, or retrieving the full content of a specific vault item — those operations require a separate transactional endpoint not available here. For real-time pricing or token data, look elsewhere. The two skills on this host serve entirely separate domains and should not be confused: one is for AI-asset marketplace search, the other for consumer e-commerce search. ## Capabilities ### AI Asset Discovery Enables structured browsing and filtering of the Purch Vault to locate purchasable AI skills, knowledge bases, and personas by keyword, category, product type, and price range with cursor-based pagination. - **`search-purch-vault`** — Search the Purch Vault for purchasable AI skills, knowledge bases, and personas, with filtering by category, product type, and price range, returning cursor-paginated results with metadata. ### Consumer Product Search Accepts natural-language shopping queries and returns AI-generated replies alongside ranked product listings with prices, ratings, and purchase links from Amazon and Shopify. - **`search-products-with-ai-shopping-assistant`** — Accepts a natural language shopping query and returns an AI-generated reply plus a ranked list of matching products with prices, ratings, and purchase links sourced from Amazon and Shopify. ## Skill reference ### `search-purch-vault` **Purch Vault Search** — Search the Purch Vault for purchasable AI skills, knowledge bases, and personas, with filtering by category, product type, and price range, returning cursor-paginated results with metadata. *Use when:* Use when an agent needs to discover or browse available items in the Purch Vault, such as finding skills by keyword, filtering by category or product type, or paginating through listings to identify purchasable AI tools. *Not for:* Do not use to retrieve the full content or payload of a specific vault item; use a dedicated item-fetch or purchase endpoint instead. Not suitable for real-time price feeds or token data. **Inputs:** - `q` (string) — Free-text search query to match against vault item titles and descriptions. - `category` (string) — Filter results to a specific category. Allowed values: marketing, development, automation, career, ios, productivity. - `productType` (string) — Filter by product type. Allowed values: skill, knowledge, persona. - `minPrice` (integer) — Minimum price filter in USDC whole units (inclusive, minimum 0). - `maxPrice` (integer) — Maximum price filter in USDC whole units (inclusive, minimum 0). - `cursor` (string) — Pagination cursor — UUID of the last item from the previous page. - `limit` (integer) — Number of items to return per page. Range: 1–100. Defaults to 30. **Returns:** Returns a boostedItems array (promoted listings) and an items array of matching vault entries, each with id, slug, title, cardDescription, price, category, coverImageUrl, creator object, createdAt timestamp, downloads count, and featured flag. **Example:** `GET https://api.purch.xyz/x402/vault/search?q=automation&category=automation&productType=skill&minPrice=0&maxPrice=10&limit=30` --- ### `search-products-with-ai-shopping-assistant` **Purch AI Shopping Assistant** — Accepts a natural language shopping query and returns an AI-generated reply plus a ranked list of matching products with prices, ratings, and purchase links sourced from Amazon and Shopify. *Use when:* Use when an agent or user wants to find and compare products using a plain-language description, optionally filtered by price range or style preferences, and needs actionable product listings with direct purchase URLs. *Not for:* Do not use for real-time inventory checks, order placement, or tracking existing purchases; this endpoint returns search recommendations only, not transactional commerce operations. **Inputs:** - `message` (string, required) — Natural language shopping request describing the desired product, budget, or features. Between 1 and 1000 characters. - `context` (object) — Optional context object to guide the AI assistant, containing priceRange (min/max numbers) and/or preferences (array of style or feature strings). **Returns:** Returns an AI reply summarizing ~22 matched products with a top pick and price range, plus a products array of listings with title, price, rating, review count, image URL, product URL, and source (Amazon or Shopify). **Example:** `{"message":"comfortable men's running shoes with good arch support under $150 suitable for daily training","context":{"priceRange":{"min":0,"max":150},"preferences":["arch support","daily training"]}}` ---