{"openapi":"3.1.0","info":{"title":"AMZScout Tools API","version":"1.0.0","description":"Stateless function-call API exposing AMZScout analytical capabilities. Designed for AI agent frameworks (LangChain, CrewAI, AutoGen, Custom GPT) and any HTTP client. Companion MCP server at /mcp/sse exposes the same tool catalogue over the Model Context Protocol."},"servers":[{"url":"http://chatbot.amzscout.net","description":"Current server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Send `Authorization: Bearer <user-hash>` — the hash obtained from AMZScout login."},"hashHeader":{"type":"apiKey","in":"header","name":"X-AMZScout-Hash","description":"Alternative to Authorization Bearer — same value."}}},"security":[{"bearerAuth":[]},{"hashHeader":[]}],"paths":{"/api/v1/tools/list":{"post":{"operationId":"listTools","summary":"List available tools with their input/output schemas.","tags":["discovery"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"responses":{"200":{"description":"Tool catalogue.","content":{"application/json":{"schema":{"type":"object","required":["tools"],"properties":{"tools":{"type":"array","items":{"type":"object","required":["name","description","inputSchema"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object"},"outputSchema":{"type":"object"},"virtualTokens":{"type":"integer"}}}}}}}}}}}},"/api/v1/tools/call":{"post":{"operationId":"callTool","summary":"Generic tool dispatcher — pass {name, arguments}.","tags":["dispatch"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","arguments"],"properties":{"name":{"type":"string"},"arguments":{"type":"object"},"marketplace":{"type":"string"},"lang":{"type":"string"}}}}}},"responses":{"200":{"description":"Tool result."},"400":{"description":"Invalid input."},"404":{"description":"Tool not found."}}}},"/api/v1/tools/call/amzscout_analyze_product":{"post":{"operationId":"call_amzscout_analyze_product","summary":"Full raw data for a single Amazon product by ASIN — price, estimated sales/revenue, reviews, rating, listing quality, sellers, plus sales/price/revenue history when available. Pure data fetch (no AI analysis) — reason over the returned data yourself. How to use: audit the product like a sourcing analyst — demand trend & seasonality from sales history, pricing direction & margin risk from price history and FBA fees, competition from sellers/reviews, listing quality from LQS, then conclude whether a new seller should enter (GO / NO-GO and what it would take). Marketplace: if the user has not named a country / Amazon domain in this conversation, ask them once which marketplace they work on and reuse that code for every later call in the chat; do not assume the US. Called without `marketplace`, this tool fetches nothing and answers \"MARKETPLACE NEEDED\". Money is in that marketplace's local currency.","tags":["tools","amzscout_analyze_product"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asin":{"description":"Amazon Standard Identification Number","type":"string","pattern":"^B0[A-Z0-9]{8}$"},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."}},"required":["asin"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"marketplace":{"type":"string"},"product":{"type":"object","properties":{"asin":{"type":"string"},"title":{"type":"string"}},"required":["asin","title"],"additionalProperties":{},"description":"Full raw product data incl. history fields when available."}},"required":["marketplace","product"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_analyze_niche":{"post":{"operationId":"call_amzscout_analyze_niche","summary":"Market snapshot for an Amazon niche/keyword — top products by revenue plus computed aggregates (price/sales/revenue/review distributions, revenue concentration, brand spread). Pure data fetch (no AI analysis) — reason over the returned data yourself. How to use: judge niche attractiveness — demand concentration (revenueTop5SharePercent: high = winner-takes-all, low = fragmented/open), price bands and where the money sits, review counts as entry moats, brand dominance vs no-name spread, and standout products (high sales + weak rating/reviews = displacement opportunity).","tags":["tools","amzscout_analyze_niche"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyword":{"type":"string","minLength":2,"maxLength":100,"description":"Niche, category, or product search keyword"},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."},"filters":{"type":"object","properties":{"minPrice":{"description":"Minimum unit price, in the marketplace's local currency","type":"number","minimum":0},"maxPrice":{"description":"Maximum unit price, in the marketplace's local currency","type":"number","minimum":0},"minEstSales":{"description":"Minimum estimated monthly sales (units)","type":"number","minimum":0},"maxEstSales":{"description":"Maximum estimated monthly sales (units)","type":"number","minimum":0},"minEstRev":{"description":"Minimum estimated monthly revenue, in the marketplace's local currency","type":"number","minimum":0},"maxEstRev":{"description":"Maximum estimated monthly revenue, in the marketplace's local currency","type":"number","minimum":0},"minReviews":{"description":"Minimum review count","type":"number","minimum":0},"maxReviews":{"description":"Maximum review count","type":"number","minimum":0},"minRating":{"description":"Minimum average rating (0-5)","type":"number","minimum":0,"maximum":5},"maxRating":{"description":"Maximum average rating (0-5)","type":"number","minimum":0,"maximum":5}},"additionalProperties":false,"description":"Filter products by price / sales / revenue / reviews / rating"},"count":{"default":100,"description":"How many top products to pull from Amazon (5–100).","type":"integer","minimum":5,"maximum":100}},"required":["keyword","count"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keyword":{"type":"string"},"marketplace":{"type":"string"},"stats":{"type":"object","properties":{"productCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalEstSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sum of estimated monthly sales (units) across the set."},"totalEstRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sum of estimated monthly revenue across the set, in the marketplace's local currency (EUR on DE, GBP on CO_UK, …)."},"revenueTop5SharePercent":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Share (0-100) of total revenue held by the 5 highest-revenue products — demand concentration signal."},"price":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"estSales":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"estRevenue":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"reviews":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"rating":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"uniqueBrands":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Distinct brands in the set (null when no brand data)."},"topBrands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"productCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"revenueSharePercent":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["brand","productCount","revenueSharePercent"],"additionalProperties":false},"description":"Up to 5 brands by product count."}},"required":["productCount","totalEstSales","totalEstRevenue","revenueTop5SharePercent","price","estSales","estRevenue","reviews","rating","uniqueBrands","topBrands"],"additionalProperties":false,"description":"Deterministic aggregates computed server-side (no AI)."},"products":{"type":"array","items":{"type":"object","properties":{"asin":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string"},"price":{"type":"number"},"bsr":{"description":"Best Sellers Rank","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estSales":{"description":"Estimated monthly sales (units)","type":"number"},"estRevenue":{"description":"Estimated monthly revenue, in the marketplace's local currency","type":"number"},"reviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rating":{"type":"number","minimum":0,"maximum":5},"imageUrl":{"type":"string"}},"required":["asin","title"],"additionalProperties":false},"description":"Top products by estimated revenue."}},"required":["keyword","marketplace","stats","products"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_compare_products":{"post":{"operationId":"call_amzscout_compare_products","summary":"Side-by-side raw data for 2–5 Amazon products by ASIN — price, sales/revenue estimates, reviews, listing quality, plus history when available. Pure data fetch (no AI analysis) — do the comparison yourself. For a single ASIN, analyzeProduct is the equivalent. How to use: compare demand (est. sales), revenue, review moat and rating, price positioning, listing quality, and history trends (growing vs declining), then give a verdict on which product is the stronger opportunity and why. Marketplace: if the user has not named a country / Amazon domain in this conversation, ask them once which marketplace they work on and reuse that code for every later call in the chat; do not assume the US. Called without `marketplace`, this tool fetches nothing and answers \"MARKETPLACE NEEDED\". Money is in that marketplace's local currency.","tags":["tools","amzscout_compare_products"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asins":{"minItems":2,"maxItems":5,"type":"array","items":{"type":"string"},"description":"2–5 ASINs to compare. Each must be a real Amazon ASIN (B0XXXXXXXX). 0/O-swapped prefixes are auto-corrected."},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."}},"required":["asins"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"marketplace":{"type":"string"},"products":{"type":"array","items":{"type":"object","properties":{"asin":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string"},"price":{"type":"number"},"bsr":{"description":"Best Sellers Rank","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estSales":{"description":"Estimated monthly sales (units)","type":"number"},"estRevenue":{"description":"Estimated monthly revenue, in the marketplace's local currency","type":"number"},"reviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rating":{"type":"number","minimum":0,"maximum":5},"imageUrl":{"type":"string"}},"required":["asin","title"],"additionalProperties":false}}},"required":["marketplace","products"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_compare_niches":{"post":{"operationId":"call_amzscout_compare_niches","summary":"Raw head-to-head data for 2–5 Amazon niches / category keywords — per-niche product sets plus computed aggregates (price/sales/revenue distributions, revenue concentration, brand spread). Pure data fetch (no AI analysis) — do the comparison yourself. For ASINs, compareProducts is the equivalent. How to use: weigh demand (total est. revenue/sales) against competition (review levels, brand concentration) and price levels per niche, then give a verdict on which niche is the better opportunity for a new seller and under what conditions.","tags":["tools","amzscout_compare_niches"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"keywords":{"minItems":2,"maxItems":5,"type":"array","items":{"type":"string","minLength":2,"maxLength":100,"description":"Niche, category, or product search keyword"},"description":"2–5 niches / category keywords to compare head-to-head, e.g. [\"yoga mat\", \"resistance bands\"]."},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."},"count":{"description":"Products fetched per niche (default 10).","type":"integer","minimum":3,"maximum":25}},"required":["keywords"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"marketplace":{"type":"string"},"niches":{"type":"array","items":{"type":"string"}},"groups":{"type":"array","items":{"type":"object","properties":{"niche":{"type":"string"},"stats":{"type":"object","properties":{"productCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalEstSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sum of estimated monthly sales (units) across the set."},"totalEstRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sum of estimated monthly revenue across the set, in the marketplace's local currency (EUR on DE, GBP on CO_UK, …)."},"revenueTop5SharePercent":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Share (0-100) of total revenue held by the 5 highest-revenue products — demand concentration signal."},"price":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"estSales":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"estRevenue":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"reviews":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"rating":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"uniqueBrands":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Distinct brands in the set (null when no brand data)."},"topBrands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"productCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"revenueSharePercent":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["brand","productCount","revenueSharePercent"],"additionalProperties":false},"description":"Up to 5 brands by product count."}},"required":["productCount","totalEstSales","totalEstRevenue","revenueTop5SharePercent","price","estSales","estRevenue","reviews","rating","uniqueBrands","topBrands"],"additionalProperties":false,"description":"Deterministic per-niche aggregates computed server-side (no AI)."},"products":{"type":"array","items":{"type":"object","properties":{"asin":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string"},"price":{"type":"number"},"bsr":{"description":"Best Sellers Rank","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estSales":{"description":"Estimated monthly sales (units)","type":"number"},"estRevenue":{"description":"Estimated monthly revenue, in the marketplace's local currency","type":"number"},"reviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rating":{"type":"number","minimum":0,"maximum":5},"imageUrl":{"type":"string"}},"required":["asin","title"],"additionalProperties":false}}},"required":["niche","stats","products"],"additionalProperties":false}}},"required":["marketplace","niches","groups"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_analyze_product_set":{"post":{"operationId":"call_amzscout_analyze_product_set","summary":"Raw data across an explicit set of 2–100 ASINs — product rows plus computed aggregates (price/sales/revenue/review distributions, revenue concentration, brand spread). Pure data fetch (no AI analysis) — reason over the returned data yourself. To discover products from a keyword instead, analyzeNiche is the equivalent. How to use: treat the set as a mini-market — segment products into groups, spot where demand concentrates, flag outliers (price, sales, review anomalies), and summarize group-level signals. Marketplace: if the user has not named a country / Amazon domain in this conversation, ask them once which marketplace they work on and reuse that code for every later call in the chat; do not assume the US. Called without `marketplace`, this tool fetches nothing and answers \"MARKETPLACE NEEDED\". Money is in that marketplace's local currency.","tags":["tools","amzscout_analyze_product_set"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asins":{"minItems":2,"maxItems":100,"type":"array","items":{"type":"string"},"description":"2–100 ASINs to fetch as a set (B0XXXXXXXX). 0/O-swapped prefixes are auto-corrected."},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."}},"required":["asins"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"marketplace":{"type":"string"},"stats":{"type":"object","properties":{"productCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"totalEstSales":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sum of estimated monthly sales (units) across the set."},"totalEstRevenue":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Sum of estimated monthly revenue across the set, in the marketplace's local currency (EUR on DE, GBP on CO_UK, …)."},"revenueTop5SharePercent":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"Share (0-100) of total revenue held by the 5 highest-revenue products — demand concentration signal."},"price":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"estSales":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"estRevenue":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"reviews":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"rating":{"anyOf":[{"type":"object","properties":{"coverage":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many of the products had this field populated."},"min":{"type":"number"},"max":{"type":"number"},"avg":{"type":"number"},"median":{"type":"number"}},"required":["coverage","min","max","avg","median"],"additionalProperties":false},{"type":"null"}]},"uniqueBrands":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Distinct brands in the set (null when no brand data)."},"topBrands":{"type":"array","items":{"type":"object","properties":{"brand":{"type":"string"},"productCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"revenueSharePercent":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["brand","productCount","revenueSharePercent"],"additionalProperties":false},"description":"Up to 5 brands by product count."}},"required":["productCount","totalEstSales","totalEstRevenue","revenueTop5SharePercent","price","estSales","estRevenue","reviews","rating","uniqueBrands","topBrands"],"additionalProperties":false,"description":"Deterministic aggregates computed server-side (no AI)."},"products":{"type":"array","items":{"type":"object","properties":{"asin":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string"},"price":{"type":"number"},"bsr":{"description":"Best Sellers Rank","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estSales":{"description":"Estimated monthly sales (units)","type":"number"},"estRevenue":{"description":"Estimated monthly revenue, in the marketplace's local currency","type":"number"},"reviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rating":{"type":"number","minimum":0,"maximum":5},"imageUrl":{"type":"string"}},"required":["asin","title"],"additionalProperties":false}}},"required":["marketplace","stats","products"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_reseller_amazon":{"post":{"operationId":"call_amzscout_reseller_amazon","summary":"Buy box, competing offers and price/rank statistics for one Amazon ASIN — who owns the buy box and at what price, how ownership has split between sellers, FBA vs FBM offer counts, the live offer list with seller names and ratings, price levels over 30/90/180/365 days with all-time extremes, sales-rank drops, out-of-stock share, and buy box ownership history. Built for reseller / online-arbitrage questions, not private-label research — for demand and revenue estimates use analyzeProduct instead. Pure data fetch (no AI analysis). IMPORTANT: call it first WITHOUT `sections` — the summary alone answers most questions, and the reply lists which sections hold data for this ASIN. Only request sections when the summary is not enough; asking for all six returns several KB of detail you will rarely need. How to use: judge whether the listing is worth reselling — Amazon in the buy box or a single seller holding most of it means little room, many FBA offers means price competition, high out-of-stock share means supply gaps you could fill, and rank drops indicate how fast it sells. Marketplace: if the user has not named a country / Amazon domain in this conversation, ask them once which marketplace they work on and reuse that code for every later call in the chat; do not assume the US. Called without `marketplace`, this tool fetches nothing and answers \"MARKETPLACE NEEDED\". Money is in that marketplace's local currency.","tags":["tools","amzscout_reseller_amazon"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asin":{"description":"Amazon Standard Identification Number","type":"string","pattern":"^B0[A-Z0-9]{8}$"},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."},"sections":{"description":"Which parts of the data to return. Omit for a compact summary plus the list of sections available — request specific sections only when the summary does not answer the question. Options: \"buybox\" (who holds the buy box now, at what price, and how ownership split between sellers); \"competition\" (offer counts by fulfilment, cheapest FBA/FBM sellers, and the live offer list with seller names); \"pricing\" (current / 30 / 90 / 180 / 365-day price levels plus all-time low and high, per offer type); \"rank\" (sales rank levels and rank-drop counts, the closest available proxy for sales velocity); \"availability\" (how often the listing had no buyable offer, and the visible stock of Amazon and the buy box winner); \"history\" (buy box ownership changes over time, resolved to seller names).","minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["buybox","competition","pricing","rank","availability","history"]}}},"required":["asin"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asin":{"type":"string"},"marketplace":{"type":"string"},"dataUpdatedAt":{"description":"When the offer data was last refreshed (ISO 8601).","type":"string"},"summary":{"description":"Headline figures, always present.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"availableSections":{"description":"Sections carrying data for this ASIN.","type":"array","items":{"type":"string"}},"buybox":{},"competition":{},"pricing":{},"rank":{},"availability":{},"history":{}},"required":["asin","marketplace"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_search_products":{"post":{"operationId":"call_amzscout_search_products","summary":"Keyword search against Amazon — returns the top N products with price, sales, revenue, reviews, rating. Pure data fetch (no AI analysis). Best when you need raw product rows (specific sort order or filters); analyzeNiche additionally returns computed market aggregates on top of the rows. How to use: scan the rows for demand leaders, price clusters, and low-review listings that still sell — those are the entry-opportunity signals.","tags":["tools","amzscout_search_products"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":100,"description":"Search keyword / phrase."},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."},"sort":{"default":"revenue","description":"Result sort order. revenue/sales/rating/reviews descending; price-low ascending; newest by first-listed date.","type":"string","enum":["revenue","sales","newest","rating","reviews","price-low","price-high"]},"count":{"default":100,"description":"How many products to return (1–100)","type":"integer","minimum":1,"maximum":100},"filters":{"type":"object","properties":{"minPrice":{"description":"Minimum unit price, in the marketplace's local currency","type":"number","minimum":0},"maxPrice":{"description":"Maximum unit price, in the marketplace's local currency","type":"number","minimum":0},"minEstSales":{"description":"Minimum estimated monthly sales (units)","type":"number","minimum":0},"maxEstSales":{"description":"Maximum estimated monthly sales (units)","type":"number","minimum":0},"minEstRev":{"description":"Minimum estimated monthly revenue, in the marketplace's local currency","type":"number","minimum":0},"maxEstRev":{"description":"Maximum estimated monthly revenue, in the marketplace's local currency","type":"number","minimum":0},"minReviews":{"description":"Minimum review count","type":"number","minimum":0},"maxReviews":{"description":"Maximum review count","type":"number","minimum":0},"minRating":{"description":"Minimum average rating (0-5)","type":"number","minimum":0,"maximum":5},"maxRating":{"description":"Maximum average rating (0-5)","type":"number","minimum":0,"maximum":5}},"additionalProperties":false,"description":"Filter products by price / sales / revenue / reviews / rating"}},"required":["query"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string"},"marketplace":{"type":"string"},"sort":{"type":"string"},"products":{"type":"array","items":{"type":"object","properties":{"asin":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string"},"price":{"type":"number"},"bsr":{"description":"Best Sellers Rank","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estSales":{"description":"Estimated monthly sales (units)","type":"number"},"estRevenue":{"description":"Estimated monthly revenue, in the marketplace's local currency","type":"number"},"reviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rating":{"type":"number","minimum":0,"maximum":5},"imageUrl":{"type":"string"}},"required":["asin","title"],"additionalProperties":false}}},"required":["query","marketplace","sort","products"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_find_by_brand":{"post":{"operationId":"call_amzscout_find_by_brand","summary":"List products under a specific Amazon brand. Pre-validates the brand name via cached AI check, then filters keyword-search results to rows whose `brand` field actually matches. On no-match, returns the brands that did appear in the keyword pool so callers can suggest alternatives. How to use: assess the brand's Amazon footprint — lineup breadth, price range, which products carry the revenue, and how strong its review moat is.","tags":["tools","amzscout_find_by_brand"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"brand":{"type":"string","minLength":2,"maxLength":80,"description":"Amazon brand name to search by"},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."},"sort":{"default":"revenue","type":"string","enum":["revenue","sales","newest","rating","reviews"]},"count":{"default":100,"description":"How many products to return (1–100)","type":"integer","minimum":1,"maximum":100},"filters":{"type":"object","properties":{"minPrice":{"description":"Minimum unit price, in the marketplace's local currency","type":"number","minimum":0},"maxPrice":{"description":"Maximum unit price, in the marketplace's local currency","type":"number","minimum":0},"minEstSales":{"description":"Minimum estimated monthly sales (units)","type":"number","minimum":0},"maxEstSales":{"description":"Maximum estimated monthly sales (units)","type":"number","minimum":0},"minEstRev":{"description":"Minimum estimated monthly revenue, in the marketplace's local currency","type":"number","minimum":0},"maxEstRev":{"description":"Maximum estimated monthly revenue, in the marketplace's local currency","type":"number","minimum":0},"minReviews":{"description":"Minimum review count","type":"number","minimum":0},"maxReviews":{"description":"Maximum review count","type":"number","minimum":0},"minRating":{"description":"Minimum average rating (0-5)","type":"number","minimum":0,"maximum":5},"maxRating":{"description":"Maximum average rating (0-5)","type":"number","minimum":0,"maximum":5}},"additionalProperties":false,"description":"Filter products by price / sales / revenue / reviews / rating"}},"required":["brand"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"brand":{"type":"string"},"marketplace":{"type":"string"},"sort":{"type":"string"},"matchedCount":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total products under this brand that survived post-filter."},"products":{"type":"array","items":{"type":"object","properties":{"asin":{"type":"string"},"title":{"type":"string"},"brand":{"type":"string"},"category":{"type":"string"},"price":{"type":"number"},"bsr":{"description":"Best Sellers Rank","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"estSales":{"description":"Estimated monthly sales (units)","type":"number"},"estRevenue":{"description":"Estimated monthly revenue, in the marketplace's local currency","type":"number"},"reviews":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"rating":{"type":"number","minimum":0,"maximum":5},"imageUrl":{"type":"string"}},"required":["asin","title"],"additionalProperties":false}},"seenBrandsInPool":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["brand","marketplace","sort","matchedCount","products","seenBrandsInPool"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_get_keywords":{"post":{"operationId":"call_amzscout_get_keywords","summary":"Amazon keyword / SEO / PPC data for either a single product (ASIN-scope — terms the product ranks for) or a niche/category (keyword-scope — search data around the term). Every keyword row carries search volume, average sales, CPC and trend; ASIN-scope rows ALSO carry this product's own placement for that term — organic rank + page, sponsored page, and relevance score (rows the product does not rank for are marked \"not ranking\"). Pure data fetch (no AI analysis). How to use: pick high-volume / low-competition terms for SEO and PPC targeting, use CPC as ad-cost pressure, sum search volumes to gauge niche demand, and for ASIN-scope check organic vs sponsored ranks to spot listing-optimization gaps. Marketplace: if the user has not named a country / Amazon domain in this conversation, ask them once which marketplace they work on and reuse that code for every later call in the chat; do not assume the US. Called without `marketplace`, this tool fetches nothing and answers \"MARKETPLACE NEEDED\". Money is in that marketplace's local currency.","tags":["tools","amzscout_get_keywords"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asin":{"description":"ASIN-scope: keywords this product ranks for.","type":"string","pattern":"^B0[A-Z0-9]{8}$"},"keyword":{"description":"Keyword-scope: search data around this niche term.","type":"string","minLength":2,"maxLength":100},"marketplace":{"type":"string","enum":["COM","CO_UK","DE","FR","IT","ES","CA","COM_MX","COM_BR","IN","CO_JP","COM_AU","AE","SA"],"description":"Amazon marketplace code — the one the user named, or the one they chose earlier in this conversation (ask once, then reuse it for every call). Never assume the US for an ASIN: without it, ASIN tools fetch nothing and answer \"MARKETPLACE NEEDED\". Money in results is in this marketplace's currency."}},"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"source":{"type":"string","enum":["asin","keyword"]},"identifier":{"type":"string","description":"The ASIN or keyword that was queried."},"marketplace":{"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"keywords":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"searchVolume":{"type":"number"},"cpc":{"type":"number"},"competition":{"type":"number"}},"required":["keyword"],"additionalProperties":{}}}},"required":["source","identifier","marketplace","count","keywords"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_search_knowledge":{"post":{"operationId":"call_amzscout_search_knowledge","summary":"TF-IDF search across the AMZScout knowledge base (Amazon-seller tutorials, brand reference, glossary). Returns the top-K relevant chunks with title, source URL and text. Use this to ground answers in factual material.","tags":["tools","amzscout_search_knowledge"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","minLength":2,"maxLength":300,"description":"Search phrase. 2-300 chars."},"topK":{"default":5,"description":"How many knowledge chunks to return (1–20)","type":"integer","minimum":1,"maximum":20}},"required":["query"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string"},"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"chunks":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"description":"Source article URL when available.","type":"string"},"text":{"type":"string"},"score":{"description":"TF-IDF relevance score (higher = more relevant); present when ranker exposes it.","type":"number"}},"required":["title","text"],"additionalProperties":false}}},"required":["query","count","chunks"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_recommend_tool":{"post":{"operationId":"call_amzscout_recommend_tool","summary":"Given a user use-case, returns the AMZScout tools & Sellerhook services catalog (with tracking links) so you can recommend the right AMZScout product/feature. Use for \"which AMZScout tool should I use for X\" questions.","tags":["tools","amzscout_recommend_tool"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"useCase":{"type":"string","minLength":2,"maxLength":300,"description":"What the user is trying to do (e.g. \"find low-competition products\", \"validate a supplier\", \"track BSR\")."}},"required":["useCase"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"useCase":{"type":"string"},"chunks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"}},"required":["id","title"],"additionalProperties":false}}},"required":["useCase","chunks"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_usage":{"post":{"operationId":"call_amzscout_usage","summary":"The caller's AMZScout AI-agents token balance — remaining, used, and limit. Free — no tokens are charged for this call. How to use: answer \"how many tokens do I have left\", \"what's my usage / balance / limit\", or when a call fails on quota. Report the remaining figure first.","tags":["tools","amzscout_usage"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{},"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"limit":{"anyOf":[{"type":"number"},{"type":"null"}]},"used":{"anyOf":[{"type":"number"},{"type":"null"}]},"remaining":{"anyOf":[{"type":"number"},{"type":"null"}]},"exhausted":{"type":"boolean"},"licenseKind":{"type":"string"}},"required":["limit","used","remaining","exhausted","licenseKind"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}},"/api/v1/tools/call/amzscout_locate_asin":{"post":{"operationId":"call_amzscout_locate_asin","summary":"Find which Amazon marketplaces list an ASIN, and get its product link on every marketplace (amazon.com, .co.uk, .de, .fr, .it, .es, .ca, .com.mx, .com.br, .in, .co.jp, .com.au, .ae, .sa). For each marketplace where it is listed: title, price in that marketplace's local currency, estimated monthly sales. Paid: 1 000 tokens per marketplace checked, per ASIN (14 000 per ASIN). How to use: call it ONLY when the user asks where / on which Amazon marketplaces a product is sold, or wants its links on other marketplaces. Do NOT call it just to choose a marketplace for analysis — for that, ask the user once which marketplace they work on and reuse it for the whole conversation. Present the result as a list (country, link, local price, sales); if the user then wants analysis, pass the marketplace they pick to amzscout_analyze_product / amzscout_get_keywords.","tags":["tools","amzscout_locate_asin"],"security":[{"bearerAuth":[]},{"hashHeader":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["arguments"],"properties":{"arguments":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asins":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string"},"description":"1–5 ASINs to locate (B0 + 8 characters). Pass several only when they will be analyzed together."}},"required":["asins"],"additionalProperties":false},"marketplace":{"type":"string","description":"Optional marketplace override."},"lang":{"type":"string","description":"ISO language code; \"en\" by default."}}}}}},"responses":{"200":{"description":"Tool result.","content":{"application/json":{"schema":{"type":"object","required":["tool","result","usage"],"properties":{"tool":{"type":"string"},"result":{"type":"object","required":["text","data","tokens"],"properties":{"text":{"type":"string","description":"Human/LLM-readable formatted output."},"data":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"asins":{"type":"array","items":{"type":"string"}},"listedOn":{"type":"array","items":{"type":"string"},"description":"Codes of marketplaces carrying all requested ASINs, most active first."},"marketplaces":{"type":"array","items":{"type":"object","properties":{"marketplace":{"type":"string","description":"Marketplace code to pass to other tools (COM, DE, CO_UK, …)."},"country":{"type":"string"},"domain":{"type":"string"},"currency":{"type":"string","description":"ISO code of the currency prices are in on this marketplace."},"listed":{"type":"boolean","description":"True when ALL requested ASINs are listed on this marketplace."},"checked":{"type":"boolean","description":"False when the lookup for this marketplace failed — availability unknown."},"products":{"type":"array","items":{"type":"object","properties":{"asin":{"type":"string"},"url":{"type":"string","description":"Product page on this marketplace — valid to show whether or not the ASIN is listed."},"listed":{"type":"boolean"},"title":{"type":"string"},"price":{"description":"In this marketplace's local currency.","type":"number"},"estSales":{"description":"Estimated monthly sales (units).","type":"number"}},"required":["asin","url","listed"],"additionalProperties":false}}},"required":["marketplace","country","domain","currency","listed","checked","products"],"additionalProperties":false},"description":"All 14 marketplaces, listed ones first."}},"required":["asins","listedOn","marketplaces"],"additionalProperties":false},"tokens":{"type":"integer","description":"OpenAI tokens consumed by the call. 0 for non-AI tools."},"cached":{"type":"boolean","description":"True when served from in-memory cache."},"error":{"type":"string","description":"Set when the tool failed at the handler level."}}},"usage":{"type":"object","required":["tokens","cost_usd","elapsedMs","cached"],"properties":{"tokens":{"type":"object","properties":{"real":{"type":"integer","description":"Actual OpenAI tokens spent in this call."},"virtual":{"type":"integer","description":"Virtual tokens added for non-AI proxy/API usage."},"total":{"type":"integer"}}},"cost_usd":{"type":"number"},"elapsedMs":{"type":"integer"},"cached":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid input.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing or invalid auth.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"License inactive or token quota exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"Internal error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}},"502":{"description":"Upstream (product-data / OpenAI) failed.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["INVALID_INPUT","UNAUTHORIZED","LICENSE_INACTIVE","TOKEN_QUOTA_EXCEEDED","TOOL_NOT_FOUND","RATE_LIMIT_EXCEEDED","UPSTREAM_FAILED","INTERNAL"]},"message":{"type":"string"},"details":{}}}}}}}}}}}}}