{ "openapi": "3.1.0", "info": { "title": "Apiguru Amazon Data API", "version": "1.1.4", "summary": "Real-time structured Amazon marketplace data: product details, reviews, search, best-sellers, deals, seller profiles, and live offers/stock across 20 country marketplaces.", "description": "Real-time structured Amazon marketplace data: product details, reviews, search, best-sellers, deals, seller profiles, and live offers/stock across 20 country marketplaces.\n\n## Two ways to call this API\n\n**Humans / existing customers** — send `X-API-KEY` against `https://dash.apiguru.app/api/v1`.\n\n**AI agents** — call `https://agent.apiguru.app/agent/v1` with no credentials at all. You get 3 free calls per 24h, then an HTTP 402 with a `PAYMENT-REQUIRED` challenge you settle in USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913) on Base mainnet (eip155:8453). No account, no API key, no subscription.\n\nAn MCP server is available at `https://mcp.apiguru.app/mcp`.\n\n## Retry policy\n\nRetry 503 and 429 with backoff. Never retry 400/404 - the input itself is the problem.\n", "contact": { "email": "support@apiguru.app" } }, "servers": [ { "url": "https://dash.apiguru.app/api/v1", "description": "Keyed API (X-API-KEY)" }, { "url": "https://agent.apiguru.app/agent/v1", "description": "Keyless agent gateway (x402, USDC on Base)" } ], "security": [ { "ApiKeyHeader": [] }, { "ApiKeyQuery": [] }, {} ], "components": { "securitySchemes": { "ApiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-KEY" }, "ApiKeyQuery": { "type": "apiKey", "in": "query", "name": "api_key" } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "request_id": { "type": "string" } }, "required": [ "error" ] } } }, "paths": { "/v2/product-details": { "get": { "operationId": "product_details", "summary": "Full product detail for a single ASIN", "description": "Fetches the complete product record for one ASIN on one marketplace: title, price, star rating, rating count, images, description, feature bullets, variations and category.\n\n**Price:** $0.01 per call\n\n**Notes:** 404 means the ASIN is absent from that marketplace and IS billed. 503 means our fetch failed and is NOT billed - retry. Bullet points and specs are what Amazon shows for the listing; on multi-variant listings they can describe the product family rather than the exact variant. A null field means Amazon did not show it.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asin", "in": "query", "required": true, "description": "Single Amazon ASIN, 10 uppercase alphanumeric characters. Exactly one - comma-separated lists are rejected; use product_details_batch for many.", "schema": { "type": "string", "pattern": "^[A-Z0-9]{10}$" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "asin": "B09DJLW458", "product_title": "Example Product", "product_price": "$29.99", "product_star_rating": "4.5", "product_num_ratings": 1284 }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/product_details_bp.py" } }, "/v2/product-reviews": { "get": { "operationId": "product_reviews", "summary": "Customer reviews for a single ASIN", "description": "Returns the review block for one ASIN: overall star rating, total rating count, Amazon's 'customers say' AI summary, and the individual review list.\n\n**Price:** $0.01 per call\n\n**Notes:** Same 404-billed / 503-not-billed semantics as product_details.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asin", "in": "query", "required": true, "description": "Single Amazon ASIN, 10 uppercase alphanumeric characters.", "schema": { "type": "string", "pattern": "^[A-Z0-9]{10}$" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "asin": "B09DJLW458", "product_title": "Example Product", "product_star_rating": "4.5", "product_num_ratings": 1284, "customers_say": "Customers like the build quality and value.", "product_reviews": [] }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/product_reviews_v2_bp.py" } }, "/search": { "get": { "operationId": "search", "summary": "Search Amazon products by keyword", "description": "Keyword search with pagination, sorting, and filtering by category, price range, condition, brand or seller.\n\n**Price:** $0.01 per call\n\n**Notes:** Blank values and the literal string 'null' are treated as unset. `page` must be a positive integer or the call 400s. Ten filters narrow a search besides `query`: page, sort_by, geo, brand, seller_id, category_id, min_price, max_price, product_condition and today_deals. `product_num_ratings` and `offers_count` are integers; `product_star_rating`, `product_price` and `product_original_price` are decimal strings; a null field means Amazon did not show it for that result. `is_prime` is true when the result carries a Prime badge or its delivery line offers Prime delivery. `metadata.total_pages` says how far `page` can go. `delivery` splits the delivery line: `free_delivery_date` is the date a non-member gets for free, `prime_delivery` the slot Prime would give, `fastest_delivery_date` the paid faster option; `raw` is always the whole line. Dates are the strings Amazon printed, and on non-English marketplaces only `raw` may be filled.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "query", "in": "query", "required": true, "description": "Search keywords. Required and must be non-empty.", "schema": { "type": "string", "minLength": 1 } }, { "name": "page", "in": "query", "required": false, "description": "Result page, 1-based.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "sort_by", "in": "query", "required": false, "description": "Result ordering.", "schema": { "type": "string", "enum": [ "RELEVANCE", "BEST_SELLERS", "LOW_HIGH_PRICE", "HIGH_LOW_PRICE", "REVIEWS", "NEWEST" ], "default": "RELEVANCE" } }, { "name": "category_id", "in": "query", "required": false, "description": "Restrict to an Amazon category id.", "schema": { "type": "string" } }, { "name": "min_price", "in": "query", "required": false, "description": "Minimum price filter, marketplace currency.", "schema": { "type": "string" } }, { "name": "max_price", "in": "query", "required": false, "description": "Maximum price filter, marketplace currency.", "schema": { "type": "string" } }, { "name": "product_condition", "in": "query", "required": false, "description": "Condition filter, e.g. NEW or USED.", "schema": { "type": "string" } }, { "name": "brand", "in": "query", "required": false, "description": "Brand name filter.", "schema": { "type": "string" } }, { "name": "seller_id", "in": "query", "required": false, "description": "Restrict results to one seller.", "schema": { "type": "string" } }, { "name": "today_deals", "in": "query", "required": false, "description": "Restrict to items in today's deals.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "metadata": { "page_number": 1, "page_size": 48, "total": 4912, "total_pages": 103 }, "products": [ { "asin": "B0888TJNH1", "product_title": "Womens Capri V Sporty Flip Flop", "product_brand": "Crocs", "product_price": "24.95", "product_original_price": "39.99", "product_price_per_unit": null, "promotion": null, "product_star_rating": "4.5", "product_num_ratings": 5167, "product_url": "https://www.amazon.com/dp/B0888TJNH1", "product_photo": "https://m.media-amazon.com/images/I/....jpg", "product_stock_message": null, "is_prime": false, "is_sponsored": false, "is_amazon_choice": false, "is_best_seller": false, "climate_pledge": false, "has_variations": true, "badges": [], "sales_volume": "200+ bought in past month", "product_delivery_info": "Join Prime to get FREE delivery Today 6 PM - 11 PM Or Non-members get FREE delivery Thu, Sep 10", "delivery": { "raw": "Join Prime to get FREE delivery Today 6 PM - 11 PM Or Non-members get FREE delivery Thu, Sep 10", "free_delivery_date": "Thu, Sep 10", "fastest_delivery_date": null, "prime_delivery": "Today 6 PM - 11 PM" }, "offers_count": 1 } ], "amazon_request_count": 1, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/search_product_bp.py" } }, "/product": { "get": { "operationId": "product_details_batch", "summary": "Product detail for up to 20 ASINs in one call", "description": "Batch variant of product_details. Accepts a comma-separated ASIN list, deduplicates it, and fetches all of them concurrently. Far cheaper and faster than N single calls.\n\n**Price:** $0.008 per item (max 20)\n\n**Notes:** Billed per ASIN processed, including ones that come back not-found. More than 20 ASINs returns 413. Bullet points and specs are what Amazon shows for the listing; on multi-variant listings they can describe the product family rather than the exact variant. A null field means Amazon did not show it.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asins", "in": "query", "required": true, "description": "Comma-separated ASIN list, maximum 20 after de-duplication. Each must be 10 uppercase alphanumeric characters.", "schema": { "type": "string" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "asin": "B09DJLW458", "product_title": "Example Product" } ], "billable_requests_count": 1, "amazon_request_count": 1, "response_time": "1420ms", "country_code": "US", "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "per_item", "unitPriceUsd": "0.008", "countParam": "asins", "countSeparator": ",", "maxItems": 20, "countDedup": true }, "x-apiguru-source": "blueprints/product_details_batch_bp.py" } }, "/stock": { "get": { "operationId": "offers_stock", "summary": "Live offers and inventory for up to 10 ASINs", "description": "Returns the current offer list per ASIN (seller, price, condition, buy-box winner) and, optionally, the actual purchasable stock quantity.\n\n**Price:** $0.015 per item (max 10)\n\n**Notes:** Billed per upstream Amazon request, which is more than one per ASIN when check_inventory is true. /scrape is a legacy alias for the same handler.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asins", "in": "query", "required": true, "description": "Comma-separated ASIN list, maximum 10. Each must be 10 uppercase alphanumeric characters; malformed entries are rejected with 400.", "schema": { "type": "string" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "check_inventory", "in": "query", "required": false, "description": "Resolve the true purchasable stock quantity. Slower and bills more upstream requests, so leave off unless you need the number.", "schema": { "type": "boolean", "default": false } }, { "name": "offers_count", "in": "query", "required": false, "description": "'all' for every offer, 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID.", "schema": { "type": "string", "default": "all" } }, { "name": "condition", "in": "query", "required": false, "description": "Comma-separated condition filter. Any of ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE. Unrecognised values silently fall back to ALL.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "asin": "B09DJLW458", "offers": [], "stock": 42 } ], "amazon_request_count": 1, "response_time": 2100, "country_code": "US", "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "per_item", "unitPriceUsd": "0.015", "countParam": "asins", "countSeparator": ",", "maxItems": 10, "countDedup": false }, "x-apiguru-source": "blueprints/offers_stock_bp.py" } }, "/scrape": { "get": { "operationId": "offers_stock_alias", "summary": "Live offers and inventory for up to 10 ASINs (legacy alias of /stock)", "description": "Returns the current offer list per ASIN (seller, price, condition, buy-box winner) and, optionally, the actual purchasable stock quantity.\n\n**Price:** $0.015 per item (max 10)\n\n**Notes:** Billed per upstream Amazon request, which is more than one per ASIN when check_inventory is true. /scrape is a legacy alias for the same handler.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "asins", "in": "query", "required": true, "description": "Comma-separated ASIN list, maximum 10. Each must be 10 uppercase alphanumeric characters; malformed entries are rejected with 400.", "schema": { "type": "string" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "check_inventory", "in": "query", "required": false, "description": "Resolve the true purchasable stock quantity. Slower and bills more upstream requests, so leave off unless you need the number.", "schema": { "type": "boolean", "default": false } }, { "name": "offers_count", "in": "query", "required": false, "description": "'all' for every offer, 'winner' for the buy-box offer only, or a specific alphanumeric Offer ID.", "schema": { "type": "string", "default": "all" } }, { "name": "condition", "in": "query", "required": false, "description": "Comma-separated condition filter. Any of ALL, NEW, USED_LIKE_NEW, USED_VERY_GOOD, USED_GOOD, USED_ACCEPTABLE. Unrecognised values silently fall back to ALL.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "asin": "B09DJLW458", "offers": [], "stock": 42 } ], "amazon_request_count": 1, "response_time": 2100, "country_code": "US", "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "per_item", "unitPriceUsd": "0.015", "countParam": "asins", "countSeparator": ",", "maxItems": 10, "countDedup": false }, "x-apiguru-source": "blueprints/offers_stock_bp.py", "deprecated": true } }, "/v2/best-sellers": { "get": { "operationId": "best_sellers", "summary": "Best-seller rankings for a category", "description": "Returns the current Amazon best-seller list for a category, with optional subcategory drill-down and pagination.\n\n**Price:** $0.01 per call\n\n**Notes:** No required parameters - calling it bare returns US appliances page 1.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "category", "in": "query", "required": false, "description": "Category slug, lowercased by the server. Defaults to 'appliances'.", "schema": { "type": "string", "default": "appliances" } }, { "name": "subcategory_code", "in": "query", "required": false, "description": "Optional subcategory node id to drill into.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Result page, 1-based.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "best_sellers": [] }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/best_sellers_bp.py" } }, "/v2/deals": { "get": { "operationId": "deals", "summary": "Current Amazon deals with filters", "description": "Returns active Amazon deals, filterable by category, brand, minimum star rating, price band, discount band, and Prime early access.\n\n**Price:** $0.01 per call\n\n**Notes:** The bucket parameters are ordinal buckets, not literal prices or percentages. min_product_star_rating rejects 5.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset, non-negative.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "categories", "in": "query", "required": false, "description": "Category filter.", "schema": { "type": "string" } }, { "name": "min_product_star_rating", "in": "query", "required": false, "description": "Minimum star rating. Only 1, 2, 3, 4 or ALL are accepted - 5 is rejected with 400.", "schema": { "type": "string", "enum": [ "1", "2", "3", "4", "ALL" ] } }, { "name": "price_range", "in": "query", "required": false, "description": "Price band bucket 1-5, or ALL.", "schema": { "type": "string", "enum": [ "1", "2", "3", "4", "5", "ALL" ] } }, { "name": "discount_range", "in": "query", "required": false, "description": "Discount band bucket 1-4, or ALL.", "schema": { "type": "string", "enum": [ "1", "2", "3", "4", "ALL" ] } }, { "name": "brands", "in": "query", "required": false, "description": "Brand filter.", "schema": { "type": "string" } }, { "name": "prime_early_access", "in": "query", "required": false, "description": "Restrict to Prime early access deals.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "deals": { "data": [] }, "amazon_request_count": 1, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/deals_bp.py" } }, "/seller-profile": { "get": { "operationId": "seller_profile_batch", "summary": "Seller profiles for up to 10 seller IDs", "description": "Returns the storefront profile for each seller id: business name, rating, feedback counts, address and marketplace presence.\n\n**Price:** $0.012 per item (max 10)\n\n**Notes:** Seller ID validation is all-or-nothing: one malformed id rejects the entire request with 400.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "seller_ids", "in": "query", "required": true, "description": "Comma-separated seller IDs, maximum 10. Each must be 13-15 alphanumeric characters or the whole call 400s.", "schema": { "type": "string" } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "results": [ { "seller_id": "A1B2C3D4E5F6G", "business_name": "Example Seller" } ], "billable_requests_count": 1, "amazon_request_count": 1, "response_time": 1800, "country_code": "US", "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "per_item", "unitPriceUsd": "0.012", "countParam": "seller_ids", "countSeparator": ",", "maxItems": 10, "countDedup": false }, "x-apiguru-source": "blueprints/seller_profile_batch_bp.py" } }, "/v2/seller-products": { "get": { "operationId": "seller_products", "summary": "Products listed by a seller", "description": "Returns the paginated catalogue of products offered by a given seller storefront.\n\n**Price:** $0.01 per call\n\n**Notes:** Unlike seller_profile_batch, seller_id format is not pattern-validated here.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "seller_id", "in": "query", "required": true, "description": "Amazon seller ID. Required.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Result page, 1-based.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "products": [] }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/seller_products_bp.py" } }, "/v2/seller-reviews": { "get": { "operationId": "seller_reviews", "summary": "Feedback reviews for a seller", "description": "Returns paginated seller feedback, optionally filtered to a star-rating window.\n\n**Price:** $0.01 per call\n\n**Notes:** from_rating and to_rating are optional; omit both for unfiltered feedback.", "tags": [ "Amazon Data" ], "parameters": [ { "name": "seller_id", "in": "query", "required": true, "description": "Amazon seller ID. Required.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Result page, 1-based.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "from_rating", "in": "query", "required": false, "description": "Lower bound of the star-rating filter.", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "to_rating", "in": "query", "required": false, "description": "Upper bound of the star-rating filter.", "schema": { "type": "integer", "minimum": 1, "maximum": 5 } }, { "name": "geo", "in": "query", "required": false, "description": "Marketplace country code.", "schema": { "type": "string", "enum": [ "US", "CA", "DE", "MX", "UK", "FR", "IT", "ES", "AU", "BR", "IN", "JP", "NL", "AE", "PL", "SA", "SG", "SE", "TR", "BE" ], "default": "US" } } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object" }, "example": { "success": true, "data": { "reviews": [] }, "request_id": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f" } } } }, "400": { "description": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or invalid API key on the keyed path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "402": { "description": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "Account disabled, or no active subscription plan.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Too many items in a batch request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Per-second rate limit exceeded for the plan. Back off and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error. NOT billed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-apiguru-price": { "model": "flat", "priceUsd": "0.01" }, "x-apiguru-source": "blueprints/seller_reviews_bp.py" } } }, "x-apiguru-geos": { "US": "com", "CA": "ca", "DE": "de", "MX": "com.mx", "UK": "co.uk", "FR": "fr", "IT": "it", "ES": "es", "AU": "com.au", "BR": "com.br", "IN": "in", "JP": "co.jp", "NL": "nl", "AE": "ae", "PL": "pl", "SA": "sa", "SG": "sg", "SE": "se", "TR": "com.tr", "BE": "com.be" }, "x-apiguru-conventions": { "asin_pattern": "^[A-Z0-9]{10}$", "asin_note": "Uppercase only. Lowercase ASINs are rejected with 400 - normalise before calling.", "seller_id_pattern": "^[A-Za-z0-9]{13,15}$", "geo_default": "US", "sample_asin": "B09DJLW458", "error_semantics": { "400": "Bad input (bad ASIN format, unknown geo, missing required param). NOT billed.", "401": "Missing or invalid API key on the keyed path.", "402": "Payment required. On the agent path this carries a PAYMENT-REQUIRED challenge. On the keyed path it means the account balance is exhausted.", "403": "Account disabled, or no active subscription plan.", "413": "Too many items in a batch request.", "429": "Per-second rate limit exceeded for the plan. Back off and retry.", "404": "The ASIN genuinely does not exist on that marketplace. BILLED - the upstream fetch was performed and the bad input was the caller's. Retrying will not help; try a different geo.", "503": "Upstream fetch failed on our side (block, parse fault). NOT billed. Safe and correct to retry.", "500": "Internal error. NOT billed." }, "retry_policy": "Retry 503 and 429 with backoff. Never retry 400/404 - the input itself is the problem." } }