{"openapi":"3.1.0","info":{"title":"sigpik Developer API","version":"1.0.0","description":"Promotion investigations, product rankings, keyword traffic intelligence, and independent signal notifications. Manage credentials and webhook delivery in Dashboard."},"servers":[{"url":"https://sigpik.com/api/v1"}],"tags":[{"name":"Core Intelligence"},{"name":"Signals Webhooks"},{"name":"Public Catalog"}],"paths":{"/research/promotion-investigations":{"post":{"operationId":"startPromotionInvestigation","tags":["Core Intelligence"],"summary":"Start one product promotion history investigation","description":"Start one product promotion history investigation. Uses the same execution and account research allowance as the product page. Explicit confirm_usage and UUID idempotency_key are required. Repeat the same key and inputs to recover the same task. Up to three active tasks per account. Report generation runs in the background. Follow status_url to read progress and the final report together. Service may return 503 before activation.","security":[{"sigpikApiKey":[]}],"x-sigpik-scopes":["research:execute"],"x-sigpik-developer-access-quota-units":1,"responses":{"202":{"description":"Accepted for background processing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromotionInvestigation"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"slug":{"type":"string","minLength":1,"maxLength":200,"pattern":"^[a-z0-9][a-z0-9-]*$"},"locale":{"default":"en","type":"string","enum":["en","zh-CN"]},"idempotency_key":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"confirm_usage":{"type":"boolean","const":true}},"required":["slug","idempotency_key","confirm_usage"],"additionalProperties":false}}}}}},"/research/promotion-investigations/{task_id}":{"get":{"operationId":"getPromotionInvestigation","tags":["Core Intelligence"],"summary":"Read investigation progress and the saved final report in one response","description":"Read investigation progress and the saved final report in one response. report is null until succeeded; failed/cancelled are terminal states. Requires research:read and current account access. Costs zero research credits and zero monthly API calls, even when the monthly counted-call allowance is exhausted. Rate limits still apply. Reads never start or advance execution.","security":[{"sigpikApiKey":[]}],"x-sigpik-scopes":["research:read"],"x-sigpik-developer-access-quota-units":0,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PromotionInvestigation"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}}]}},"/alerts/webhooks":{"post":{"operationId":"createSignalWebhook","tags":["Signals Webhooks"],"summary":"Register an HTTPS endpoint for future confirmed published signals on products you already follow","description":"Register an HTTPS endpoint for future confirmed published signals on products you already follow. The asynchronous verification POST must receive HTTP 2xx and a JSON body echoing its challenge. Notifications are independent of email preferences and never start an investigation. At most ten registrations per account per day. Service may return 503 before activation.","security":[{"sigpikApiKey":[]}],"x-sigpik-scopes":["webhooks:manage"],"x-sigpik-developer-access-quota-units":1,"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SignalWebhook"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"409":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"url":{"type":"string","maxLength":2048},"locale":{"default":"en","type":"string","enum":["en","zh-CN"]},"signal_types":{"minItems":1,"maxItems":30,"type":"array","items":{"type":"string"}}},"required":["url","signal_types"],"additionalProperties":false}}}}}},"/tools/{slug}":{"get":{"operationId":"getToolProfile","tags":["Public Catalog"],"summary":"Get one AI product profile","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Tool profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolProfile"}}}},"404":{"$ref":"#/components/responses/ApiError"}}}},"/research/search-demand":{"get":{"operationId":"researchSearchDemand","tags":["Core Intelligence"],"summary":"Research keyword traffic distribution among AI products","description":"Requires api.access and research:read, plus search_demand.full_database or invited Developer Access. Matches the current /search-demand traffic workspace: keyword search, receiving-product sector filters, product contributions, traffic shares, CR3 concentration and keyword_id detail. Default type is non_brand. items always contains keyword rows; markets contains sector filter options, not a standalone market map. The retired view parameter is rejected. Shares use the complete tracked product sample, not total search volume or the whole market. Existing history and comparison fields are supporting evidence, not separate product views; null changes are unavailable, not zero. Developer Access forces page 1, up to 10 rows, 1 history month and 5 sector filter options, including nested limits. SaaS Ideas (/saas-ideas) is a separate admin-only development workspace with no public API or MCP tool.","security":[{"sigpikApiKey":[]},{"sigpikSession":[]}],"x-sigpik-scopes":["research:read"],"x-sigpik-developer-access-quota-units":1,"parameters":[{"name":"locale","in":"query","schema":{"default":"en","type":"string","maxLength":20}},{"name":"q","in":"query","schema":{"type":"string","maxLength":120}},{"name":"market","in":"query","schema":{"description":"Sector slug; not a country code.","type":"string","maxLength":120}},{"name":"type","in":"query","schema":{"default":"non_brand","type":"string","enum":["all","non_brand","brand"]}},{"name":"min_products","in":"query","schema":{"default":1,"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3},{"type":"number","const":5}]}},{"name":"min_traffic","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":10000000000}},{"name":"min_volume","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":10000000000}},{"name":"sort","in":"query","schema":{"default":"traffic","type":"string","enum":["traffic","volume","products"]}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"maximum":1000}},{"name":"limit","in":"query","schema":{"default":25,"description":"Requested page size. Developer Access caps it at 10 and always returns page 1.","type":"integer","minimum":1,"maximum":50}},{"name":"keyword_id","in":"query","schema":{"description":"Optional observed keyword detail. Omit or use 0 for no detail.","type":"integer","minimum":0,"maximum":9007199254740991}}],"responses":{"200":{"description":"Search Demand research result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchDemandResponse"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}}}},"/research/rankings":{"get":{"operationId":"rankAiProducts","tags":["Core Intelligence"],"summary":"Rank AI products using sigpik market data","description":"Requires api.access and research:read plus market.rankings and market.advanced_filters, or invited Developer Access. Additional ranking dimensions require their corresponding account features. Developer Access forces page 1 and at most 10 results. Growth rates are ratios: 0.314 means 31.4%.","security":[{"sigpikApiKey":[]},{"sigpikSession":[]}],"x-sigpik-scopes":["research:read"],"x-sigpik-developer-access-quota-units":1,"parameters":[{"name":"locale","in":"query","schema":{"default":"en","type":"string","maxLength":20}},{"name":"category","in":"query","schema":{"type":"string","maxLength":120}},{"name":"country","in":"query","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":80}},{"name":"sort","in":"query","schema":{"default":"growth","type":"string","enum":["growth","gain","traffic","dr_growth","organic","ai","paid"]}},{"name":"order","in":"query","schema":{"default":"desc","type":"string","enum":["asc","desc"]}},{"name":"min_traffic","in":"query","schema":{"default":1000,"type":"integer","minimum":0,"maximum":9007199254740991}},{"name":"min_growth","in":"query","schema":{"default":0,"type":"number","minimum":0,"maximum":100}},{"name":"min_dr","in":"query","schema":{"default":0,"type":"number","minimum":0,"maximum":100}},{"name":"min_dr_gain","in":"query","schema":{"default":0,"type":"number","minimum":0,"maximum":100}},{"name":"max_domain_age_months","in":"query","schema":{"default":0,"type":"integer","minimum":0,"maximum":120}},{"name":"page","in":"query","schema":{"default":1,"type":"integer","minimum":1,"maximum":200}},{"name":"limit","in":"query","schema":{"default":25,"description":"Requested page size. Developer Access caps it at 10 and always returns page 1.","type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Ranking research result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RankingsResponse"}}}},"400":{"$ref":"#/components/responses/ApiError"},"401":{"$ref":"#/components/responses/ApiError"},"403":{"$ref":"#/components/responses/ApiError"},"404":{"$ref":"#/components/responses/ApiError"},"429":{"$ref":"#/components/responses/ApiError"},"503":{"$ref":"#/components/responses/ApiError"}}}}},"components":{"securitySchemes":{"sigpikApiKey":{"type":"http","scheme":"bearer","bearerFormat":"spk_live_…","description":"A Developer Access, Pro, or Enterprise API key created in Dashboard → Developer. Send it as Authorization: Bearer <key>."},"sigpikSession":{"type":"http","scheme":"bearer","bearerFormat":"Better Auth signed session","description":"A signed session with Developer Access, Pro, or Enterprise entitlement. Credential-management operations reject developer API keys."}},"schemas":{"DeveloperTask":{"type":"object","required":["task_id","type","status","stage","status_url","result_url","poll_after_seconds","created_at","updated_at","completed_at","error"],"properties":{"task_id":{"type":"string","pattern":"^task_[0-9a-f-]{36}$"},"type":{"const":"promotion_investigation"},"status":{"enum":["queued","running","succeeded","failed","cancelled"]},"stage":{"enum":["queued","investigating","generating_report","complete"]},"status_url":{"type":"string"},"result_url":{"type":["string","null"]},"poll_after_seconds":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"PromotionTaskResult":{"type":"object","required":["task_id","type","report"],"properties":{"task_id":{"type":"string"},"type":{"const":"promotion_investigation"},"report":{"type":"object","properties":{"version":{"type":"string"},"generated_at":{"type":["string","null"],"format":"date-time"},"narrative":{"type":["object","null"],"description":"Cited analysis, sections and action advice from the product-page report."},"summary":{"type":"object"},"analysis":{"type":"object"},"timeline":{"type":"array","items":{"type":"object"}},"strategies":{"type":"array","items":{"type":"object"}},"sources":{"type":"array","items":{"type":"object"}},"context_leads":{"type":"array","items":{"type":"object"}},"conclusion":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}},"caveat":{"type":"string"},"reliability":{"type":"object"},"omitted_action_count":{"type":"integer"},"omitted_context_count":{"type":"integer"}}}}},"SignalWebhook":{"type":"object","required":["id","url","status","locale","signal_types","failure_count","created_at","updated_at"],"properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"status":{"enum":["pending","active","paused","deleted"]},"locale":{"enum":["en","zh-CN"]},"signal_types":{"type":"array","items":{"enum":["traffic_breakout","traffic_acceleration","traffic_deceleration","entered_category_top_10","entered_category_top_20","dropped_out_of_category_top_10","market_share_shift","ai_referral_breakout","ai_traffic_share_shift","new_ai_referral_source","ai_referral_sources_diversified","price_increased","price_decreased","free_plan_added","free_plan_removed","pricing_model_changed","trial_changed","enterprise_plan_introduced","backlink_acquisition_spike","ai_directory_push","media_review_burst","google_ads_started","ad_creative_expansion","new_feature","new_model","api_added","mcp_added","positioning_shift","product_launch","website_sitemap_expansion","website_sitemap_contraction","programmatic_seo_expansion","organic_keyword_breakout","brand_search_growth","new_market_pages","chrome_user_growth","primary_domain_changed","product_discontinued"]}},"failure_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"signing_secret":{"type":"string","description":"Returned only when created or explicitly rotated. Store securely."}}},"SignalWebhookEvent":{"type":"object","required":["id","version","type","created_at","data"],"properties":{"id":{"type":"string"},"version":{"const":"1"},"type":{"enum":["signal.published","webhook.verification","webhook.test"]},"created_at":{"type":"string","format":"date-time"},"data":{"type":"object","description":"Signal: product, signal_type, change, observation period, public evidence summary and product URL. Verification: challenge. Test: message."}}},"PromotionInvestigation":{"allOf":[{"$ref":"#/components/schemas/DeveloperTask"},{"type":"object","required":["report"],"properties":{"report":{"anyOf":[{"type":"object","properties":{"version":{"type":"string"},"generated_at":{"type":["string","null"],"format":"date-time"},"narrative":{"type":["object","null"],"description":"Cited analysis, sections and action advice from the product-page report."},"summary":{"type":"object"},"analysis":{"type":"object"},"timeline":{"type":"array","items":{"type":"object"}},"strategies":{"type":"array","items":{"type":"object"}},"sources":{"type":"array","items":{"type":"object"}},"context_leads":{"type":"array","items":{"type":"object"}},"conclusion":{"type":"string"},"limitations":{"type":"array","items":{"type":"string"}},"caveat":{"type":"string"},"reliability":{"type":"object"},"omitted_action_count":{"type":"integer"},"omitted_context_count":{"type":"integer"}}},{"type":"null"}],"description":"The saved report when succeeded; null while queued/running or after failure. Never generates a report on read."}}}]},"ToolCard":{"type":"object","required":["tool_id","canonical_slug","localized_slug","name","official_url","pricing_model","has_free_plan","has_api","has_mcp","verification_status","staleness_status","requested_locale","resolved_locale"],"properties":{"tool_id":{"type":"integer"},"canonical_slug":{"type":"string"},"localized_slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"short_description":{"type":["string","null"]},"logo_url":{"type":["string","null"]},"favicon_url":{"type":["string","null"]},"screenshot_url":{"type":["string","null"]},"official_url":{"type":"string"},"primary_category_slug":{"type":["string","null"]},"primary_category_name":{"type":["string","null"]},"pricing_model":{"type":"string"},"has_free_plan":{"type":"boolean"},"has_api":{"type":"boolean"},"has_mcp":{"type":"boolean"},"verification_status":{"type":"string","enum":["verified","pending"]},"staleness_status":{"type":"string"},"requested_locale":{"type":"string"},"resolved_locale":{"type":"string"},"available_locales":{"type":["array","null"],"items":{"type":"string"}}},"additionalProperties":true},"ToolProfile":{"type":"object","required":["tool_id","canonical_slug","localized_slug","name","official_url","pricing_model","listed_at","verification_status","staleness_status","has_free_plan","has_free_trial","has_api","has_mcp","requested_locale","resolved_locale","available_locales","categories"],"properties":{"tool_id":{"type":"integer"},"canonical_slug":{"type":"string"},"localized_slug":{"type":"string"},"name":{"type":"string"},"tagline":{"type":["string","null"]},"short_description":{"type":["string","null"]},"long_description":{"type":["string","null"]},"official_url":{"type":"string"},"pricing_model":{"type":"string"},"listed_at":{"type":"string","format":"date-time"},"verification_status":{"type":"string"},"staleness_status":{"type":"string"},"has_free_plan":{"type":"boolean"},"has_free_trial":{"type":"boolean"},"has_api":{"type":"boolean"},"has_mcp":{"type":"boolean"},"requested_locale":{"type":"string"},"resolved_locale":{"type":"string"},"available_locales":{"type":"array","items":{"type":"string"}},"categories":{"type":"array","items":{"type":"object","additionalProperties":true}}},"additionalProperties":true},"SearchDemandItem":{"type":"object","properties":{"keyword":{"type":"string"},"keyword_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"brand_type":{"type":"string","enum":["generic","brand_navigational","brand_commercial","mixed","unknown"]},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"cluster_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"market_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"market_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"market_slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"observed_markets":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_traffic":{"type":"number"},"search_volume":{"type":"number"},"product_change1m":{"anyOf":[{"type":"number"},{"type":"null"}]},"traffic_change1m":{"anyOf":[{"type":"number"},{"type":"null"}]},"comparison_status":{"description":"Growth is usable only when the sample is comparable.","type":"string","enum":["comparable","sample_changed","new_observation","missing_history","insufficient_baseline","unverified"]},"traffic_distribution":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"tool_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"market_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"observed_traffic":{"type":"number"},"share":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["tool_id","name","slug","market_name","observed_traffic","share"],"additionalProperties":{}}},"total_traffic":{"type":"number"},"product_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"other_traffic":{"type":"number"},"other_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"cr3":{"anyOf":[{"type":"number"},{"type":"null"}]},"concentration":{"type":"string","enum":["unknown","single","concentrated","balanced","distributed"]}},"required":["products","total_traffic","product_count","other_traffic","other_products","cr3","concentration"],"additionalProperties":{}}},"required":["keyword","keyword_id","brand_type","cluster_id","cluster_name","market_id","market_name","market_slug","observed_markets","observed_products","observed_traffic","search_volume","product_change1m","traffic_change1m"],"additionalProperties":{}},"SearchDemandResponse":{"type":"object","properties":{"dataset":{"type":"object","properties":{"captured_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"observed_month":{"anyOf":[{"type":"string"},{"type":"null"}]},"exhaustive":{"type":"boolean","const":false},"source":{"type":"string","const":"similarweb"},"sample_type":{"type":"string","const":"top_search_keywords"}},"required":["captured_at","observed_month","exhaustive","source","sample_type"],"additionalProperties":false},"filters":{"type":"object","properties":{"demand_type":{"type":"string","enum":["all","non_brand","brand"]},"market_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"market":{"type":"string"},"min_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"min_traffic":{"type":"number"},"min_volume":{"type":"number"},"page":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"page_size":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"query":{"type":"string"},"selected_keyword_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"sort":{"type":"string","enum":["traffic","volume","products"]}},"required":["demand_type","market_id","market","min_products","min_traffic","min_volume","page","page_size","query","selected_keyword_id","sort"],"additionalProperties":false},"items":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"keyword_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"brand_type":{"type":"string","enum":["generic","brand_navigational","brand_commercial","mixed","unknown"]},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"cluster_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"market_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"market_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"market_slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"observed_markets":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_traffic":{"type":"number"},"search_volume":{"type":"number"},"product_change1m":{"anyOf":[{"type":"number"},{"type":"null"}]},"traffic_change1m":{"anyOf":[{"type":"number"},{"type":"null"}]},"comparison_status":{"description":"Growth is usable only when the sample is comparable.","type":"string","enum":["comparable","sample_changed","new_observation","missing_history","insufficient_baseline","unverified"]},"traffic_distribution":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"tool_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"market_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"observed_traffic":{"type":"number"},"share":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["tool_id","name","slug","market_name","observed_traffic","share"],"additionalProperties":{}}},"total_traffic":{"type":"number"},"product_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"other_traffic":{"type":"number"},"other_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"cr3":{"anyOf":[{"type":"number"},{"type":"null"}]},"concentration":{"type":"string","enum":["unknown","single","concentrated","balanced","distributed"]}},"required":["products","total_traffic","product_count","other_traffic","other_products","cr3","concentration"],"additionalProperties":{}}},"required":["keyword","keyword_id","brand_type","cluster_id","cluster_name","market_id","market_name","market_slug","observed_markets","observed_products","observed_traffic","search_volume","product_change1m","traffic_change1m"],"additionalProperties":{}}},"keyword":{"anyOf":[{"type":"object","properties":{"keyword":{"type":"string"},"keyword_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"brand_type":{"type":"string","enum":["generic","brand_navigational","brand_commercial","mixed","unknown"]},"cluster_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"cluster_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"market_id":{"anyOf":[{"type":"number"},{"type":"null"}]},"market_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"market_slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"observed_markets":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_traffic":{"type":"number"},"search_volume":{"type":"number"},"product_change1m":{"anyOf":[{"type":"number"},{"type":"null"}]},"traffic_change1m":{"anyOf":[{"type":"number"},{"type":"null"}]},"comparison_status":{"description":"Growth is usable only when the sample is comparable.","type":"string","enum":["comparable","sample_changed","new_observation","missing_history","insufficient_baseline","unverified"]},"traffic_distribution":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"tool_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"market_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"observed_traffic":{"type":"number"},"share":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["tool_id","name","slug","market_name","observed_traffic","share"],"additionalProperties":{}}},"total_traffic":{"type":"number"},"product_count":{"type":"integer","minimum":0,"maximum":9007199254740991},"other_traffic":{"type":"number"},"other_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"cr3":{"anyOf":[{"type":"number"},{"type":"null"}]},"concentration":{"type":"string","enum":["unknown","single","concentrated","balanced","distributed"]}},"required":["products","total_traffic","product_count","other_traffic","other_products","cr3","concentration"],"additionalProperties":{}},"history":{"type":"array","items":{"type":"object","properties":{"month":{"type":"string"},"observed_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_traffic":{"type":"number"},"search_volume":{"type":"number"}},"required":["month","observed_products","observed_traffic","search_volume"],"additionalProperties":false}},"markets":{"type":"array","items":{"type":"object","properties":{"market_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"market_name":{"type":"string"},"observed_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_traffic":{"type":"number"},"share":{"type":"number"}},"required":["market_id","market_name","observed_products","observed_traffic","share"],"additionalProperties":false}},"products":{"type":"array","items":{"type":"object","properties":{"tool_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"slug":{"type":"string"},"domain":{"type":"string"},"market_name":{"anyOf":[{"type":"string"},{"type":"null"}]},"observed_traffic":{"type":"number"}},"required":["tool_id","name","slug","market_name","observed_traffic"],"additionalProperties":{}}},"related_observed":{"type":"array","items":{"type":"object","properties":{"keyword":{"type":"string"},"keyword_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"observed_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_traffic":{"type":"number"},"shared_products":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["keyword","keyword_id","observed_products","observed_traffic","shared_products"],"additionalProperties":false}}},"required":["keyword","keyword_id","brand_type","cluster_id","cluster_name","market_id","market_name","market_slug","observed_markets","observed_products","observed_traffic","search_volume","product_change1m","traffic_change1m","history","markets","products","related_observed"],"additionalProperties":{}},{"type":"null"}]},"markets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"slug":{"type":"string"}},"required":["id","name","slug"],"additionalProperties":false},"description":"Product-sector filter options for the keyword table, not a standalone market-map result."},"pagination":{"type":"object","properties":{"page":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"limit":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"has_more":{"type":"boolean"},"has_previous":{"type":"boolean"},"total":{"type":"integer","minimum":0,"maximum":9007199254740991},"total_pages":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["page","limit","has_more","has_previous","total","total_pages"],"additionalProperties":false},"requested_locale":{"type":"string"},"resolved_locale":{"type":"string"},"summary":{"type":"object","properties":{"captured_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"latest_month":{"anyOf":[{"type":"string"},{"type":"null"}]},"markets":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_products":{"type":"integer","minimum":0,"maximum":9007199254740991},"observed_terms":{"type":"integer","minimum":0,"maximum":9007199254740991},"sample_type":{"type":"string","const":"top_search_keywords"},"source":{"type":"string","const":"similarweb"}},"required":["captured_at","latest_month","markets","observed_products","observed_terms","sample_type","source"],"additionalProperties":false}},"required":["dataset","filters","items","keyword","markets","pagination","requested_locale","resolved_locale","summary"],"additionalProperties":false},"RankingItem":{"type":"object","required":["rank","tool_id","name","slug","normalized_domain","latest_month","previous_month","latest_visits","previous_visits","visits_change","growth_rate"],"properties":{"rank":{"type":"integer"},"tool_id":{"type":"integer"},"name":{"type":"string"},"slug":{"type":"string"},"normalized_domain":{"type":"string"},"primary_category_name":{"type":["string","null"]},"primary_category_slug":{"type":["string","null"]},"latest_month":{"type":"string"},"previous_month":{"type":"string"},"latest_visits":{"type":"number"},"previous_visits":{"type":"number"},"visits_change":{"type":"number"},"growth_rate":{"type":"number"},"domain_rating":{"type":["number","null"]},"favicon_url":{"type":["string","null"]}},"additionalProperties":true},"PagePagination":{"type":"object","required":["page","limit","has_more"],"properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"has_previous":{"type":"boolean"},"next_page":{"type":["integer","null"]},"previous_page":{"type":["integer","null"]},"total":{"type":"integer"},"total_pages":{"type":"integer"}},"additionalProperties":true},"RankingsResponse":{"type":"object","required":["dataset","eligible_population","filters","items","pagination","requested_locale","resolved_locale"],"properties":{"category":{"type":["object","null"],"additionalProperties":true},"dataset":{"type":"object","additionalProperties":true},"eligible_population":{"type":"integer"},"filters":{"type":"object","additionalProperties":true},"items":{"type":"array","items":{"$ref":"#/components/schemas/RankingItem"}},"pagination":{"$ref":"#/components/schemas/PagePagination"},"requested_locale":{"type":"string"},"resolved_locale":{"type":"string"}}}},"responses":{"ApiError":{"description":"Machine-readable API error","content":{"application/json":{"schema":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}},"request_id":{"type":"string"}}}}}}}}}