{"openapi":"3.1.0","info":{"title":"ViralSpy API","version":"1.0.0-beta.1","description":"Search ViralSpy's classified TikTok creative corpus and request evidence-backed analyst answers. Search is unlimited as a plan entitlement and protected by documented fair-use controls.","contact":{"name":"ViralSpy support","url":"https://docs.viralspy.com/docs/support"}},"servers":[{"url":"https://api.viralspy.com/v1","description":"Production"}],"tags":[{"name":"Videos"},{"name":"Creators"},{"name":"Advertisers"},{"name":"Hooks"},{"name":"Shop"},{"name":"Trends"},{"name":"Analyst"},{"name":"Usage"}],"paths":{"/videos":{"get":{"operationId":"searchVideos","summary":"Search videos","tags":["Videos"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":200}},{"name":"sort","in":"query","schema":{"enum":["best_match","trending","breakout","newest","views","comments","reposts"]}},{"name":"ad","in":"query","schema":{"enum":["any","yes","no"]}},{"name":"hook","in":"query","schema":{"enum":["any","yes","no"]}},{"name":"viral_hook","in":"query","schema":{"enum":["any","yes","no"]}},{"name":"media_type","in":"query","schema":{"enum":["any","video","slideshow"]}},{"name":"region","in":"query","schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"content_source","in":"query","schema":{"enum":["all","brand","ugc","unknown"],"default":"all"},"description":"Publisher: the advertiser's own account (brand) or creators (ugc)."},{"name":"promotion_status","in":"query","schema":{"enum":["all","promotional","none_detected","unknown"],"default":"all"},"description":"Promotion detection (disclosures, TikTok Shop, classified ads). Takes precedence over ad."},{"name":"tiktok_shop","in":"query","schema":{"enum":["any","yes","no"],"default":"any"}},{"name":"product_types","in":"query","schema":{"type":"string"},"description":"Advertised product types: app, saas_and_software, physical_product, beauty_and_personal_care, fashion_and_apparel, food_and_beverage, health_and_supplements, digital_product, service, entertainment, finance, education, other. Comma-separated; matches any."},{"name":"formats","in":"query","schema":{"type":"string"},"description":"Video formats, e.g. talking-head, screen-recording, green-screen, pov, skit, demo. Comma-separated; matches any."},{"name":"hook_mechanics","in":"query","schema":{"type":"string"},"description":"Hook mechanics, e.g. curiosity, problem-solution, contrarian, social_proof. Comma-separated; matches any."},{"name":"promotion_strategies","in":"query","schema":{"type":"string"},"description":"Promotion strategies, e.g. founder-led, ugc-style, demo-led, testimonial-led. Comma-separated; matches any."},{"name":"posted_after","in":"query","schema":{"type":"string","format":"date"}},{"name":"posted_before","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Results per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response's meta.next_cursor. Reuse only with identical query parameters and limit; invalid, expired, or mismatched cursors return 400 invalid_cursor."},{"name":"include","in":"query","schema":{"enum":["preview","full_text"],"default":"preview"},"description":"List results are previews by default: transcript, caption (desc), and video_description are trimmed to about 300 characters (flagged transcript_truncated / description_truncated) and slideshows keep 3 image URLs (image_count has the total); trend reports are summarised. Pass full_text for complete text, or fetch the item by ID."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/videos/{id}":{"get":{"operationId":"getVideo","summary":"Get a video","tags":["Videos"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"TikTok aweme ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"request_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/videos/{id}/similar-hooks":{"get":{"operationId":"findSimilarHooks","summary":"Find videos with similar hooks","tags":["Videos"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":12,"default":8}},{"name":"include","in":"query","schema":{"enum":["preview","full_text"],"default":"preview"},"description":"List results are previews by default: transcript, caption (desc), and video_description are trimmed to about 300 characters (flagged transcript_truncated / description_truncated) and slideshows keep 3 image URLs (image_count has the total); trend reports are summarised. Pass full_text for complete text, or fetch the item by ID."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/feeds/{feed}":{"get":{"operationId":"listFeed","summary":"List a ranked creative feed","tags":["Videos"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"feed","in":"path","required":true,"schema":{"enum":["breakout","early_breakout","trending","newest"]}},{"name":"region","in":"query","schema":{"type":"string","pattern":"^[A-Z]{2}$"}},{"name":"language","in":"query","schema":{"type":"string"}},{"name":"content_source","in":"query","schema":{"enum":["all","brand","ugc","unknown"],"default":"all"},"description":"Publisher: the advertiser's own account (brand) or creators (ugc)."},{"name":"promotion_status","in":"query","schema":{"enum":["all","promotional","none_detected","unknown"],"default":"all"},"description":"Promotion detection (disclosures, TikTok Shop, classified ads). Takes precedence over ad."},{"name":"tiktok_shop","in":"query","schema":{"enum":["any","yes","no"],"default":"any"}},{"name":"product_types","in":"query","schema":{"type":"string"},"description":"Advertised product types: app, saas_and_software, physical_product, beauty_and_personal_care, fashion_and_apparel, food_and_beverage, health_and_supplements, digital_product, service, entertainment, finance, education, other. Comma-separated; matches any."},{"name":"formats","in":"query","schema":{"type":"string"},"description":"Video formats, e.g. talking-head, screen-recording, green-screen, pov, skit, demo. Comma-separated; matches any."},{"name":"hook_mechanics","in":"query","schema":{"type":"string"},"description":"Hook mechanics, e.g. curiosity, problem-solution, contrarian, social_proof. Comma-separated; matches any."},{"name":"promotion_strategies","in":"query","schema":{"type":"string"},"description":"Promotion strategies, e.g. founder-led, ugc-style, demo-led, testimonial-led. Comma-separated; matches any."},{"name":"posted_after","in":"query","schema":{"type":"string","format":"date"}},{"name":"posted_before","in":"query","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Results per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response's meta.next_cursor. Reuse only with identical query parameters and limit; invalid, expired, or mismatched cursors return 400 invalid_cursor."},{"name":"include","in":"query","schema":{"enum":["preview","full_text"],"default":"preview"},"description":"List results are previews by default: transcript, caption (desc), and video_description are trimmed to about 300 characters (flagged transcript_truncated / description_truncated) and slideshows keep 3 image URLs (image_count has the total); trend reports are summarised. Pass full_text for complete text, or fetch the item by ID."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/creators":{"get":{"operationId":"searchCreators","summary":"Search creators","tags":["Creators"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100}},{"name":"view","in":"query","schema":{"enum":["all","trending","new"]}},{"name":"type","in":"query","schema":{"enum":["all","advertised","hire_ready","house"]}},{"name":"window","in":"query","schema":{"enum":[2,7,30]}},{"name":"niche","in":"query","schema":{"enum":["app","saas_and_software","physical_product","beauty_and_personal_care","fashion_and_apparel","food_and_beverage","health_and_supplements","digital_product","service","entertainment","finance","education","other"]},"description":"The creator's main advertised product type."},{"name":"country","in":"query","schema":{"type":"string","pattern":"^[A-Z]{2}$"},"description":"Creator country: where most of their posts come from."},{"name":"has_email","in":"query","schema":{"type":"boolean"},"description":"Only creators with a publicly listed contact email."},{"name":"min_followers","in":"query","schema":{"type":"integer","minimum":0}},{"name":"max_followers","in":"query","schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Results per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response's meta.next_cursor. Reuse only with identical query parameters and limit; invalid, expired, or mismatched cursors return 400 invalid_cursor."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/creators/{id}":{"get":{"operationId":"getCreator","summary":"Get a creator by immutable TikTok UID","tags":["Creators"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Immutable TikTok author UID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"request_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/creators/{id}/videos":{"get":{"operationId":"listCreatorVideos","summary":"List a creator's videos","tags":["Creators"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"ads","in":"query","schema":{"enum":["any","yes","no"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Results per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response's meta.next_cursor. Reuse only with identical query parameters and limit; invalid, expired, or mismatched cursors return 400 invalid_cursor."},{"name":"include","in":"query","schema":{"enum":["preview","full_text"],"default":"preview"},"description":"List results are previews by default: transcript, caption (desc), and video_description are trimmed to about 300 characters (flagged transcript_truncated / description_truncated) and slideshows keep 3 image URLs (image_count has the total); trend reports are summarised. Pass full_text for complete text, or fetch the item by ID."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/advertisers":{"get":{"operationId":"searchAdvertisers","summary":"Search advertisers","tags":["Advertisers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","schema":{"type":"string","maxLength":100}},{"name":"view","in":"query","schema":{"enum":["all","trending","new"]}},{"name":"focus","in":"query","schema":{"enum":["all","apps","dtc"]}},{"name":"category","in":"query","schema":{"enum":["beauty","apps","products","fashion","services","food","entertainment","digital","health","education","finance","automotive"]},"description":"beauty: Beauty & personal care; apps: Apps & software; products: Consumer products; fashion: Fashion & apparel; services: Services; food: Food & drink; entertainment: Entertainment & games; digital: Digital products; health: Health & supplements; education: Education & courses; finance: Finance; automotive: Automotive"},{"name":"niche","in":"query","schema":{"enum":["skincare","makeup","haircare","nails","fragrance","salons","beauty_retail","supplements","telehealth","wellness_products","clothing","activewear","shoes","jewellery","bags_accessories","lingerie","snacks","drinks","alcohol","restaurants","grocery_delivery","home_kitchen","cleaning","electronics","pet","kids_baby","sports_outdoor","general_retail","other_goods","ai_tools","creative_apps","productivity","social_apps","lifestyle_apps","learning_apps","games","streaming","music","events_sports","tabletop","templates","ebooks","ingame_items","courses_coaching","business_courses","schools_tutoring","banking","investing","crypto","betting","insurance_loans","travel","telecom","local_services","b2b_services","shopping_services","cars","car_care","auto_dealers"]},"description":"Sub-niche within a category (coverage still growing)."},{"name":"order","in":"query","schema":{"enum":["relevance","signal","newest","views","posts","top_video"]}},{"name":"window","in":"query","schema":{"enum":[0,2,7,30]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Results per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response's meta.next_cursor. Reuse only with identical query parameters and limit; invalid, expired, or mismatched cursors return 400 invalid_cursor."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/advertisers/{id}":{"get":{"operationId":"getAdvertiser","summary":"Get a canonical advertiser","tags":["Advertisers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Canonical advertiser UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"request_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/advertisers/{id}/videos":{"get":{"operationId":"listAdvertiserVideos","summary":"List an advertiser's videos","tags":["Advertisers"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Results per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response's meta.next_cursor. Reuse only with identical query parameters and limit; invalid, expired, or mismatched cursors return 400 invalid_cursor."},{"name":"include","in":"query","schema":{"enum":["preview","full_text"],"default":"preview"},"description":"List results are previews by default: transcript, caption (desc), and video_description are trimmed to about 300 characters (flagged transcript_truncated / description_truncated) and slideshows keep 3 image URLs (image_count has the total); trend reports are summarised. Pass full_text for complete text, or fetch the item by ID."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/hooks":{"get":{"operationId":"listHooks","summary":"List the Hooks chart (hook formulas ranked by distinct creators, refreshed every 3 hours)","tags":["Hooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"lens","in":"query","schema":{"enum":["trending","rising","performing","evergreen"],"default":"trending"}},{"name":"q","in":"query","schema":{"type":"string","maxLength":100},"description":"Text filter over the formula, wording, mechanics and brands."},{"name":"product_type","in":"query","schema":{"enum":["app","saas_and_software","physical_product","beauty_and_personal_care","fashion_and_apparel","food_and_beverage","health_and_supplements","digital_product","service","entertainment","finance","education","other"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/hooks/{id}/history":{"get":{"operationId":"getHookHistory","summary":"Daily history for one hook formula","tags":["Hooks"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"days","in":"query","schema":{"type":"integer","minimum":7,"maximum":180,"default":42}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shop/products":{"get":{"operationId":"listShopProducts","summary":"List TikTok Shop products gaining traction","tags":["Shop"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":60,"default":7}},{"name":"q","in":"query","schema":{"type":"string","maxLength":80},"description":"Product title fragment."},{"name":"category","in":"query","schema":{"type":"string","maxLength":80},"description":"TikTok Shop category name or fragment (see /shop/categories)."},{"name":"regions","in":"query","schema":{"type":"string"},"description":"Posting creators' countries (ISO alpha-2), comma-separated."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/shop/categories":{"get":{"operationId":"listShopCategories","summary":"List TikTok Shop categories with product counts","tags":["Shop"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":60,"default":7}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/trends":{"get":{"operationId":"listTrends","summary":"List trend reports","tags":["Trends"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Results per page."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous response's meta.next_cursor. Reuse only with identical query parameters and limit; invalid, expired, or mismatched cursors return 400 invalid_cursor."},{"name":"include","in":"query","schema":{"enum":["preview","full_text"],"default":"preview"},"description":"List results are previews by default: transcript, caption (desc), and video_description are trimmed to about 300 characters (flagged transcript_truncated / description_truncated) and slideshows keep 3 image URLs (image_count has the total); trend reports are summarised. Pass full_text for complete text, or fetch the item by ID."}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","required":["data","meta","request_id"],"properties":{"data":{"type":"array","items":{"type":"object","additionalProperties":true}},"meta":{"$ref":"#/components/schemas/PageMeta"},"request_id":{"type":"string","format":"uuid"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/trends/{id}":{"get":{"operationId":"getTrend","summary":"Get a trend report","tags":["Trends"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Trend report ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"request_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/agent/answers":{"post":{"operationId":"createAgentAnswer","summary":"Request an evidence-backed ViralSpy analyst answer","tags":["Analyst"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8,"maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["question"],"properties":{"question":{"type":"string","minLength":1,"maxLength":8000},"context":{"type":"string","maxLength":12000}}}}}},"responses":{"200":{"description":"SSE stream by default","content":{"text/event-stream":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object"}}}},"202":{"description":"An identical request is already running"},"409":{"description":"Idempotency key reused with a different request"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/agent/answers/{id}":{"get":{"operationId":"getAgentAnswer","summary":"Get analyst request status or result","tags":["Analyst"],"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Analyst request UUID","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"request_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Get organisation usage","tags":["Usage"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","additionalProperties":true},"request_id":{"type":"string","format":"uuid"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Use a ViralSpy API key. Never place keys in query strings. 401 responses carry a WWW-Authenticate: Bearer challenge."}},"schemas":{"PageMeta":{"type":"object","required":["count","has_more","next_cursor"],"properties":{"count":{"type":"integer"},"total":{"type":["integer","null"]},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"Problem":{"type":"object","required":["type","title","status","request_id"],"properties":{"type":{"type":"string","format":"uri"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"code":{"type":"string"},"request_id":{"type":"string","format":"uuid"}}}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"Missing or invalid credential","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"NotFound":{"description":"Resource not found","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"RateLimited":{"description":"Fair-use or rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}}}