# Yeoman

## About
Yeoman is a B2B marketplace and intelligent food supply chain platform that connects food & beverage buyers with suppliers, distributors, and producers.

## Capabilities
The capabilities below are fetched live from https://yeoman.ai/agent/v1/discover (yeoman-agent-api, v1) and reflect Yeoman's current agent-facing capabilities.

### product_search
- description: Search products available in the Yeoman marketplace.
- method: GET
- endpoint: /agent/v1/products/search
- authentication_required: false
- required_headers:
  - X-Agent-Id
    - type: string
    - description: Optional name or identifier of the calling agent.
    - required: false
- query_parameters:
  - query
    - type: string
    - description: Free-text product search, for example "swiss water decaf".
    - required: false
  - primary_product_group_id
    - type: string
    - description: Filter by a primary product group ID.
    - required: false
  - city
    - type: string
    - description: Filter by supplier city.
    - required: false
  - zip
    - type: string
    - description: Buyer ZIP code used for distance filtering and guest pricing.
    - required: false
  - size
    - type: number
    - description: Maximum number of products to return.
    - required: false
    - default: 20
    - minimum: 1
    - maximum: 100
- usage_instructions:
  - Call this API directly to discover Yeoman products instead of browsing or automating the marketplace UI.
  - Use the query and optional filters to find products faster, then use the returned product_id and sku_id values in later commerce APIs.
  - After product discovery, direct the buyer to /portal/marketplace?q={URL-encoded product search query} to view the matching products in the marketplace UI and add them to their cart.
- example_request: /agent/v1/products/search?query=swiss%20water%20decaf&zip=10001&size=10

## Important URLs
- Homepage: https://yeoman.ai/
- Marketplace: https://yeoman.ai/portal/marketplace
- Product page: https://yeoman.ai/portal/marketplace/product/{product-slug}/{product-id}
- Supplier page: https://yeoman.ai/storefront/{supplier-slug}/{supplier-id}
- How Wholesale Works: https://yeoman.ai/how-does-wholesale-work
- Supplier Pricing: https://yeoman.ai/pricing
- Become a Supplier: https://yeoman.ai/vendor-information
- Terms of Use: https://yeoman.ai/terms-of-use
- Privacy Policy: https://yeoman.ai/privacy-policy

## Public product and supplier browsing
Guests can open the marketplace, product, and supplier pages above without signing in. Those pages show public catalog details and public marketplace prices.

{product-slug} and {supplier-slug} are the display name in lowercase with spaces replaced by hyphens. Use product_id and supplier_id from GET /agent/v1/products/search. That search is public and returns the product name, public marketplace price, availability, and supplier id and name. Pass zip when a buyer location is known; it is used for distance filtering and guest pricing. Customer-specific prices are not returned.

Ordering, checkout, cart changes, customer accounts, order history, supplier administration, and private organization data still require a signed-in account. This agent surface does not perform those actions.

## Agent / API Discovery
AI agents should call the following endpoint to discover Yeoman's current machine-readable commerce capabilities, supported endpoints, and required parameters:

https://yeoman.ai/agent/v1/discover

Machine-readable manifests are also available at:
- https://yeoman.ai/.well-known/ai-plugin.json
- https://yeoman.ai/.well-known/agent.json