{"openapi":"3.2.0","info":{"title":"Amazon Product Data API","description":"Real-time Amazon US data: product details and prices, search, keyword rankings, Best Sellers, New Releases, search suggestions and seller products.","version":"1.0.0"},"servers":[{"url":"https://fvnwv.jojapi.net"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"System"},{"name":"Products"},{"name":"Search"},{"name":"Discover"},{"name":"Sellers"}],"x-agent-commerce":{"catalog_url":"https://fvnwv.jojapi.net/_jojapi/agent/plans","discovery_url":"https://fvnwv.jojapi.net/.well-known/x402","directory_url":"https://agents.jojapi.net/apis/amazonapi","docs":"https://docs.jojapi.com/consumers/agents"},"paths":{"/api/v1/health":{"get":{"operationId":"get_api_v1_health","summary":"Service status","description":"Liveness check. Does not call Amazon.","tags":["System"],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/products/{asin}":{"get":{"operationId":"get_api_v1_products_asin","summary":"Product details","description":"Live product data for one ASIN (or Amazon product URL): title, brand, category path, current and list price, discount, coupon, deal, availability status, seller and fulfilment, delivery dates, rating with star distribution, Best Sellers Rank, BSR-based sales estimate, badges, images, variations, features and specifications. Always fetched live from Amazon.","tags":["Products"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"asin","in":"path","description":"10-character ASIN (e.g. B09B8V1LZ3) or a full Amazon product URL","required":true,"schema":{"type":"string"}}]}},"/api/v1/products/{asin}/price-history":{"get":{"operationId":"get_api_v1_products_asin_price_history","summary":"Price history","description":"Every price this API recorded for the ASIN (one point per live product fetch, at most every 15 minutes unless the price changes) with lowest, highest, average and change over the period. Served from the database, no Amazon request.","tags":["Products"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"asin","in":"path","description":"10-character ASIN (e.g. B09B8V1LZ3) or a full Amazon product URL","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","description":"Period in days","required":false,"schema":{"type":"integer","default":30}}]}},"/api/v1/products/batch":{"post":{"operationId":"post_api_v1_products_batch","summary":"Product details for up to 10 ASINs","description":"Live product details for up to 10 ASINs or product URLs in one call. Each result has status \"ok\" with the product, or \"error\" with an error code — one failing ASIN doesn't fail the batch.","tags":["Products"],"responses":{"200":{"description":"Default Response"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["asins"],"properties":{"asins":{"type":"array","minItems":1,"maxItems":10,"items":{"type":"string","minLength":10,"maxLength":2048},"description":"Up to 10 ASINs or product URLs"}}},"example":{}}}}}},"/api/v1/products/batch/async":{"post":{"operationId":"post_api_v1_products_batch_async","summary":"Queue up to 50 ASINs","description":"Queues up to 50 ASINs and returns a batchId immediately (HTTP 202). Poll GET /api/v1/jobs/{batchId} until status is \"completed\". Results are kept for 60 minutes.","tags":["Products"],"responses":{"200":{"description":"Default Response"}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["asins"],"properties":{"asins":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"string","minLength":10,"maxLength":2048},"description":"Up to 50 ASINs or product URLs"}}},"example":{}}}}}},"/api/v1/jobs/{batchId}":{"get":{"operationId":"get_api_v1_jobs_batchId","summary":"Async batch status and results","description":"Progress and per-ASIN results of a batch created with POST /api/v1/products/batch/async. status is \"processing\" until every ASIN finished, then \"completed\".","tags":["Products"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"batchId","in":"path","required":true,"schema":{"type":"string"}}]}},"/api/v1/products/{asin}/reviews":{"get":{"operationId":"get_api_v1_products_asin_reviews","summary":"Top reviews and rating breakdown","description":"Rating average, total count and star distribution plus the top reviews Amazon shows on the product page (typically 8-13, including reviews from other countries): rating, title, text, author, date, country, variant, verified purchase, Vine flag, helpful votes and review images. Cached up to 24 hours and refreshed whenever the product is fetched live.","tags":["Products"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"asin","in":"path","description":"10-character ASIN (e.g. B09B8V1LZ3) or a full Amazon product URL","required":true,"schema":{"type":"string"}},{"name":"sort","in":"query","description":"top = Amazon order","required":false,"schema":{"type":"string","enum":["top","recent","helpful"],"default":"top"}},{"name":"rating","in":"query","description":"Only reviews with this star rating","required":false,"schema":{"type":"integer"}},{"name":"verifiedOnly","in":"query","description":"Only verified purchases","required":false,"schema":{"type":"boolean","default":false}}]}},"/api/v1/products/lookup":{"get":{"operationId":"get_api_v1_products_lookup","summary":"Find ASIN by UPC, EAN, ISBN or GTIN","description":"Resolves a barcode (UPC-A, EAN-13, ISBN-10, ISBN-13 or GTIN-14) to Amazon products. The check digit is validated first. Returns the best match and up to 10 candidates. Matches are cached for 30 days.","tags":["Products"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"code","in":"query","description":"Barcode digits, e.g. 054000598449 or 9780593135204","required":true,"schema":{"type":"string"}}]}},"/api/v1/search":{"get":{"operationId":"get_api_v1_search","summary":"Product search","description":"Live Amazon search results for a keyword, with optional sort, price range, Prime, minimum rating and department filters. Each result has position, ASIN, title, brand, byline (author/artist/publisher), price, list price, discount, format, rating, bought-in-past-month, Prime and sponsored flags, badge, deal, coupon and delivery. Amazon shows 16 (list layout) or 48 (grid layout) results per page depending on the query. Sponsored placements in separate ad blocks are not included. isPrime is null when Amazon shows no delivery details for the result.","tags":["Search"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"q","in":"query","description":"Search keywords","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Result page (1-20)","required":false,"schema":{"type":"integer","default":1}},{"name":"sort","in":"query","description":"Result order","required":false,"schema":{"type":"string","enum":["relevance","price_asc","price_desc","rating","newest","best_sellers"],"default":"relevance"}},{"name":"minPrice","in":"query","description":"Minimum price in USD","required":false,"schema":{"type":"number"}},{"name":"maxPrice","in":"query","description":"Maximum price in USD","required":false,"schema":{"type":"number"}},{"name":"primeOnly","in":"query","description":"Only Prime-eligible products","required":false,"schema":{"type":"boolean","default":false}},{"name":"minRating","in":"query","description":"Only products rated at least this many stars","required":false,"schema":{"type":"string","enum":["1","2","3","4"]}},{"name":"department","in":"query","description":"Limit the search to one department","required":false,"schema":{"type":"string","enum":["appliances","arts_crafts","automotive","baby","beauty","books","computers","electronics","fashion","garden_outdoor","grocery","health_household","home_kitchen","kindle_store","movies_tv","music","office_products","pet_supplies","sports_outdoors","tools","toys_games","video_games"]}}]}},"/api/v1/keywords/rank":{"get":{"operationId":"get_api_v1_keywords_rank","summary":"Keyword rank of a product","description":"Scans up to 5 live search result pages for a keyword and returns where the ASIN appears: overall position, organic position (sponsored results excluded), page and position on page. found is false when the ASIN is not in the scanned pages. Every scanned page is one Amazon request; scanning stops at the page where the ASIN is found.","tags":["Search"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"keyword","in":"query","required":true,"schema":{"type":"string"}},{"name":"asin","in":"query","description":"ASIN or Amazon product URL","required":true,"schema":{"type":"string"}},{"name":"pages","in":"query","description":"How many result pages to scan at most","required":false,"schema":{"type":"integer","default":3}}]}},"/api/v1/discover/best-sellers":{"get":{"operationId":"get_api_v1_discover_best_sellers","summary":"Best Sellers","description":"Amazon Best Sellers with rank, ASIN, title, price and rating. Without category: the top items of every department (department field set per item). With category (see /discover/categories): that category's list. Amazon updates these lists hourly; responses are cached for up to 1 hour.","tags":["Discover"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"category","in":"query","description":"Category slug from GET /api/v1/discover/categories, e.g. electronics or electronics/541966","required":false,"schema":{"type":"string"}}]}},"/api/v1/discover/new-releases":{"get":{"operationId":"get_api_v1_discover_new_releases","summary":"Hot New Releases","description":"Amazon Hot New Releases with rank, ASIN, title, price and rating, for all departments or one category. Cached for up to 1 hour.","tags":["Discover"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"category","in":"query","description":"Category slug from GET /api/v1/discover/categories, e.g. electronics or electronics/541966","required":false,"schema":{"type":"string"}}]}},"/api/v1/discover/autocomplete":{"get":{"operationId":"get_api_v1_discover_autocomplete","summary":"Search suggestions","description":"Keyword suggestions Amazon shows in its search box while typing. Useful for keyword research. Cached for 24 hours.","tags":["Discover"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"q","in":"query","description":"Partial search text","required":true,"schema":{"type":"string"}}]}},"/api/v1/discover/categories":{"get":{"operationId":"get_api_v1_discover_categories","summary":"Category tree","description":"Best Sellers categories with their slugs, for the category parameter of /discover/best-sellers and /discover/new-releases. Without parent: top-level departments. With parent (e.g. electronics): its sub-categories (slugs like electronics/541966). Cached until the end of the day (UTC).","tags":["Discover"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"parent","in":"query","description":"Category slug from GET /api/v1/discover/categories, e.g. electronics or electronics/541966","required":false,"schema":{"type":"string"}}]}},"/api/v1/sellers/{sellerId}/products":{"get":{"operationId":"get_api_v1_sellers_sellerId_products","summary":"Seller storefront products","description":"Live list of products sold by a seller, in the same format as /search results.","tags":["Sellers"],"responses":{"200":{"description":"Default Response"}},"parameters":[{"name":"sellerId","in":"path","description":"Amazon seller ID, e.g. A2R2RITDJNW1Q6","required":true,"schema":{"type":"string"}},{"name":"page","in":"query","description":"Result page (1-20)","required":false,"schema":{"type":"integer","default":1}}]}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-JoJAPI-Key","description":"Your JoJ API key."}}}}