{"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":"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","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":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned by the previous response."}],"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}}],"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":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned by the previous response."}],"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":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned by the previous response."}],"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}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned by the previous response."}],"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":"window","in":"query","schema":{"enum":[0,2,7,30]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned by the previous response."}],"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}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned by the previous response."}],"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}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor returned by the previous response."}],"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."}},"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"}}}}}}}