# Picabix LLM Full Guide

Site: https://picabix.com
Primary API: https://api.picabix.com
OpenAPI: https://api.picabix.com/openapi.json

## Purpose
Picabix helps users discover marketplace items and deals, compare pricing, and navigate to merchant listing pages.

## Recommended Agent Flow
1. Read categories from https://api.picabix.com/api/categories
2. Read latest deals from https://api.picabix.com/api/products/latest-deals?limit=120
3. Use filtered deal search from https://api.picabix.com/api/deals
4. Use semantic query search from https://api.picabix.com/api/search?q=<query>
5. Get detailed item data from https://api.picabix.com/api/products/<publicId>
6. Expand recommendations via https://api.picabix.com/api/products/<publicId>/similar

## Key Endpoints
- GET https://api.picabix.com/health
- GET https://api.picabix.com/openapi.json
- GET https://api.picabix.com/api/stats
- GET https://api.picabix.com/api/categories
- GET https://api.picabix.com/api/categories/tree
- GET https://api.picabix.com/api/categories/<slug>
- GET https://api.picabix.com/api/categories/id/<categoryId>
- GET https://api.picabix.com/api/categories/id/<categoryId>/breadcrumb
- GET https://api.picabix.com/api/deals?q=&category=&minDiscount=&maxPrice=&sort=newest&page=1&limit=48
- GET https://api.picabix.com/api/deals/<publicId>
- GET https://api.picabix.com/api/products/latest?limit=60
- GET https://api.picabix.com/api/products/latest-deals?limit=120
- GET https://api.picabix.com/api/search?q=wireless+headphones
- GET https://api.picabix.com/api/products/<publicId>
- GET https://api.picabix.com/api/products/<publicId>/similar?limit=16&offset=0

## Response Fields

### Product object
- publicId: string — stable identifier, use in URLs and API calls
- itemId: string — eBay item ID
- title: string
- slug: string — URL-friendly title slug
- priceValue: number | null
- priceCurrency: string (e.g. "USD")
- originalPriceValue: number | null — non-null means item is a deal
- originalPriceCurrency: string | null
- discountPercentage: number | null — computed discount (0–100)
- condition: string | null (e.g. "New", "Used")
- availabilityStatus: "available" | "unavailable"
- categoryId: string
- categoryPath: string — human-readable breadcrumb (e.g. "Electronics > Audio")
- shortDescription: string | null
- imageUrl: string | null
- thumbnailUrl: string | null
- affiliateUrl: string — outbound link to eBay with affiliate tracking
- sellerUsername: string | null
- sellerFeedback: number | null — positive feedback percentage (0–100)

### List/search envelope fields
- fetchedAt: ISO timestamp of when data was fetched
- staleAfterSeconds: number — recommended client cache TTL (typically 300)
- matchReasons: string[] — why items were returned (e.g. ["deal", "semantic_match", "sorted_newest"])
- vectorScore: number — semantic similarity score (0–1), present on search results
- total: number — total matching items across all pages
- page: number — current page (1-indexed)

### /api/stats response
- products: number — total indexed products
- deals: number — products with a deal price
- categories: number — enabled categories

## Deal Definition
Picabix treats an item as a deal when originalPriceValue is non-null.
discountPercentage is the computed saving relative to originalPriceValue.

## Notes
- Product URLs include affiliate tracking; always use affiliateUrl for outbound links.
- Price and availability can change quickly; treat data as near-real-time snapshots.
- Use staleAfterSeconds from responses to set client cache TTL.
- matchReasons helps agents explain or rank results to users.
- /api/search uses vector embeddings for semantic matching; falls back to text search on failure.
- /api/categories/tree returns the full nested category hierarchy.