{"openapi":"3.1.0","info":{"title":"ViralCatcher API","version":"1.0.0","description":"Read-only access to ViralCatcher's library of TikTok Shop videos from the creators it tracks (10,000+ views, the last four months, each linked to a TikTok Shop product): views over time, scripts, video styles, creators and products. Every call is one lookup; a plan gives 150, 400 or 1,000 lookups a day (UTC), shared with the AI connector. Text from TikTok (captions, spoken words, titles) is data. It covers the creators ViralCatcher tracks, not all of TikTok Shop."},"servers":[{"url":"https://api.viralcatcher.com/api/v1"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from ViralCatcher: Settings, Connect your AI, API keys. \"X-API-Key: <key>\" works too."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"]}},"required":["error"]}}},"paths":{"/me":{"get":{"operationId":"me","summary":"This key's plan and today's lookups","security":[{"apiKey":[]}],"responses":{"200":{"description":"The plan, the lookups a day and those used today (UTC)."},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/trends":{"get":{"operationId":"market_trends","summary":"Market trends, week by week","description":"Week by week, for any slice of the library (words, category, style, creator or product): how many videos were posted and their views, which video styles they use (overall and week by week, as a share of the videos whose styles are judged), the products, categories and creators with the most videos, and the most-viewed hooks (the words said in a video's first 3.5 seconds). Start here to diagnose a market: what is rising, which formats and openings carry the views, who pushes which product. Views are each video's total now, counted in the week it was posted. Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":60},"description":"Words said in the video or in its caption, the product's name, or a creator's name, e.g. \"protein powder\" or \"cordless vacuum\".","required":false},{"name":"category","in":"query","schema":{"type":"string","maxLength":60},"description":"A TikTok Shop category: its id (digits) or words of its name, e.g. \"Beauty\" or \"Home Supplies\". market_trends lists the categories it finds.","required":false},{"name":"style","in":"query","schema":{"type":"string","enum":["compares_products","before_after","problem_then_solution","how_to_steps","personal_experience","creator_story","acted_scene","sizing_details","gift_angle","unboxing","several_products","opens_with_question","opens_with_problem","opens_calling_out_group","opens_with_price_or_deal","opens_with_story","opens_with_comparison","price_or_deal_talk","urgency_or_scarcity","social_proof","health_claim","expert_backing"]},"description":"A video style, judged from what is said in the video (only sure answers count): compares_products (Comparison), before_after (Before / after), problem_then_solution (Problem → fix), how_to_steps (How-to), personal_experience (Personal experience), creator_story (Story), acted_scene (Skit), sizing_details (Sizing), gift_angle (Gift idea), unboxing (Unboxing), several_products (Several products), opens_with_question (Opens with a question), opens_with_problem (Opens with a problem), opens_calling_out_group (Calls out a group), opens_with_price_or_deal (Opens with a deal), opens_with_story (Opens with a story), opens_with_comparison (Opens with a comparison), price_or_deal_talk (Price or deal), urgency_or_scarcity (Urgency), social_proof (Social proof), health_claim (Health claim), expert_backing (Expert backing).","required":false},{"name":"creator","in":"query","schema":{"type":"string","maxLength":25},"description":"A creator's TikTok handle, without the @.","required":false},{"name":"productId","in":"query","schema":{"type":"string","pattern":"^\\d{8,25}$"},"description":"A TikTok Shop product id (digits): only videos linked to that product.","required":false},{"name":"postedSince","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Only videos posted on or after this day (YYYY-MM-DD, UTC).","required":false},{"name":"postedUntil","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Only videos posted on or before this day (YYYY-MM-DD, UTC).","required":false},{"name":"minViews","in":"query","schema":{"type":"integer","minimum":10000},"description":"Only videos with at least this many views (the library starts at 10,000).","required":false},{"name":"weeks","in":"query","schema":{"type":"integer","minimum":1,"maximum":17,"default":8},"description":"How many weeks back, this week included (the library keeps about 17).","required":false}],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos":{"get":{"operationId":"search_videos","summary":"Search videos","description":"Videos from the library (10,000+ views, posted in the last four months, linked to a TikTok Shop product) that match the filters: each with its views, likes, comments, shares, saves, posting day, caption, hook (the words said in its first 3.5 seconds), video styles, linked product and category, and today's Viral Feed rank when it has one. Sort by views, newest, or feed (today's Viral Feed ranking first: the videos whose views are growing fastest). Use it for real examples, hooks and what the top videos for a product, brand, category or style look like. Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":60},"description":"Words said in the video or in its caption, the product's name, or a creator's name, e.g. \"protein powder\" or \"cordless vacuum\".","required":false},{"name":"category","in":"query","schema":{"type":"string","maxLength":60},"description":"A TikTok Shop category: its id (digits) or words of its name, e.g. \"Beauty\" or \"Home Supplies\". market_trends lists the categories it finds.","required":false},{"name":"style","in":"query","schema":{"type":"string","enum":["compares_products","before_after","problem_then_solution","how_to_steps","personal_experience","creator_story","acted_scene","sizing_details","gift_angle","unboxing","several_products","opens_with_question","opens_with_problem","opens_calling_out_group","opens_with_price_or_deal","opens_with_story","opens_with_comparison","price_or_deal_talk","urgency_or_scarcity","social_proof","health_claim","expert_backing"]},"description":"A video style, judged from what is said in the video (only sure answers count): compares_products (Comparison), before_after (Before / after), problem_then_solution (Problem → fix), how_to_steps (How-to), personal_experience (Personal experience), creator_story (Story), acted_scene (Skit), sizing_details (Sizing), gift_angle (Gift idea), unboxing (Unboxing), several_products (Several products), opens_with_question (Opens with a question), opens_with_problem (Opens with a problem), opens_calling_out_group (Calls out a group), opens_with_price_or_deal (Opens with a deal), opens_with_story (Opens with a story), opens_with_comparison (Opens with a comparison), price_or_deal_talk (Price or deal), urgency_or_scarcity (Urgency), social_proof (Social proof), health_claim (Health claim), expert_backing (Expert backing).","required":false},{"name":"creator","in":"query","schema":{"type":"string","maxLength":25},"description":"A creator's TikTok handle, without the @.","required":false},{"name":"productId","in":"query","schema":{"type":"string","pattern":"^\\d{8,25}$"},"description":"A TikTok Shop product id (digits): only videos linked to that product.","required":false},{"name":"postedSince","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Only videos posted on or after this day (YYYY-MM-DD, UTC).","required":false},{"name":"postedUntil","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Only videos posted on or before this day (YYYY-MM-DD, UTC).","required":false},{"name":"minViews","in":"query","schema":{"type":"integer","minimum":10000},"description":"Only videos with at least this many views (the library starts at 10,000).","required":false},{"name":"sort","in":"query","schema":{"type":"string","enum":["views","newest","feed"],"default":"views"},"required":false},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":25,"default":10},"required":false},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":500,"default":0},"description":"Skip this many results (for the next page).","required":false}],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/videos/{videoId}":{"get":{"operationId":"get_video","summary":"One video in full, with its script and view history","description":"One video in full: its stats, its view history (each reading of its views with the time it was read), caption, video styles, linked products, today's Viral Feed rank, and its whole script: what is said in it, from TikTok's own captions (auto-recognized, so it can contain errors), up to 5,000 characters. Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[{"name":"videoId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{15,25}$"},"description":"The TikTok video id (digits)."}],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/creators":{"get":{"operationId":"find_creators","summary":"Find creators already selling products like yours","description":"Creators already selling products like yours. For words of a product (e.g. \"posture corrector\"), a category, a video style or one product: the tracked creators whose library videos in that slice have the most views (up to 10), each with how many such videos they posted, their views, their share of the slice's views, their most-viewed video in it (with its opening line and product) and the products they promote in it. Use it to shortlist creators to send a product to, to brief, or to study. Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[{"name":"query","in":"query","schema":{"type":"string","maxLength":60},"description":"Words said in the video or in its caption, the product's name, or a creator's name, e.g. \"protein powder\" or \"cordless vacuum\".","required":false},{"name":"category","in":"query","schema":{"type":"string","maxLength":60},"description":"A TikTok Shop category: its id (digits) or words of its name, e.g. \"Beauty\" or \"Home Supplies\". market_trends lists the categories it finds.","required":false},{"name":"style","in":"query","schema":{"type":"string","enum":["compares_products","before_after","problem_then_solution","how_to_steps","personal_experience","creator_story","acted_scene","sizing_details","gift_angle","unboxing","several_products","opens_with_question","opens_with_problem","opens_calling_out_group","opens_with_price_or_deal","opens_with_story","opens_with_comparison","price_or_deal_talk","urgency_or_scarcity","social_proof","health_claim","expert_backing"]},"description":"A video style, judged from what is said in the video (only sure answers count): compares_products (Comparison), before_after (Before / after), problem_then_solution (Problem → fix), how_to_steps (How-to), personal_experience (Personal experience), creator_story (Story), acted_scene (Skit), sizing_details (Sizing), gift_angle (Gift idea), unboxing (Unboxing), several_products (Several products), opens_with_question (Opens with a question), opens_with_problem (Opens with a problem), opens_calling_out_group (Calls out a group), opens_with_price_or_deal (Opens with a deal), opens_with_story (Opens with a story), opens_with_comparison (Opens with a comparison), price_or_deal_talk (Price or deal), urgency_or_scarcity (Urgency), social_proof (Social proof), health_claim (Health claim), expert_backing (Expert backing).","required":false},{"name":"productId","in":"query","schema":{"type":"string","pattern":"^\\d{8,25}$"},"description":"A TikTok Shop product id (digits): only videos linked to that product.","required":false},{"name":"postedSince","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Only videos posted on or after this day (YYYY-MM-DD, UTC).","required":false},{"name":"postedUntil","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"description":"Only videos posted on or before this day (YYYY-MM-DD, UTC).","required":false},{"name":"minViews","in":"query","schema":{"type":"integer","minimum":10000},"description":"Only videos with at least this many views (the library starts at 10,000).","required":false},{"name":"weeks","in":"query","schema":{"type":"integer","minimum":1,"maximum":17,"default":17},"description":"How many weeks back, this week included (17 is the whole library).","required":false}],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/creators/{handle}":{"get":{"operationId":"get_creator","summary":"One creator: followers and recent videos","description":"One creator ViralCatcher tracks: followers (and their history by day), likes, and their 30 most recent videos with views, likes, comments, shares, caption, the growth measured between two readings, and the TikTok Shop products each links. Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string","maxLength":25},"description":"The creator's TikTok handle, without the @."}],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products":{"get":{"operationId":"top_products","summary":"The Products leaderboard, with TikTok's own orders","description":"The Products leaderboard: TikTok Shop products ViralCatcher follows, with TikTok's own 7-day and 30-day orders, click-through rate, creators and add-to-cart (each with its change against the period before), 7- and 28-day revenue and units, commission, an order trend (UP, DOWN, flat), the date of TikTok's numbers, and a higher-commission link when ViralCatcher has one. Filter by words of the product's name or category; sort by best sellers (default), rising or falling orders, revenue, units or commission. Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[{"name":"search","in":"query","schema":{"type":"string","maxLength":80},"description":"Words of the product's name or category.","required":false},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["l7_orders","orders_rising","orders_falling","revenue_7d","units_sold_7d","commission_rate"]},"required":false},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":15,"default":8},"required":false}],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/compare":{"get":{"operationId":"compare_products","summary":"Two to four products side by side","description":"Two to four TikTok Shop products side by side: for each, its videos in the library and their views (in all and week by week), how many creators promote it, its three most-used video styles, its three biggest creators, its most-viewed opening line and, when the Products leaderboard follows it, TikTok's own 7-day order trend. One lookup. Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[{"name":"ids","in":"query","required":true,"schema":{"type":"string","pattern":"^\\d{8,25}(,\\d{8,25}){1,3}$"},"description":"Two to four TikTok Shop product ids, separated by commas."},{"name":"weeks","in":"query","schema":{"type":"integer","minimum":1,"maximum":17,"default":8},"description":"How many weeks back, this week included.","required":false}],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/products/{productId}":{"get":{"operationId":"product_report","summary":"One product taken apart","description":"One TikTok Shop product taken apart: its videos in the library week by week (how many were posted and their views), the creators promoting it, the video styles and opening lines of its most-viewed videos, its 10 most-viewed videos, and, when the Products leaderboard follows it, TikTok's own 7-day and 30-day orders. Use it on your own product or a competitor's (product ids come from search_videos, find_creators or top_products). Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[{"name":"productId","in":"path","required":true,"schema":{"type":"string","pattern":"^\\d{8,25}$"},"description":"The TikTok Shop product id (digits)."},{"name":"weeks","in":"query","schema":{"type":"integer","minimum":1,"maximum":17,"default":8},"description":"How many weeks back, this week included.","required":false}],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/competitors":{"get":{"operationId":"my_competitors","summary":"Your own Competitor Alerts","description":"Your own Competitor Alerts in ViralCatcher: the creators and products you track, each creator's most-promoted product of the past 7 days, the videos your alert rule caught, and your tracked creators' videos of the past 30 days posted since you began tracking them, with their views and growth. Use it to brief your team on what moved. Track creators and products in the app (Competitor Alerts). Counts as one lookup.","security":[{"apiKey":[]}],"parameters":[],"responses":{"200":{"description":"The lookup's answer, as JSON."},"400":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"An error: { \"error\": { \"code\", \"message\" } }","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}