{"openapi":"3.1.0","paths":{"/v1/niches":{"get":{"description":"Retrieves a paginated list of Niches. Each Niche represents a market segment or product category being tracked.","operationId":"ExternalApiV1Controller_listNiches","parameters":[{"name":"currentPage","required":false,"in":"query","description":"The page of items to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page. By default, it is 20. Max page size is 50","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NicheList"}}}},"400":{"description":"Invalid pagination parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List all Niches","tags":["v1"]}},"/v1/niches/{nicheId}/keywords":{"get":{"description":"Retrieves the master keyword list for the specified niche. The master keyword list contains relevant search terms monitored for ranking and performance metrics.","operationId":"ExternalApiV1Controller_getMasterKeywordList","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GetMasterKeywordListResult"}}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get master keyword list for a niche","tags":["v1"]}},"/v1/niches/{nicheId}/competitors":{"get":{"description":"Retrieves the list of Competitors within the specified Niche along with Niche statistics. For the Niche, returns keyword statistics, opportunity evaluation, and benchmark median values. For each Competitor, returns key business metrics including sales, revenue, number of variations, main image URL, and more.","operationId":"ExternalApiV1Controller_getCompetitorList","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/GetCompetitorListResult"}}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get Competitor list and Niche statistics","tags":["v1"]}},"/v1/niches/{nicheId}/ranking-juices":{"get":{"description":"Retrieves the Ranking Juices for each Competitor within the specified Niche. Ranking Juice is a DataDive proprietary metric that identifies the key factors driving search ranking success for each Competitor's listing. The API also returns the maximum Ranking Juice benchmark calculated using the keyword staffing method.","operationId":"ExternalApiV1Controller_calculateRankingJuices","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/NicheRankingJuices"}}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get Ranking Juices for a Niche","tags":["v1"]}},"/v1/niches/{nicheId}/roots":{"get":{"description":"Retrieves the keyword lexical roots for the specified Niche. Roots are individual words or word combinations extracted from the Master Keyword List. For example, \"bluetooth headphones\" contains roots: \"bluetooth\", \"headphones\", and \"bluetooth headphones\". This analysis helps identify the most impactful keywords and their search volume distribution.","operationId":"ExternalApiV1Controller_getRootsForNiche","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ExternalRootResponseDto"}}}}]}}}},"400":{"description":"Invalid nicheId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get keyword roots for a Niche","tags":["v1"]}},"/v1/niches/{nicheId}/ai-copywriter":{"post":{"description":"Starts an advanced-AI listing generation for the Niche and returns immediately with a `generationId`. Generation runs asynchronously — poll GET /v1/niches/:nicheId/ai-copywriter/:generationId until `status` is `complete` (result available) or `failed`.","operationId":"ExternalApiV1Controller_useAiCopywriterForNiche","parameters":[{"name":"nicheId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AiCopyWriterInputDto"}}}},"responses":{"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Use AI Copywriter for the niche","tags":["v1"]}},"/v1/niches/{nicheId}/ai-copywriter/{generationId}":{"get":{"description":"Retrieves the status of an advanced-AI listing generation started via POST /v1/niches/:nicheId/ai-copywriter. Returns different schemas based on state: generating (in progress), complete (with the generated listing), or failed (with an error). Poll this endpoint until the generation completes.","operationId":"ExternalApiV1Controller_getAiCopywriterStatus","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}},{"name":"generationId","required":true,"in":"path","description":"The generationId returned when the generation was started","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/AiListingGenerationGeneratingResponseDto"},{"$ref":"#/components/schemas/AiListingGenerationCompleteResponseDto"},{"$ref":"#/components/schemas/AiListingGenerationFailedResponseDto"}]}}}},"400":{"description":"Invalid generationId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"AI listing generation not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get AI Copywriter generation status","tags":["v1"]}},"/v1/niches/{nicheId}":{"delete":{"description":"Deletes the specified Niche and all associated data including keywords, competitors, all dives and diveboxes. Note: A Niche cannot be deleted if it is used in any Rank Radar.","operationId":"ExternalApiV1Controller_deleteNiche","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Niche not found"},"409":{"description":"Niche cannot be deleted because it is used in a rank radar"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Deletes the Niche","tags":["v1"]}},"/v1/niches/rank-radars":{"get":{"description":"Retrieves a paginated list of Rank Radars. Rank Radars track keyword rankings over time for specific ASINs, monitoring organic and sponsored positions across search results. Returns summary metrics including top 10/50 keyword counts and search volumes. By default only active Rank Radars are returned; use the status filter for paused or archived ones.","operationId":"ExternalApiV1Controller_getRankRadarList","parameters":[{"name":"nicheId","required":false,"in":"query","description":"Filter Rank Radars by Niche identifier","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by Rank Radar status. ACTIVE (the default) returns Rank Radars that are tracking; PAUSED returns those stopped via the archive endpoint; ARCHIVED returns those removed via DELETE; ALL returns active and paused together. Any other value is rejected with 400.","schema":{"enum":["ACTIVE","PAUSED","ARCHIVED","ALL"],"type":"string"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page. By default, it is 20. Max page size is 50","schema":{"example":20}},{"name":"currentPage","required":false,"in":"query","description":"The page of items to retrieve. By default, it is 1","schema":{"example":1}},{"name":"searchText","required":false,"in":"query","description":"Filter Rank Radars by ASIN or product title","schema":{}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalRankRadarListResponseDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List all Rank Radars","tags":["v1"]},"post":{"description":"Creates a new Rank Radar to track keyword rankings for a specific ASIN within a Niche. The Rank Radar will monitor organic and sponsored rankings for the specified number of keywords. Rank Radar Search Term tokens are consumed based on the number of keywords tracked. Returns a rankRadarId for accessing the tracking data.","operationId":"ExternalApiV1Controller_createRankRadar","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRankRadarRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRankRadarSuccessResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRankRadarErrorResponseDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Create a new Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}":{"get":{"description":"Retrieves historical keyword ranking data for the specified Rank Radar within a date range. Returns tracked keywords with their daily organic and impression rank positions. Use this to analyze ranking trends and performance over time.","operationId":"ExternalApiV1Controller_getRankRadarKeywordList","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}},{"name":"startDate","required":true,"in":"query","description":"Start date for the ranking data range in yyyy-mm-dd format","schema":{"example":"2024-03-26","type":"string"}},{"name":"endDate","required":true,"in":"query","description":"End date for the ranking data range in yyyy-mm-dd format","schema":{"example":"2024-03-26","type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KrtKeywordListResponseDto"}}}},"400":{"description":"Invalid rankRadarId or date format"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get keyword rankings for a Rank Radar","tags":["v1"]},"delete":{"description":"Deletes the specified Rank Radar and all associated keyword ranking data. Frees Daily Tracked Keywords quota.","operationId":"ExternalApiV1Controller_deleteRankRadar","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"responses":{"204":{"description":"Deleted"},"400":{"description":"Invalid rankRadarId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Deletes the Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/archive":{"post":{"description":"Archives (pauses) an active Rank Radar. Tracking stops for all of its keywords and the Daily Tracked Keywords quota is freed, but the Rank Radar and its historical data are retained. Rank Radars archived this way are listed with the status=PAUSED filter, not status=ARCHIVED (which covers those removed via DELETE), and are reactivated via the resume endpoint. This operation is idempotent: archiving an already-archived Rank Radar succeeds without changes.","operationId":"ExternalApiV1Controller_archiveRankRadar","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"responses":{"204":{"description":"Archived"},"400":{"description":"Invalid rankRadarId"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Archive a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/resume":{"post":{"description":"Resumes (reactivates) an archived Rank Radar. Keyword tracking is restarted for as many keywords as the available Daily Tracked Keywords quota allows, prioritizing the most relevant keywords. This operation is idempotent: resuming an already-active Rank Radar succeeds without changes.","operationId":"ExternalApiV1Controller_resumeRankRadar","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"responses":{"204":{"description":"Resumed"},"400":{"description":"Invalid rankRadarId or Daily Tracked Keywords quota exceeded"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Resume a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/search-terms":{"post":{"description":"Adds manual search terms (keywords) to an existing Rank Radar for tracking. New keywords are added to the Niche and start being tracked, while any previously paused matching keywords are resumed. Daily Tracked Keywords quota is consumed for each newly tracked keyword. Returns the origin breakdown of the submitted terms and `keywordToRankRadarKeywordIdMap`, mapping each term to its Rank Radar keyword identifier.","operationId":"ExternalApiV1Controller_addRankRadarSearchTerms","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddSearchTermsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalAddSearchTermsResponseDto"}}}},"400":{"description":"Invalid rankRadarId, invalid search terms, or Daily Tracked Keywords quota exceeded"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Add search terms to a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/search-terms/archive":{"post":{"description":"Archives (pauses) the specified search terms of a Rank Radar so they stop being tracked and their Daily Tracked Keywords quota is freed. Search terms are identified by their Rank Radar keyword identifiers (the `id` values returned by GET /v1/niches/rank-radars/:rankRadarId and the `keywordToRankRadarKeywordIdMap` values returned by the add search terms endpoint). This operation is idempotent: search terms that are already archived are left unchanged.","operationId":"ExternalApiV1Controller_archiveRankRadarSearchTerms","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarSearchTermIdsDto"}}}},"responses":{"204":{"description":"Archived"},"400":{"description":"Invalid rankRadarId or rankRadarKeywordIds"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Archive search terms of a Rank Radar","tags":["v1"]}},"/v1/niches/rank-radars/{rankRadarId}/search-terms/resume":{"post":{"description":"Resumes (unpauses) the specified archived search terms of a Rank Radar so they start being tracked again. Daily Tracked Keywords quota is consumed for each resumed search term. Search terms are identified by their Rank Radar keyword identifiers. This operation is idempotent: search terms that are already active are left unchanged.","operationId":"ExternalApiV1Controller_resumeRankRadarSearchTerms","parameters":[{"name":"rankRadarId","required":true,"in":"path","description":"The unique identifier of the Rank Radar","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankRadarSearchTermIdsDto"}}}},"responses":{"204":{"description":"Resumed"},"400":{"description":"Invalid rankRadarId, invalid rankRadarKeywordIds, or Daily Tracked Keywords quota exceeded"},"401":{"description":"Api key is invalid"},"403":{"description":"Rank Radar does not belong to this subscription, or the member who authorized this connection no longer has access to the organization"},"404":{"description":"Rank Radar not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Resume search terms of a Rank Radar","tags":["v1"]}},"/v1/niches/dives":{"post":{"description":"Initiates a Niche Dive starting from a hero ASIN. The Niche Dive process automatically identifies and analyzes Competitors, extracts relevant keywords, and generates complete Niche research data. Dive tokens are consumed based on the number of Competitors specified. Returns a diveId to track the analysis progress.","operationId":"ExternalApiV1Controller_createDive","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveSuccessResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveErrorResponseDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Create a new Niche Dive","tags":["v1"]}},"/v1/niches/dive_with_competitors":{"post":{"description":"Initiates a Niche Dive from a caller-provided list of Competitor ASINs — no automatic Competitor discovery is performed. Mirrors the \"ASIN tray → Create Niche\" flow in the extension. Dive tokens are consumed based on the number of ASINs supplied. Returns a diveId to track the analysis progress via GET /v1/niches/dives/{diveId}.","operationId":"ExternalApiV1Controller_createDiveWithCompetitors","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveWithCompetitorsRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveWithCompetitorsResponseDto"}}}},"400":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateNicheDiveErrorResponseDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"The number of ASINs exceeds your plan limit, or you are at your Niche limit"},"404":{"description":"Resource not found"},"422":{"description":"Current product data could not be found for enough of the given ASINs. No Dive tokens are consumed."},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Create a new Niche Dive from an explicit Competitor list","tags":["v1"]}},"/v1/niches/{nicheId}/redive":{"post":{"description":"Re-runs a Dive on an existing Niche to refresh its research data. Two modes:\n\n- `same_competitors` — re-dives the Niche's current Competitor set. Takes no other field.\n- `discover` — searches for a fresh Competitor set, keeping any `lockedAsins` and skipping any `excludedAsins`. `numberOfCompetitors` is the total number of ASINs the refreshed Dive should contain, including the locked ones. `heroAsin` is the seed product discovery starts from; when omitted it defaults to the Niche Competitor with the highest sales, preferring one that belongs to one of your connected seller accounts.\n\nThe Dive runs asynchronously and consumes Dive tokens like any other Dive. Poll GET /v1/niches/dives/{diveId} with the returned `diveId` until the status is `success` or `error`. The refreshed data stays on the same `nicheId`; no new Niche is created.","operationId":"ExternalApiV1Controller_rediveNiche","parameters":[{"name":"nicheId","required":true,"in":"path","description":"The unique identifier of the Niche to re-dive","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RediveNicheRequestDto"}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ResponseDto"},{"properties":{"data":{"$ref":"#/components/schemas/RediveNicheResponseDto"}}}]}}}},"400":{"description":"Invalid nicheId or request body, a field that does not belong to the given mode, or not enough Dive tokens for the requested number of Competitors"},"401":{"description":"Api key is invalid"},"403":{"description":"The Niche belongs to another subscription, or the requested number of Competitors exceeds your plan limit"},"404":{"description":"Niche not found, or it has no completed research to re-dive"},"422":{"description":"In `same_competitors` mode, current product data could no longer be found for enough of the Niche's Competitors to re-dive (for example they were delisted). No Dive tokens are consumed."},"429":{"description":"Rate limit exceeded (2 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Re-dive an existing Niche","tags":["v1"]}},"/v1/sellers/{sellerId}/marketplaces/{marketplace}/asins/{asin}/inventory":{"get":{"description":"Returns the sellable units of an ASIN at each Amazon fulfillment center, for one of your connected seller accounts.\n\n`distribution` includes every fulfillment center currently assigned to this ASIN, including those with `availableStock: 0` — useful for spotting regional stockouts.\n\nOnly the sellable disposition is broken down. Inbound, reserved, and unsellable units are not currently included.\n\n`lastUpdatedAt` is the timestamp of the most recent daily refresh from Amazon. It is `null` if the inventory data hasn't been refreshed in the last 30 days.\n\nRate limited to approximately 60 requests per minute per API key.\n\nExample:\n```\ncurl -H \"x-api-key: $API_KEY\" \\\n  https://api.datadive.tools/v1/sellers/A1B2C3/marketplaces/com/asins/B0ABCDEFGH/inventory\n```","operationId":"ExternalApiV1Controller_getInventoryByFc","parameters":[{"name":"asin","required":true,"in":"path","description":"Amazon Standard Identification Number","schema":{"example":"B0ABCDEFGH"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InventoryByFcResponseDto"}}}},"400":{"description":"Malformed sellerId, marketplace, or ASIN"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Caller cannot access inventory for this combination of seller, marketplace, and ASIN. Returned identically whether the seller is not owned by the caller or the ASIN is not in the catalog (prevents seller/ASIN enumeration)."},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get per-fulfillment-center sellable inventory for an ASIN","tags":["v1"]}},"/v1/alerts/indexing-issues":{"get":{"description":"Returns a paginated list of indexing-issue alerts across your connected Amazon seller accounts. An indexing-issue alert fires when one of your ASINs is no longer indexed for its tracked keywords. Results are scoped to your organization. Optionally filter by `sellerId`, `marketplace`, lifecycle `status`, and `updatedSince` (for incremental polling). Defaults to active alerts from the last 30 days. Rate limited to approximately 60 requests per minute per API key.","operationId":"ExternalApiV1Controller_listIndexingIssueAlerts","parameters":[{"name":"sellerId","required":false,"in":"query","description":"Filter to a single Amazon seller account you have connected to DataDive","schema":{"example":"A1B2C3D4E5","type":"string"}},{"name":"marketplace","required":false,"in":"query","description":"Filter to a single Amazon marketplace code (e.g. com, co.uk, de, ca)","schema":{"example":"com","type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]}},{"name":"status","required":false,"in":"query","description":"Lifecycle filter. `active` (default) returns unresolved alerts, `resolved` returns resolved alerts, `all` returns both. Dismissed alerts are never returned.","schema":{"default":"active","type":"string","enum":["active","resolved","all"]}},{"name":"updatedSince","required":false,"in":"query","description":"Return only alerts surfaced at or after this ISO-8601 timestamp (filters on `lastAlertedAt`, i.e. when the alert was created). Use this to incrementally sync since your last poll. Defaults to the last 30 days when omitted.","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexingIssueAlertListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List indexing-issue alerts","tags":["v1"]}},"/v1/alerts/blind-spend":{"get":{"description":"Returns a paginated list of blind-spend alerts across your connected Amazon seller accounts. A blind-spend alert flags ad spend on customer search terms that produced little or no sales; each alert embeds its unresolved wasted-spend search terms with spend/clicks/CVR. Results are scoped to your organization. Optionally filter by `sellerId`, `marketplace`, lifecycle `status`, and `updatedSince` (for incremental polling). Defaults to active alerts from the last 30 days. Rate limited to approximately 60 requests per minute per API key.","operationId":"ExternalApiV1Controller_listBlindSpendAlerts","parameters":[{"name":"sellerId","required":false,"in":"query","description":"Filter to a single Amazon seller account you have connected to DataDive","schema":{"example":"A1B2C3D4E5","type":"string"}},{"name":"marketplace","required":false,"in":"query","description":"Filter to a single Amazon marketplace code (e.g. com, co.uk, de, ca)","schema":{"example":"com","type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]}},{"name":"status","required":false,"in":"query","description":"Lifecycle filter. `active` (default) returns unresolved alerts, `resolved` returns resolved alerts, `all` returns both. Dismissed alerts are never returned.","schema":{"default":"active","type":"string","enum":["active","resolved","all"]}},{"name":"updatedSince","required":false,"in":"query","description":"Return only alerts surfaced at or after this ISO-8601 timestamp (filters on `lastAlertedAt`, i.e. when the alert was created). Use this to incrementally sync since your last poll. Defaults to the last 30 days when omitted.","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BlindSpendAlertListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded (approximately 60 requests/min per API key)."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List wasted-spend (blind spend) alerts","tags":["v1"]}},"/v1/seller_profiles":{"get":{"description":"Returns a paginated list of Amazon seller profiles connected to your organization. Use the sellerId and marketplace from these results to query seller-specific endpoints such as catalog and inventory.","operationId":"ExternalApiV1Controller_listSellerProfiles","parameters":[{"name":"currentPage","required":false,"in":"query","description":"The page of items to retrieve. By default, it is 1","schema":{"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Number of items per page. By default, it is 20. Max page size is 50","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SellerProfileListDto"}}}},"400":{"description":"Invalid pagination parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List seller profiles","tags":["v1"]}},"/v1/sellers/{sellerId}/marketplaces/{marketplace}/catalog":{"get":{"description":"Returns a paginated list of ASINs from the product catalog for the specified seller account and marketplace. Supports filtering by search text (title/brand), brand name, and product status. Defaults to Active products only; pass status=all to include all statuses.","operationId":"ExternalApiV1Controller_listCatalogAsins[0]","parameters":[{"name":"search","required":false,"in":"query","description":"Partial match on product title or brand","schema":{"example":"wireless earbuds","type":"string"}},{"name":"brand","required":false,"in":"query","description":"Partial match on brand name","schema":{"example":"Anker","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by product status. Defaults to \"Active\". Use \"all\" to include all statuses.","schema":{"default":"Active","example":"Active","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogAsinListDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List catalog ASINs for a seller","tags":["v1"]}},"/v1/seller_profiles/{sellerId}/marketplaces/{marketplace}/catalog":{"get":{"description":"Returns a paginated list of ASINs from the product catalog for the specified seller account and marketplace. Supports filtering by search text (title/brand), brand name, and product status. Defaults to Active products only; pass status=all to include all statuses.","operationId":"ExternalApiV1Controller_listCatalogAsins[1]","parameters":[{"name":"search","required":false,"in":"query","description":"Partial match on product title or brand","schema":{"example":"wireless earbuds","type":"string"}},{"name":"brand","required":false,"in":"query","description":"Partial match on brand name","schema":{"example":"Anker","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by product status. Defaults to \"Active\". Use \"all\" to include all statuses.","schema":{"default":"Active","example":"Active","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatalogAsinListDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List catalog ASINs for a seller","tags":["v1"]}},"/v1/sellers/{sellerId}/marketplaces/{marketplace}/listing-changes":{"get":{"description":"Returns a paginated list of listing changes (price, content, image) detected for the specified seller account and marketplace. Optionally filter by ASIN, brand, date range, and change type. Set `includeCorrelations=true` to enrich each change with before/after sales and ranking metrics.","operationId":"ExternalApiV1Controller_listListingChanges[0]","parameters":[{"name":"types","required":false,"in":"query","description":"Comma-separated listing change types to filter by (Price, Content, Image). Defaults to all.","schema":{"type":"array","items":{"type":"string"}}},{"name":"asin","required":false,"in":"query","description":"Filter by exact ASIN or parent ASIN","schema":{"example":"B0ABCDEFGH","type":"string"}},{"name":"brand","required":false,"in":"query","description":"Filter by brand name (partial match)","schema":{"example":"Anker","type":"string"}},{"name":"search","required":false,"in":"query","description":"Search by title or brand (partial match)","schema":{"example":"wireless earbuds","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date filter (ISO 8601)","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date filter (ISO 8601)","schema":{"example":"2024-07-01T00:00:00Z","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort field","schema":{"default":"date","type":"string","enum":["date","type"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"includeCorrelations","required":false,"in":"query","description":"Include before/after metric correlations for each change","schema":{"default":false,"type":"boolean"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingChangesExternalListDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List listing changes for a seller","tags":["v1"]}},"/v1/seller_profiles/{sellerId}/marketplaces/{marketplace}/listing-changes":{"get":{"description":"Returns a paginated list of listing changes (price, content, image) detected for the specified seller account and marketplace. Optionally filter by ASIN, brand, date range, and change type. Set `includeCorrelations=true` to enrich each change with before/after sales and ranking metrics.","operationId":"ExternalApiV1Controller_listListingChanges[1]","parameters":[{"name":"types","required":false,"in":"query","description":"Comma-separated listing change types to filter by (Price, Content, Image). Defaults to all.","schema":{"type":"array","items":{"type":"string"}}},{"name":"asin","required":false,"in":"query","description":"Filter by exact ASIN or parent ASIN","schema":{"example":"B0ABCDEFGH","type":"string"}},{"name":"brand","required":false,"in":"query","description":"Filter by brand name (partial match)","schema":{"example":"Anker","type":"string"}},{"name":"search","required":false,"in":"query","description":"Search by title or brand (partial match)","schema":{"example":"wireless earbuds","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Start date filter (ISO 8601)","schema":{"example":"2024-06-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"End date filter (ISO 8601)","schema":{"example":"2024-07-01T00:00:00Z","type":"string"}},{"name":"sortBy","required":false,"in":"query","description":"Sort field","schema":{"default":"date","type":"string","enum":["date","type"]}},{"name":"sortOrder","required":false,"in":"query","description":"Sort direction","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"includeCorrelations","required":false,"in":"query","description":"Include before/after metric correlations for each change","schema":{"default":false,"type":"boolean"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 20, max 50)","schema":{"minimum":1,"maximum":50,"example":20,"type":"number"}},{"name":"marketplace","required":true,"in":"path","description":"Amazon marketplace code (e.g. `com`, `co.uk`, `de`, `ca`)","schema":{"example":"com"}},{"name":"sellerId","required":true,"in":"path","description":"Amazon seller account identifier (`amzSellerId`) connected to DataDive","schema":{"example":"A1B2C3D4E5"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingChangesExternalListDto"}}}},"400":{"description":"Invalid parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List listing changes for a seller","tags":["v1"]}},"/v1/quota":{"get":{"description":"Returns current quota usage and capacity for all billable features, along with the next quota refresh date.","operationId":"ExternalApiV1Controller_getQuotaUsage","parameters":[],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalQuotaResponseDto"}}}},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get quota usage","tags":["v1"]}},"/v1/usage":{"get":{"description":"Returns a paginated list of billable feature usage logs for your organization. Each entry represents a token consumption event (e.g. a dive, rank radar creation, AI copywriter prompt). Optionally filter by feature type, user name/email, and date range.","operationId":"ExternalApiV1Controller_getUsageLogs","parameters":[{"name":"type","required":false,"in":"query","description":"Filter by billable feature type","schema":{"type":"string","enum":["DIVED_ASINS","PRODUCT_BRIEF_ASINS","AI_COPYWRITER_PROMPTS","RANK_RADAR_KEYWORDS","INDEXING_DIAGNOSIS"]}},{"name":"search","required":false,"in":"query","description":"Search by user name or email (case-insensitive partial match)","schema":{"example":"john","type":"string"}},{"name":"startDate","required":false,"in":"query","description":"Filter usage logs created on or after this date (ISO 8601)","schema":{"example":"2024-01-01T00:00:00Z","type":"string"}},{"name":"endDate","required":false,"in":"query","description":"Filter usage logs created on or before this date (ISO 8601)","schema":{"example":"2024-12-31T23:59:59Z","type":"string"}},{"name":"currentPage","required":false,"in":"query","description":"Page of items to retrieve (default 1)","schema":{"minimum":1,"example":1,"type":"number"}},{"name":"pageSize","required":false,"in":"query","description":"Items per page (default 50, max 200)","schema":{"minimum":1,"maximum":200,"example":50,"type":"number"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExternalUsageLogListDto"}}}},"400":{"description":"Invalid query parameters"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"List billable feature usage logs","tags":["v1"]}},"/v1/niches/dives/{diveId}":{"get":{"description":"Retrieves the current status of a Niche Dive analysis. Returns different response schemas based on the Dive state: in_progress (with estimated completion time), success (with nicheId and token usage), or error (with error details). Poll this endpoint to track the progress of a Dive until completion.","operationId":"ExternalApiV1Controller_getDiveStatus","parameters":[{"name":"diveId","required":true,"in":"path","description":"The unique identifier of the Dive","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/NicheDiveStatusSuccessResponseDto"},{"$ref":"#/components/schemas/NicheDiveStatusInProgressResponseDto"},{"$ref":"#/components/schemas/NicheDiveStatusErrorResponseDto"}]}}}},"400":{"description":"Invalid diveId"},"401":{"description":"Api key is invalid"},"403":{"description":"Unauthorized to access the resource"},"404":{"description":"Resource not found"},"429":{"description":"Rate limit exceeded, either the per-client-IP limit or the per-API-key limit for this endpoint."},"500":{"description":"Internal error"}},"security":[{"apiKey":[]}],"summary":"Get Niche Dive status","tags":["v1"]}}},"info":{"title":"Data Dive Developer APIs","description":"\n  An API key is required to call the APIs in this page. The key must be set in the header named <b>x-api-key</b>.\n  <p>Example: call a Data-Dive api with curl</p>\n\n  ```bash\n  curl -X 'GET' \\\n  'https://api.datadive.tools/v1/mkl/z515cGOFg3' \\\n  -H 'accept: application/json' \\\n  -H 'x-api-key: apikey1234abcdefghij0123456789'\n  ```\n  \n  ## MCP (Model Context Protocol)\n\n  These APIs also back the DataDive remote MCP server. AI tools connected via MCP call them with an\n  OAuth 2.1 Bearer access token instead of an <b>x-api-key</b> header; both credentials resolve to the\n  same organization-scoped access. Connect an AI tool from **Data Dive > Your account > API Key**.\n  \n  ## Webhook Events\n\n  Webhook events are delivered as HTTP POST requests to your configured webhook URL. To set up, edit, or archive webhooks, navigate to **Data Dive > Your account > [Integrations](https://2.datadive.tools/integrations)**. From there you can:\n\n  * Provide your endpoint destination URL.\n  * Subscribe to specific event topics.\n  ","version":"1.0.0","contact":{}},"tags":[],"servers":[{"url":"https://api.datadive.tools"}],"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Your API key on DataDive","scheme":"apiKey"},"mcpBearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"MCP OAuth 2.1 access token, issued by connecting an AI tool to DataDive"}},"schemas":{"NicheItem":{"type":"object","properties":{"nicheId":{"type":"string","example":"z515cGOFg3","description":"The unique identifier of the Niche"},"heroKeyword":{"type":"string","example":"dog hat","description":"The primary keyword that defines the Niche"},"nicheLabel":{"type":"string","example":"Dog-hat opportunity","description":"A human-readable label for the Niche"},"marketplace":{"type":"string","example":"com","description":"The Amazon marketplace domain (e.g., com, uk, de)"},"latestResearchDate":{"type":"object","description":"The date when the Niche data was last updated"}},"required":["nicheId","heroKeyword","nicheLabel","marketplace","latestResearchDate"]},"NicheList":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/NicheItem"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"ResponseDto":{"type":"object","properties":{"message":{"type":"string","example":["request successfully processed"]},"data":{"type":"object"}}},"BidInfo":{"type":"object","properties":{"min":{"type":"number","description":"Min bid. For USD, the value is in cent. For example: 101 means $1.01"},"max":{"type":"number","description":"Max bid. For USD, the value is in cent. For example: 886 means $8.86"},"median":{"type":"number","description":"Average bid. For USD, the value is in cent. For example: 445 means $4.45"}},"required":["min","max","median"]},"MasterKeyword":{"type":"object","properties":{"keyword":{"type":"string","description":"The search term or keyword phrase"},"searchVolume":{"type":"number","description":"Monthly search volume for this keyword on Amazon"},"relevancy":{"type":"object","description":"Relevancy score indicating how well the keyword matches the Niche. Can be \"Outlier\" or a numeric score."},"asinRanks":{"type":"object","example":{"B09DCJJ9R3":2,"B09JZSHN73":4,"B09512SA73":null},"description":"Competitor ASINs organic ranks for this keyword. Null indicates the product is not ranked in the first pages."},"suggestedBid":{"nullable":true,"description":"Exact-match suggested bid (in cents). Null when not yet fetched for the latest dive.","type":"object","allOf":[{"$ref":"#/components/schemas/BidInfo"}]}},"required":["keyword","searchVolume","relevancy","asinRanks","suggestedBid"]},"GetMasterKeywordListResult":{"type":"object","properties":{"keywords":{"description":"List of search terms in Master Keywords List with their search volume, relevancy, Competitors ranks, and exact-match suggested bid (in cents; null when not yet fetched for the latest dive)","type":"array","items":{"$ref":"#/components/schemas/MasterKeyword"}},"latestResearchDate":{"format":"date-time","type":"string","description":"The date when the Niche was last researched"}},"required":["keywords","latestResearchDate"]},"MklStatisticsData":{"type":"object","properties":{"numKeywords":{"type":"number"},"numVisibleKeywords":{"type":"number"},"numMaxVisibleKeywords":{"type":"number"},"totalSvOfKeywords":{"type":"number"},"totalSvOfVisibleKeywords":{"type":"number"},"totalSvOfVisibleOutlierKeywords":{"type":"number"},"totalSvOfResidueKeywords":{"type":"number"}},"required":["numKeywords","numVisibleKeywords","numMaxVisibleKeywords","totalSvOfKeywords","totalSvOfVisibleKeywords","totalSvOfVisibleOutlierKeywords","totalSvOfResidueKeywords"]},"NumericOpportunityValue":{"type":"object","properties":{"value":{"type":"number","example":49.5},"opportunity":{"type":"string","enum":["none","veryGoodOpportunity","goodOpportunity","badOpportunity","veryBadOpportunity"],"example":"goodOpportunity"}},"required":["value","opportunity"]},"OpportunityEvaluation":{"type":"object","properties":{"competitionSvStrength":{"$ref":"#/components/schemas/NumericOpportunityValue"},"competitionKwStrength":{"$ref":"#/components/schemas/NumericOpportunityValue"},"numRelevantKeywords":{"$ref":"#/components/schemas/NumericOpportunityValue"},"numRelevantSearchVolume":{"type":"number"},"medianDaysListed":{"$ref":"#/components/schemas/NumericOpportunityValue"},"medianReviewCount":{"$ref":"#/components/schemas/NumericOpportunityValue"},"numLaunchKeywords":{"$ref":"#/components/schemas/NumericOpportunityValue"},"numLaunchSearchVolume":{"type":"number"}},"required":["competitionSvStrength","competitionKwStrength","numRelevantKeywords","numRelevantSearchVolume","medianDaysListed","medianReviewCount","numLaunchKeywords","numLaunchSearchVolume"]},"NumericCompetitorStrengthValue":{"type":"object","properties":{"value":{"type":"number","example":10.12},"competitorStrength":{"type":"string","enum":["none","veryStrongCompetitor","strongCompetitor","weakCompetitor","veryWeakCompetitor"],"example":"weakCompetitor"}},"required":["value","competitorStrength"]},"MklBenchmark":{"type":"object","properties":{"rating":{"type":"object","example":3.6},"reviewCount":{"type":"object","example":39},"listingCreationDate":{"$ref":"#/components/schemas/NumericCompetitorStrengthValue"},"price":{"type":"object","example":11.34},"sales":{"type":"object","example":376.5,"deprecated":true},"salesLowerRange":{"type":"object","example":11.34},"salesHigherRange":{"type":"object","example":376.5},"revenue":{"type":"object","example":4384.225,"deprecated":true},"revenueLowerRange":{"type":"object","example":4384.225},"revenueHigherRange":{"type":"object","example":4384.225},"outlierKeywords":{"type":"object","example":100},"outlierSV":{"type":"object","example":100},"kwRankedOnP1":{"type":"object","example":100},"kwRankedOnP1Percent":{"type":"object","example":100},"svRankedOnP1":{"type":"object","example":100},"svRankedOnP1Percent":{"type":"object","example":100},"kwRankedOnP1Evaluation":{"type":"object","example":"veryGood"},"svRankedOnP1Evaluation":{"type":"object","example":"veryGood"},"advertisedKws":{"type":"object","example":100},"advertisedKwsPercent":{"type":"object","example":100},"tosKwsAds":{"type":"object","example":100},"tosKwsAdsPercent":{"type":"object","example":100},"tosKwsAdsEvaluation":{"type":"object","example":"veryGood"},"tosSvAds":{"type":"object","example":100},"tosSvAdsPercent":{"type":"object","example":100},"tosSvAdsEvaluation":{"type":"object","example":"veryGood"},"numberOfVariations":{"type":"object","example":24}},"required":["rating","reviewCount","listingCreationDate","price","sales","salesLowerRange","salesHigherRange","revenue","revenueLowerRange","revenueHigherRange","outlierKeywords","outlierSV","kwRankedOnP1","kwRankedOnP1Percent","svRankedOnP1","svRankedOnP1Percent","kwRankedOnP1Evaluation","svRankedOnP1Evaluation","advertisedKws","advertisedKwsPercent","tosKwsAds","tosKwsAdsPercent","tosKwsAdsEvaluation","tosSvAds","tosSvAdsPercent","tosSvAdsEvaluation","numberOfVariations"]},"CompetitorsStrengthRanksValues":{"type":"object","properties":{"sellers":{"type":"number","example":2},"percentage":{"type":"number","example":0.6,"minimum":0,"maximum":1}},"required":["sellers","percentage"]},"CompetitorsStrengthRanks":{"type":"object","properties":{"veryStrongCompetitor":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"},"strongCompetitor":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"},"weakCompetitor":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"},"veryWeakCompetitor":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"},"none":{"$ref":"#/components/schemas/CompetitorsStrengthRanksValues"}},"required":["veryStrongCompetitor","strongCompetitor","weakCompetitor","veryWeakCompetitor","none"]},"CompetitorsStrength":{"type":"object","properties":{"searchVolume":{"$ref":"#/components/schemas/CompetitorsStrengthRanks"},"keywords":{"$ref":"#/components/schemas/CompetitorsStrengthRanks"}},"required":["searchVolume","keywords"]},"AsinCatalogInfo":{"type":"object","properties":{"asin":{"type":"string"},"sellerId":{"type":"string"},"marketplace":{"type":"string"}},"required":["asin","sellerId","marketplace"]},"CompetitorListingRankingJuice":{"type":"object","properties":{"value":{"type":"number","description":"Total Ranking Juice for the entire listing","example":300456}},"required":["value"]},"CompetitorListItem":{"type":"object","properties":{"numberOfActiveSellers":{"type":"object","description":"Number","example":1},"asin":{"type":"string","description":"ASIN","example":"B07VHN2VCR"},"brand":{"type":"object","description":"Brand","example":"COLORWORK"},"title":{"type":"string","description":"Title","example":"COLORWORK DIY Paint by Numbers"},"fulfillment":{"type":"string","description":"Fulfillment","example":"FBA","enum":["AMZ","FBA","FBM","MFN"]},"price":{"type":"object","description":"Price","example":25},"sales":{"type":"object","description":"Sales","example":429},"revenue":{"type":"object","description":"Revenue","example":5143.71},"bsr":{"type":"object","description":"BSR","example":25250},"rating":{"type":"object","description":"Rating","example":5},"reviewCount":{"type":"object","description":"Review Count","example":3},"imageUrl":{"type":"object","description":"Semicolon (;) separated Urls of the images of the product","example":"https://images-na.ssl-images-amazon.com/images/I/41TfNcpwXXL.jpg","format":"uri"},"sellerCountry":{"type":"string","default":"N/A"},"listingCreationDate":{"type":"number","example":1644339094484,"description":"When the listing was created, in milliseconds since epoch. Absent when Amazon publishes no date."},"listingCreationDateEvaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"veryGood","description":"How mature this listing is for the Niche, scored against its average-days-listed thresholds. Older listings score higher. Empty string when the listing is 0 days old."},"outlierKws":{"type":"integer","example":43},"outlierSV":{"type":"integer","example":66082},"numberOfVariations":{"type":"integer","example":24},"kwRankedOnP1":{"type":"number"},"kwRankedOnP1Percent":{"type":"number"},"kwRankedOnP1Evaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"svRankedOnP1":{"type":"number"},"svRankedOnP1Percent":{"type":"number"},"svRankedOnP1Evaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"advertisedKws":{"type":"number"},"advertisedKwsPercent":{"type":"number"},"advertisedKwsEvaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"tosKwsAds":{"type":"number"},"tosKwsAdsPercent":{"type":"number"},"tosKwsAdsEvaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"tosSvAds":{"type":"number"},"tosSvAdsPercent":{"type":"number"},"tosSvAdsEvaluation":{"type":"string","enum":["veryGood","good","bad","veryBad",""],"example":"good"},"asinCatalog":{"nullable":true,"type":"object","allOf":[{"$ref":"#/components/schemas/AsinCatalogInfo"}]},"category":{"type":"object","example":"Arts, Crafts & Sewing","nullable":true},"categoryTree":{"type":"object","example":"Pet Supplies > Dogs > Apparel & Accessories","nullable":true},"listingRankingJuice":{"description":"Total Ranking Juice of this Competitor listing. Use GET /v1/niches/{nicheId}/ranking-juices for the breakdown by title, bullets and description.","allOf":[{"$ref":"#/components/schemas/CompetitorListingRankingJuice"}]}},"required":["numberOfActiveSellers","asin","brand","title","fulfillment","price","sellerCountry","outlierKws","outlierSV","numberOfVariations","kwRankedOnP1","kwRankedOnP1Percent","svRankedOnP1","svRankedOnP1Percent","advertisedKws","advertisedKwsPercent","tosKwsAds","tosKwsAdsPercent","tosSvAds","tosSvAdsPercent","asinCatalog","category","categoryTree","listingRankingJuice"]},"GetCompetitorListResult":{"type":"object","properties":{"marketplace":{"type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"],"description":"The Amazon marketplace for this Niche"},"statistics":{"description":"Statistical analysis of the Master Keyword List including keyword count, search volume distribution, and ranking metrics","allOf":[{"$ref":"#/components/schemas/MklStatisticsData"}]},"opportunityEvaluation":{"description":"Evaluation scores across multiple criteria (competition strength, keyword relevance, market maturity) indicating the Niche opportunity level","allOf":[{"$ref":"#/components/schemas/OpportunityEvaluation"}]},"benchmark":{"description":"Benchmark median values for key metrics (ratings, reviews, price, sales, revenue, keyword rankings) across all Competitors","allOf":[{"$ref":"#/components/schemas/MklBenchmark"}]},"competitorsStrength":{"description":"Overall strength assessment of Competitors in the Niche","allOf":[{"$ref":"#/components/schemas/CompetitorsStrength"}]},"competitors":{"description":"List of Competitors with their business metrics including ASIN, title, BSR, sales, revenue, ratings, reviews, price, category, images, and ranking data","type":"array","items":{"$ref":"#/components/schemas/CompetitorListItem"}},"latestResearchDate":{"format":"date-time","type":"string","description":"The date when the Niche was last researched"}},"required":["marketplace","statistics","opportunityEvaluation","benchmark","competitorsStrength","competitors","latestResearchDate"]},"RankingJuiceProperty":{"type":"object","properties":{"rankingJuice":{"type":"number","description":"Ranking Juice value for this specific listing property","example":1144}},"required":["rankingJuice"]},"ListingRankingJuice":{"type":"object","properties":{"rankingJuice":{"type":"number","description":"Total Ranking Juice value for the entire listing","example":300456},"title":{"description":"Ranking Juice contribution from the product title","allOf":[{"$ref":"#/components/schemas/RankingJuiceProperty"}]},"bullets":{"description":"Ranking Juice contribution from the bullet points","allOf":[{"$ref":"#/components/schemas/RankingJuiceProperty"}]},"description":{"description":"Ranking Juice contribution from the product description","allOf":[{"$ref":"#/components/schemas/RankingJuiceProperty"}]}},"required":["rankingJuice","title","bullets","description"]},"CompetitorRankingJuice":{"type":"object","properties":{"asin":{"type":"string","description":"ASIN of the Competitor product","example":"B00JXQQNC6"},"listing":{"description":"Ranking Juice for this Competitor's listing","allOf":[{"$ref":"#/components/schemas/ListingRankingJuice"}]}},"required":["asin","listing"]},"NicheRankingJuices":{"type":"object","properties":{"currentListing":{"description":"Ranking Juice for the current listing","allOf":[{"$ref":"#/components/schemas/ListingRankingJuice"}]},"optimizedListing":{"description":"Ranking Juice for the optimized listing using keyword staffing method to achieve maximum potential","allOf":[{"$ref":"#/components/schemas/ListingRankingJuice"}]},"competitors":{"description":"List of Competitors with their Listing Ranking Juices","type":"array","items":{"$ref":"#/components/schemas/CompetitorRankingJuice"}},"latestResearchDate":{"format":"date-time","type":"string","description":"The date when the Niche was last researched"}},"required":["currentListing","optimizedListing","competitors","latestResearchDate"]},"CombineKeywordResponseDto":{"type":"object","properties":{"keyword":{"type":"string","description":"Original keyword"},"searchVolume":{"type":"number","description":"Search Volume of Original Keyword"},"normalizedKeyword":{"type":"string","description":"Normalized Keyword, removed stop word from Original Keyword"},"normalizedSearchVolume":{"type":"number","description":"Search Volume of Normalized Keyword"},"relevancy":{"type":"number"},"cpr8dayGiveAways":{"type":"object","description":"is an estimation of the total units you would need to give away over an 8-day period to rank on page 1"},"competingProducts":{"type":"object"},"numberOfexacts":{"type":"number","description":"Give us the number of EXACTs in competitors title"},"rankingJuice":{"type":"number"}},"required":["keyword","searchVolume","normalizedKeyword","normalizedSearchVolume","relevancy","cpr8dayGiveAways","competingProducts","numberOfexacts","rankingJuice"]},"ConsolidatedResponseDto":{"type":"object","properties":{"normalizedKeyword":{"type":"string","description":"Normalized Keyword, removed stop words from Original Keyword"},"consolidatedSearchVolume":{"type":"number","description":"Addition of Original Keyword or Keywords Search Volume"}},"required":["normalizedKeyword","consolidatedSearchVolume"]},"RootsTableItem":{"type":"object","properties":{"root":{"type":"string","example":"dog","description":"Roots are the keyword or the group of keywords that are part of the original keyword"},"frequency":{"type":"number","example":51,"description":"Count of Root in the whole list of original keywords"},"broadSearchVolume":{"type":"number","example":77188,"description":"Sum of all Original Keyword Search Volume where the Root keyword is present"},"broadSearchVolumeRatio":{"type":"number","format":"float","example":0.700931693939449,"minimum":0,"maximum":1,"description":"Divide the broadSearchVolume by maxBroadSearchVolume to get this ratio"}},"required":["root","frequency","broadSearchVolume","broadSearchVolumeRatio"]},"ExternalRootResponseDto":{"type":"object","properties":{"keywords":{"type":"array","items":{"$ref":"#/components/schemas/CombineKeywordResponseDto"}},"consolidatedKeywords":{"type":"array","items":{"$ref":"#/components/schemas/ConsolidatedResponseDto"}},"roots":{"type":"array","items":{"$ref":"#/components/schemas/RootsTableItem"}},"normalizedRoots":{"type":"array","items":{"$ref":"#/components/schemas/RootsTableItem"}},"latestResearchDate":{"format":"date-time","type":"string","description":"last successful research date for the niche"}},"required":["keywords","consolidatedKeywords","roots","normalizedRoots","latestResearchDate"]},"AiCopyWriterInputDto":{"type":"object","properties":{"prompt":{"type":"string","example":"cosmo|ranking-juice|nlp|cosmo-rufus","enum":["cosmo","ranking-juice","nlp","cosmo-rufus"]},"listingToInclude":{"type":"object","example":"{ \"title\": \"Title Example\", \"description\": \"Description Example\". \"bullets\":\"bullet1\nbullet2\n\"}"}},"required":["prompt","listingToInclude"]},"AiListingGenerationGeneratingResponseDto":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique identifier of the generation attempt","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"status":{"type":"string","enum":["generating","complete","failed"],"description":"Current status: generating (in progress), complete (result available), or failed (generation errored)","example":"generating"}},"required":["generationId","status"]},"AiListingGenerationResultDto":{"type":"object","properties":{"rankingJuice":{"type":"object","description":"Ranking Juice metrics for the generated listing (value + per-field contribution).","additionalProperties":true},"title":{"type":"string","description":"Generated product title","example":"Stainless Steel Water Bottle 32oz"},"itemHighlights":{"type":"string","description":"Item highlights, if generated","example":""},"bullets":{"description":"Generated bullet points","type":"array","items":{"type":"string"}},"description":{"type":"string","description":"Generated product description"},"methodology_breakdown":{"type":"object","description":"Methodology breakdown of the generation, when produced by the model","additionalProperties":true}},"required":["rankingJuice","title","itemHighlights","bullets","description"]},"AiListingGenerationCompleteResponseDto":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique identifier of the generation attempt","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"status":{"type":"string","enum":["generating","complete","failed"],"description":"Current status: generating (in progress), complete (result available), or failed (generation errored)","example":"generating"},"result":{"description":"The generated listing","allOf":[{"$ref":"#/components/schemas/AiListingGenerationResultDto"}]}},"required":["generationId","status","result"]},"AiListingGenerationFailedResponseDto":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique identifier of the generation attempt","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"status":{"type":"string","enum":["generating","complete","failed"],"description":"Current status: generating (in progress), complete (result available), or failed (generation errored)","example":"generating"},"error":{"type":"string","description":"Human-readable error describing why the generation failed"}},"required":["generationId","status","error"]},"ExternalRankRadarStatus":{"type":"string","enum":["ACTIVE","PAUSED","ARCHIVED","ALL"],"description":"Uses the same vocabulary as the status query parameter, except the filter-only ALL"},"KRTAsinResponseDto":{"type":"object","properties":{"id":{"type":"string"},"krtId":{"type":"string"},"asin":{"type":"string"}},"required":["id","krtId","asin"]},"ExternalRankRadarResponseDto":{"type":"object","properties":{"id":{"type":"string"},"status":{"description":"Uses the same vocabulary as the status query parameter, except the filter-only ALL","example":"ACTIVE","allOf":[{"$ref":"#/components/schemas/ExternalRankRadarStatus"}]},"asin":{"$ref":"#/components/schemas/KRTAsinResponseDto"},"marketplace":{"type":"string"},"keywordCount":{"type":"number"},"title":{"type":"string"},"imageUrl":{"type":"string"},"top10KW":{"type":"object"},"top10SV":{"type":"object"},"top50KW":{"type":"object"},"top50SV":{"type":"object"}},"required":["id","status","asin","marketplace","keywordCount","title","imageUrl","top10KW","top10SV","top50KW","top50SV"]},"ExternalRankRadarListResponseDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/ExternalRankRadarResponseDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"ExternalKrtAsinRankDto":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO format"},"organicRank":{"type":"object","example":1},"impressionRank":{"type":"object","example":1}},"required":["date","organicRank","impressionRank"]},"KrtHighlightDto":{"type":"object","properties":{"id":{"type":"string","description":"Highlight ID"},"krtId":{"type":"string","description":"KRT Id related to highlight"},"krtKeywordId":{"type":"string","description":"krtKeywordId related to highlight"},"title":{"type":"string","description":"Title of Highlight"},"description":{"type":"object","description":"Description of Highlight","example":"something great"},"color":{"type":"object","description":"Color of Highlight","example":"green"},"type":{"type":"string","description":"Type of Highlight"},"startAt":{"type":"object","description":"Start Date of Highlight","example":"2024-07-12"},"endAt":{"type":"object","description":"End Date of Highlight","example":"2024-07-12"},"searchVolume":{"type":"number","description":"Search Volume of related keywords"},"svShare":{"type":"number","description":"Search Volume share of related keywords"},"keywords":{"description":"Related keywords","type":"array","items":{"type":"string"}}},"required":["id","krtId","krtKeywordId","title","description","color","type","startAt","endAt","searchVolume","svShare","keywords"]},"KrtKeywordResponseDto":{"type":"object","properties":{"id":{"type":"string"},"keyword":{"type":"string","example":"keyword"},"searchVolume":{"type":"object","example":123},"ranks":{"type":"array","items":{"$ref":"#/components/schemas/ExternalKrtAsinRankDto"}},"highlights":{"type":"array","items":{"$ref":"#/components/schemas/KrtHighlightDto"}}},"required":["id","keyword","searchVolume","ranks","highlights"]},"KrtKeywordListResponseDto":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/KrtKeywordResponseDto"}}},"required":["data"]},"AddSearchTermsRequestDto":{"type":"object","properties":{}},"ExternalAddSearchTermsResponseDto":{"type":"object","properties":{"originBreakdown":{"type":"object","readOnly":true,"example":{"manual":["puppy","outfits"],"suggestions":["dog raincoat"],"outliers":["dog swig","dog swim"],"residues":["mini cowboy","dog umbrella"],"paused":["sunglasses"]}},"keywordToRankRadarKeywordIdMap":{"type":"object","readOnly":true,"example":{"sunglasses":"rank-radar-keyword-id"}}},"required":["originBreakdown","keywordToRankRadarKeywordIdMap"]},"RankRadarSearchTermIdsDto":{"type":"object","properties":{"rankRadarKeywordIds":{"description":"The Rank Radar keyword identifiers to update. These are the `id` values returned by GET /v1/niches/rank-radars/:rankRadarId and the `keywordToRankRadarKeywordIdMap` values returned by the add search terms endpoint.","type":"array","items":{"type":"string"}}},"required":["rankRadarKeywordIds"]},"CreateNicheDiveRequestDto":{"type":"object","properties":{"marketplace":{"type":"string","description":"The Amazon marketplace where the seed product is listed","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"asin":{"type":"string","description":"The seed ASIN to start the Niche Dive analysis from. The system will identify related Competitors and build the Niche around this product.","example":"B08N5WRWNW"},"numberOfCompetitors":{"type":"number","description":"Number of Competitors to include in the Niche analysis. More Competitors provide deeper insights but consume more Dive tokens. Minimum is 2.","example":5,"minimum":2}},"required":["marketplace","asin","numberOfCompetitors"]},"CreateNicheDiveSuccessResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier for the Dive. Use this ID to check the Dive status and retrieve results when complete.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the Niche Dive analysis in ISO 8601 format","example":"2024-04-01T00:00:00Z"}},"required":["diveId","estimatedCompletionDate"]},"CreateNicheDiveErrorResponseDto":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message describing why the Dive creation failed","example":"Invalid marketplace"},"errorId":{"type":"string","description":"Unique identifier for this error instance, useful for troubleshooting and support","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"}},"required":["error","errorId"]},"CreateNicheDiveWithCompetitorsRequestDto":{"type":"object","properties":{"marketplace":{"type":"string","description":"The Amazon marketplace where the given ASINs are listed","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"asins":{"description":"The explicit list of Competitor ASINs to build the Niche from. No automatic Competitor discovery is performed — the Niche Dive runs on exactly these ASINs. Dive tokens are consumed for each one.","example":["B08N5WRWNW","B09617YV4C"],"minItems":2,"maxItems":200,"uniqueItems":true,"type":"array","items":{"type":"string"}}},"required":["marketplace","asins"]},"CreateNicheDiveWithCompetitorsResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier for the Dive. Use this ID to check the Dive status and retrieve results when complete.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the Niche Dive analysis in ISO 8601 format","example":"2024-04-01T00:00:00Z"}},"required":["diveId","estimatedCompletionDate"]},"RediveNicheResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier for the re-dive. Poll `GET /v1/niches/dives/{diveId}` with it to track progress.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the re-dive in ISO 8601 format","example":"2026-08-01T00:00:00Z"}},"required":["diveId","estimatedCompletionDate"]},"RediveNicheRequestDto":{"type":"object","properties":{"mode":{"type":"string","description":"How to pick the Competitors for the refreshed Dive. `same_competitors` re-dives the Niche's current Competitor set and takes no other field. `discover` searches for a fresh Competitor set.","enum":["same_competitors","discover"],"example":"discover"},"numberOfCompetitors":{"type":"integer","description":"Total number of ASINs the refreshed Dive should contain, including `lockedAsins`. Required in `discover` mode and rejected in `same_competitors` mode. Dive tokens are consumed for each ASIN.","example":12,"minimum":2},"heroAsin":{"type":"string","description":"Seed product the Competitor discovery starts from. Defaults to the Niche Competitor with the highest sales, preferring one that belongs to one of your connected seller accounts. `discover` mode only.","example":"B08N5WRWNW"},"lockedAsins":{"description":"ASINs that must be kept in the refreshed Competitor set regardless of what discovery finds. `discover` mode only.","example":["B08N5WRWNW","B09617YV4C"],"uniqueItems":true,"maxItems":200,"type":"array","items":{"type":"string"}},"excludedAsins":{"description":"ASINs that discovery must never select. `discover` mode only.","example":["B07XHRSRZ2"],"uniqueItems":true,"maxItems":200,"type":"array","items":{"type":"string"}}},"required":["mode"]},"CreateRankRadarRequestDto":{"type":"object","properties":{"asin":{"type":"string","description":"The ASIN of the product to track keyword rankings for","example":"B08N5WRWNW"},"numberOfKeywords":{"type":"number","description":"Number of keywords to track in the Rank Radar. More keywords provide comprehensive tracking but consume more Search Term tokens. Minimum is 1.","example":5,"minimum":1},"nicheId":{"type":"string","description":"The Niche identifier that this Rank Radar is associated with","example":"xdGJ6gy7"}},"required":["asin","numberOfKeywords","nicheId"]},"CreateRankRadarSuccessResponseDto":{"type":"object","properties":{"rankRadarId":{"type":"string","description":"Unique identifier for the created Rank Radar. Use this ID to retrieve keyword ranking data and track performance over time.","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"}},"required":["rankRadarId"]},"CreateRankRadarErrorResponseDto":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable error message describing why the Rank Radar creation failed","example":"Invalid marketplace"},"errorId":{"type":"string","description":"Unique identifier for this error instance, useful for troubleshooting and support","example":"b3e1f2c4-7e6a-4d2a-9f1e-123456789abc"}},"required":["error","errorId"]},"InventoryByFcItemDto":{"type":"object","properties":{"fc":{"type":"string","description":"Fulfillment center code"},"state":{"type":"string","description":"State or region code where the fulfillment center is located, when known"},"availableStock":{"type":"number","description":"Units of sellable inventory currently at this fulfillment center. May be `0` when stock has run out at an FC that was previously holding this ASIN — zero-balance FCs are intentionally included."},"availableStockPercentage":{"type":"number","description":"Share of this ASIN's total sellable inventory currently at this fulfillment center, expressed as a decimal fraction between 0 and 1 (e.g. `0.075` means 7.5%). NOT a 0-to-100 percentage despite the field name."}},"required":["fc","availableStock","availableStockPercentage"]},"InventoryByFcResponseDto":{"type":"object","properties":{"asin":{"type":"string"},"sellerId":{"type":"string"},"marketplace":{"type":"string","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"lastUpdatedAt":{"type":"string","description":"Timestamp of the most recent successful inventory distribution ingestion for this connection. Null if no successful ingestion in the last 30 days.","nullable":true,"format":"date-time"},"totalSellableUnits":{"type":"number","description":"Total sellable units for the ASIN across all fulfillment centers"},"distribution":{"description":"Per-fulfillment-center breakdown of sellable inventory. Includes every fulfillment center currently assigned to this ASIN, including those with `availableStock: 0`. Inbound, reserved, and unsellable units are not currently broken down by fulfillment center.","type":"array","items":{"$ref":"#/components/schemas/InventoryByFcItemDto"}}},"required":["asin","sellerId","marketplace","totalSellableUnits","distribution"]},"IndexingIssueAlertDto":{"type":"object","properties":{"id":{"type":"number","example":12345,"description":"Unique alert identifier"},"asin":{"type":"string","example":"B0ABCDEFGH","description":"The ASIN that is no longer indexed for its tracked keywords"},"title":{"type":"object","example":"Wireless Earbuds, Bluetooth 5.3","nullable":true},"imageUrl":{"type":"object","example":"https://m.media-amazon.com/images/I/abc.jpg","nullable":true},"isParent":{"type":"boolean","example":false,"description":"True when the ASIN is a parent of a variation family"},"sellerId":{"type":"string","example":"A1B2C3D4E5"},"marketplace":{"type":"string","example":"com"},"lastAlertedAt":{"format":"date-time","type":"string","example":"2024-06-01T12:00:00Z","description":"When the alert was surfaced (its creation time). Each time an alert re-fires, a fresh card is created, so this always reflects the most recent surfacing."},"resolvedAt":{"type":"object","example":null,"nullable":true,"description":"When the alert was resolved, or null if still active"}},"required":["id","asin","title","imageUrl","isParent","sellerId","marketplace","lastAlertedAt","resolvedAt"]},"IndexingIssueAlertListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/IndexingIssueAlertDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"BlindSpendSearchTermDto":{"type":"object","properties":{"term":{"type":"string","example":"wireless earbuds bluetooth","description":"The customer search term that wasted spend"},"spend":{"type":"object","example":123.45,"nullable":true,"description":"Ad spend on this search term"},"sales":{"type":"object","example":0,"nullable":true,"description":"Attributed sales from this search term"},"clicks":{"type":"object","example":15,"nullable":true},"cvr":{"type":"object","example":0,"nullable":true,"description":"Conversion rate (0–1)"},"impressions":{"type":"object","example":1500,"nullable":true}},"required":["term","spend","sales","clicks","cvr","impressions"]},"BlindSpendAlertDto":{"type":"object","properties":{"id":{"type":"number","example":12345,"description":"Unique alert identifier"},"asin":{"type":"object","example":"B0ABCDEFGH","nullable":true},"title":{"type":"object","example":"Wireless Earbuds, Bluetooth 5.3","nullable":true},"imageUrl":{"type":"object","example":"https://m.media-amazon.com/images/I/abc.jpg","nullable":true},"sellerId":{"type":"string","example":"A1B2C3D4E5"},"marketplace":{"type":"string","example":"com"},"lastAlertedAt":{"format":"date-time","type":"string","example":"2024-06-01T12:00:00Z","description":"When the alert was surfaced (its creation time). Each time an alert re-fires, a fresh card is created, so this always reflects the most recent surfacing."},"resolvedAt":{"type":"object","example":null,"nullable":true,"description":"When the alert was resolved, or null if still active"},"wastedSpend":{"type":"number","example":246.9,"description":"Total ad spend across the unresolved wasted-spend search terms"},"totalKeywordCount":{"type":"number","example":8,"description":"Total number of search terms in this alert"},"unresolvedKeywordCount":{"type":"number","example":5,"description":"Number of search terms still unresolved"},"searchTerms":{"description":"The unresolved wasted-spend search terms","type":"array","items":{"$ref":"#/components/schemas/BlindSpendSearchTermDto"}}},"required":["id","asin","title","imageUrl","sellerId","marketplace","lastAlertedAt","resolvedAt","wastedSpend","totalKeywordCount","unresolvedKeywordCount","searchTerms"]},"BlindSpendAlertListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/BlindSpendAlertDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"SellerProfileDto":{"type":"object","properties":{"sellerId":{"type":"string","example":"A1B2C3D4E5","description":"Amazon seller profile identifier"},"sellerName":{"type":"string","example":"My Brand Store","description":"Display name of the seller profile"},"marketplace":{"type":"string","example":"com","description":"Amazon marketplace domain (e.g. com, co.uk, de, ca)"},"hasAdApi":{"type":"boolean","example":true,"description":"Whether this seller profile has Ad API credentials connected"},"createdAt":{"format":"date-time","type":"string","description":"When the seller profile was connected to DataDive"}},"required":["sellerId","sellerName","marketplace","hasAdApi","createdAt"]},"SellerProfileListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/SellerProfileDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"CatalogAsinDto":{"type":"object","properties":{"asin":{"type":"string","example":"B0ABCDEFGH","description":"Amazon Standard Identification Number"},"title":{"type":"string","example":"Wireless Earbuds, Bluetooth 5.3","description":"Product title"},"parentAsin":{"type":"object","example":"B0AAAA0000","nullable":true,"description":"Parent ASIN if this is a child variation"},"brand":{"type":"object","example":"Anker","nullable":true,"description":"Product brand"},"status":{"type":"string","example":"Active","description":"Product listing status"},"imageUrl":{"type":"object","example":"https://m.media-amazon.com/images/I/abc.jpg","nullable":true,"description":"Main product image URL"},"hasVariations":{"type":"object","example":true,"nullable":true,"description":"Whether the product has variations"}},"required":["asin","title","parentAsin","brand","status","imageUrl","hasVariations"]},"CatalogAsinListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/CatalogAsinDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"ListingChangeCorrelationDto":{"type":"object","properties":{"status":{"type":"string","enum":["PENDING","AVAILABLE","UNAVAILABLE_NO_ACTIVE_RANK_RADAR","UNAVAILABLE"],"description":"Status of correlation data availability"},"message":{"type":"object","nullable":true,"description":"Human-readable status message"},"salesCvr":{"type":"object","nullable":true,"description":"Sales conversion rate before/after the change","example":{"before":0.12,"after":0.15}},"top10SearchTerms":{"type":"object","nullable":true,"description":"Count of tracked keywords in top 10 organic rank before/after","example":{"before":5,"after":8}},"top50SearchTerms":{"type":"object","nullable":true,"description":"Count of tracked keywords in top 50 organic rank before/after","example":{"before":12,"after":18}}},"required":["status","message","salesCvr","top10SearchTerms","top50SearchTerms"]},"ListingChangeExternalItemDto":{"type":"object","properties":{"asin":{"type":"string","example":"B0ABCDEFGH"},"title":{"type":"object","example":"Wireless Earbuds, Bluetooth 5.3","nullable":true},"imageUrl":{"type":"object","example":"https://m.media-amazon.com/images/I/abc.jpg","nullable":true},"date":{"format":"date-time","type":"string","description":"When the change was first detected"},"type":{"type":"string","enum":["Price","Content","Image"]},"contentType":{"type":"object","description":"Content sub-type (only for Content changes)","nullable":true,"example":"Title"},"description":{"type":"string","description":"Human-readable description of the change"},"previousValue":{"type":"object","nullable":true,"description":"Previous value (formatted)"},"newValue":{"type":"object","nullable":true,"description":"New value (formatted)"},"possibleAiRewrite":{"type":"object","nullable":true,"description":"True when this title change matches the pattern of an Amazon-initiated AI rewrite for 75-char compliance"},"flagNote":{"type":"object","nullable":true,"description":"Note explaining the flag, when present"},"correlation":{"nullable":true,"description":"Metric correlation data","type":"object","allOf":[{"$ref":"#/components/schemas/ListingChangeCorrelationDto"}]}},"required":["asin","title","imageUrl","date","type","contentType","description","previousValue","newValue","possibleAiRewrite","flagNote","correlation"]},"ListingChangesExternalListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/ListingChangeExternalItemDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"ExternalQuotaFeatureDto":{"type":"object","properties":{"used":{"type":"object","example":42,"nullable":true,"description":"Current usage count"},"capacity":{"type":"object","example":250,"nullable":true,"description":"Quota capacity"}},"required":["used","capacity"]},"ExternalQuotaFeaturesDto":{"type":"object","properties":{"DIVED_ASINS":{"description":"Dive token usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"RANK_RADAR_KEYWORDS":{"description":"Rank Radar tracked keywords usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"PRODUCT_BRIEF_ASINS":{"description":"Product brief usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"AI_COPYWRITER_PROMPTS":{"description":"AI Copywriter prompt usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]},"INDEXING_DIAGNOSIS":{"description":"Indexing diagnosis usage","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeatureDto"}]}},"required":["DIVED_ASINS","RANK_RADAR_KEYWORDS","PRODUCT_BRIEF_ASINS","AI_COPYWRITER_PROMPTS","INDEXING_DIAGNOSIS"]},"ExternalQuotaResponseDto":{"type":"object","properties":{"nextRefreshDate":{"type":"object","example":"2024-04-15T00:00:00.000Z","nullable":true,"description":"ISO 8601 timestamp of next quota reset"},"features":{"description":"Usage info per billable feature","allOf":[{"$ref":"#/components/schemas/ExternalQuotaFeaturesDto"}]}},"required":["nextRefreshDate","features"]},"ExternalUsageLogDto":{"type":"object","properties":{"name":{"type":"string","nullable":true,"example":"John Doe","description":"Name of the user who performed the action"},"email":{"type":"string","example":"johndoe@example.com","description":"Email of the user who performed the action"},"qty":{"type":"number","example":1,"description":"Number of tokens consumed"},"type":{"type":"string","enum":["DIVED_ASINS","PRODUCT_BRIEF_ASINS","AI_COPYWRITER_PROMPTS","RANK_RADAR_KEYWORDS","INDEXING_DIAGNOSIS"],"description":"The billable feature type"},"action":{"type":"string","enum":["RANK_RADAR_PAUSE","RANK_RADAR_CREATE","RANK_RADAR_UPDATE","RANK_RADAR_RESUMED","RANK_RADAR_ARCHIVE","RANK_RADAR_KEYWORD_PAUSE","RANK_RADAR_KEYWORD_UNPAUSE","DIVE_SCHEDULED","DIVE_DIVEBOX","SOLO_REVERSE_ASIN","REFUND_FAILED_SOLO_REVERSE_ASIN","REFUND_FAILED_DIVE","ANALYZE_COMPETITORS","ANALYZE_COMPETITORS_FAILED","INDEXING_DIAGNOSIS","INDEXING_DIAGNOSIS_FAILED","AI_GENERATE_DESCRIPTION","AI_GENERATE_BULLETS","AI_GENERATE_ITEM_HIGHLIGHTS","AI_GENERATE_LISTING","MANUAL_KEYWORD_ADD","MANUAL_KEYWORD_REMOVE"],"nullable":true,"description":"Specific action performed"},"nicheId":{"type":"string","nullable":true,"example":"boGkBnlEx4","description":"Associated Niche identifier"},"nicheName":{"type":"string","nullable":true,"example":"dog hat","description":"Associated Niche name"},"rankRadarId":{"type":"string","nullable":true,"example":"5231a9af-82f2-4c87-9ed4-cef0447cff1e","description":"Associated Rank Radar identifier"},"date":{"type":"string","format":"date-time","description":"When the usage was recorded"}},"required":["name","email","qty","type","action","nicheId","nicheName","rankRadarId","date"]},"ExternalUsageLogListDto":{"type":"object","properties":{"currentPage":{"type":"number","example":1},"pageSize":{"type":"number","example":20,"description":"Number of items per page"},"hasNext":{"type":"boolean","example":false,"description":"True when there is a next page. Otherwise, false"},"hasPrev":{"type":"boolean","example":false,"description":"True when there is a previous page. Otherwise, false"},"lastPage":{"type":"number","example":1,"description":"Last page or total page count"},"total":{"type":"number","example":1,"description":"Total number of items"},"data":{"description":"List of items","type":"array","items":{"$ref":"#/components/schemas/ExternalUsageLogDto"}}},"required":["currentPage","pageSize","hasNext","hasPrev","lastPage","total","data"]},"NicheDiveStatusSuccessResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier of the Dive process","example":"xxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","enum":["in_progress","error","success"],"description":"Current status of the Dive: in_progress (analysis ongoing), success (completed successfully), or error (failed)","example":"in_progress"},"nicheId":{"type":"string","description":"Unique identifier of the created Niche. Use this to access the Niche research data via other endpoints.","example":"HdNCcryRCs"},"tokensUsed":{"type":"number","description":"Number of Dive tokens consumed by this Niche analysis","example":30},"tokensLeft":{"type":"number","description":"Remaining Dive tokens available for future dives","example":1000}},"required":["diveId","status","nicheId","tokensUsed","tokensLeft"]},"NicheDiveStatusInProgressResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier of the Dive process","example":"xxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","enum":["in_progress","error","success"],"description":"Current status of the Dive: in_progress (analysis ongoing), success (completed successfully), or error (failed)","example":"in_progress"},"estimatedCompletionDate":{"type":"string","description":"Estimated completion timestamp for the Niche Dive in ISO 8601 format","example":"2024-04-01T00:00:00Z"}},"required":["diveId","status","estimatedCompletionDate"]},"NicheDiveStatusErrorResponseDto":{"type":"object","properties":{"diveId":{"type":"string","description":"Unique identifier of the Dive process","example":"xxxxxxxxxxxxxxxxxxxxxxxxxx"},"status":{"type":"string","enum":["in_progress","error","success"],"description":"Current status of the Dive: in_progress (analysis ongoing), success (completed successfully), or error (failed)","example":"in_progress"},"error":{"type":"string","description":"Error message describing what went wrong during the Dive analysis","example":"Some error message"}},"required":["diveId","status","error"]},"PpcAlertSearchTermDto":{"type":"object","properties":{"search_term":{"type":"string","example":"yoga mat thick"},"label":{"type":"string","example":"blindspend"},"spend":{"type":"object","example":45.5},"sales":{"type":"object","example":0},"clicks":{"type":"object","example":30},"impressions":{"type":"object","example":500},"cvr":{"type":"object","example":0},"roas":{"type":"object","example":0},"competitor_cvr":{"type":"object","example":0.08},"search_volume":{"type":"object","example":12000},"impression_rank":{"type":"object","example":5},"impression_share":{"type":"object","example":0.12}},"required":["search_term","label"]},"PpcAlertDataDto":{"type":"object","properties":{"seller_id":{"type":"string","example":"A1B2C3D4E5F6G7"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"tracked_asin":{"type":"string","example":"B0EXAMPLE1"},"tracked_asin_title":{"type":"object","example":"Yoga Mat - Extra Thick"},"niche_label":{"type":"string","example":"Yoga Mats"},"rank_radar_id":{"type":"string","example":"11111111-2222-4333-aaaa-bbbbbbbbbbbb"},"return_url":{"type":"string","example":"https://2.datadive.tools/alerts"},"search_terms":{"type":"array","items":{"$ref":"#/components/schemas/PpcAlertSearchTermDto"}},"search_term_count":{"type":"number","example":2},"total_spend":{"type":"number","example":67.5}},"required":["seller_id","marketplace","tracked_asin","niche_label","rank_radar_id","return_url","search_terms","search_term_count","total_spend"]},"PotentialWastedSpendPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.potential_wasted_spend"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/PpcAlertDataDto"}},"required":["id","type","created_at","organization_id","data"]},"GrowthOpportunityPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.growth_opportunity"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/PpcAlertDataDto"}},"required":["id","type","created_at","organization_id","data"]},"ProfitableOutOfBudgetTargetDataDto":{"type":"object","properties":{"targeting":{"type":"string","example":"yoga mat thick"},"keyword":{"type":"object","example":"yoga mat thick"},"match_type":{"type":"object","example":"EXACT"},"spend":{"type":"object","example":80},"sales":{"type":"object","example":440},"roas":{"type":"object","example":5.5}},"required":["targeting"]},"ProfitableOutOfBudgetDataDto":{"type":"object","properties":{"seller_id":{"type":"string","example":"A1B2C3D4E5F6G7"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"tracked_asin":{"type":"string","example":"B0EXAMPLE1"},"tracked_asin_title":{"type":"object","example":"Yoga Mat - Extra Thick"},"niche_label":{"type":"string","example":"Yoga Mats"},"rank_radar_id":{"type":"string","example":"11111111-2222-4333-aaaa-bbbbbbbbbbbb"},"return_url":{"type":"string","example":"https://2.datadive.tools/alerts"},"campaign_id":{"type":"string","example":"123456789012345"},"campaign_name":{"type":"object","example":"Yoga Mats | SP | Auto"},"recurring_after_budget_increase":{"type":"boolean","example":false},"previous_budget_increased_at":{"type":"object","example":"2026-05-01T00:00:00.000Z"},"roas":{"type":"object","example":5.2},"budget":{"type":"object","example":50},"spend":{"type":"object","example":120.5},"sales":{"type":"object","example":626.6},"out_of_budget_days":{"type":"number","example":3},"out_of_budget_window_days":{"type":"number","example":3},"targets":{"type":"array","items":{"$ref":"#/components/schemas/ProfitableOutOfBudgetTargetDataDto"}},"target_count":{"type":"number","example":2}},"required":["seller_id","marketplace","tracked_asin","niche_label","rank_radar_id","return_url","campaign_id","recurring_after_budget_increase","out_of_budget_days","out_of_budget_window_days","targets","target_count"]},"ProfitableOutOfBudgetPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.profitable_out_of_budget"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/ProfitableOutOfBudgetDataDto"}},"required":["id","type","created_at","organization_id","data"]},"IndexingIssueDataDto":{"type":"object","properties":{"seller_id":{"type":"string","example":"A1B2C3D4E5F6G7"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"tracked_asin":{"type":"string","example":"B0EXAMPLE1"},"tracked_asin_title":{"type":"object","example":"Yoga Mat - Extra Thick"},"niche_label":{"type":"string","example":"Yoga Mats"},"rank_radar_id":{"type":"string","example":"11111111-2222-4333-aaaa-bbbbbbbbbbbb"},"return_url":{"type":"string","example":"https://2.datadive.tools/alerts"},"is_parent":{"type":"boolean","example":true}},"required":["seller_id","marketplace","tracked_asin","niche_label","rank_radar_id","return_url","is_parent"]},"IndexingIssuePayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.indexing_issue"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/IndexingIssueDataDto"}},"required":["id","type","created_at","organization_id","data"]},"CompetitorPromotionDataDto":{"type":"object","properties":{"asin":{"type":"string","example":"B0COMPETITOR"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"competitor_title":{"type":"object","example":"Premium Yoga Mat - Extra Thick"},"old_price":{"type":"number","example":2999},"new_price":{"type":"number","example":1999},"change_percentage":{"type":"number","example":-33.3},"deal_type":{"type":"object","example":"LIMITED_TIME_DEAL"},"access_type":{"type":"object","example":"PRIME_EXCLUSIVE"},"promotion_starts_at":{"type":"object","example":"2026-06-01T00:00:00.000Z"},"promotion_ends_at":{"type":"object","example":"2026-06-07T23:59:59.000Z"}},"required":["asin","marketplace","old_price","new_price","change_percentage"]},"CompetitorPromotionPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.competitor_promotion"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/CompetitorPromotionDataDto"}},"required":["id","type","created_at","organization_id","data"]},"CompetitorPriceDropDataDto":{"type":"object","properties":{"asin":{"type":"string","example":"B0COMPETITOR"},"marketplace":{"type":"string","example":"com","enum":["com","ca","co.uk","com.mx","in","fr","de","es","it","co.jp"]},"competitor_title":{"type":"object","example":"Premium Yoga Mat - Extra Thick"},"old_price":{"type":"number","example":2999},"new_price":{"type":"number","example":2399},"change_percentage":{"type":"number","example":-20}},"required":["asin","marketplace","old_price","new_price","change_percentage"]},"CompetitorPriceDropPayloadDto":{"type":"object","properties":{"id":{"type":"string","example":"evt_123e4567-e89b-12d3-a456-426614174000"},"type":{"type":"string","example":"alert.competitor_price_drop"},"created_at":{"type":"string","example":"2026-06-01T12:00:00.000Z"},"organization_id":{"type":"number","example":100},"data":{"$ref":"#/components/schemas/CompetitorPriceDropDataDto"}},"required":["id","type","created_at","organization_id","data"]}}},"webhooks":{"alert.potential_wasted_spend":{"post":{"summary":"Potential Wasted Spend","description":"Spending on a keyword you should stop bidding on","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PotentialWastedSpendPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.growth_opportunity":{"post":{"summary":"Growth Opportunity","description":"Spending on a keyword you should start tracking","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GrowthOpportunityPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.profitable_out_of_budget":{"post":{"summary":"Profitable Campaign Out of Budget","description":"A profitable campaign repeatedly ran out of budget","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfitableOutOfBudgetPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.indexing_issue":{"post":{"summary":"Indexing Issue","description":"ASIN not indexed for a keyword","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IndexingIssuePayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.competitor_promotion":{"post":{"summary":"Competitor Promotion","description":"Competitor promotion detected","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorPromotionPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}},"alert.competitor_price_drop":{"post":{"summary":"Competitor Price Drop","description":"Competitor price drop detected","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitorPriceDropPayloadDto"}}}},"responses":{"2xx":{"description":"Acknowledge receipt."},"Any other response code":{"description":"Indicates a failure to receive the webhook. Data Dive will retry according to our retry policy."}}}}}}