REST API
REST API overview
The stable resource model, versioning, pagination, and analyst streaming contract.
The production base URL is:
https://api.viralspy.com/v1Resources
/videosand/feeds/{feed}expose classified creative and ranked discovery./creatorsuses immutable TikTok author UID as the canonical ID. Handles remain searchable but mutable./advertisersuses ViralSpy canonical UUIDs to avoid handle and display-name ambiguity./trendsexposes published trend reports and examples./agent/answersstreams the same evidence-backed analyst as the application./usagereports shared organisation analyst usage and fair-use settings.
Versioning
Breaking changes use a new URL version. Additive fields and endpoints may arrive within v1; clients should ignore unknown response fields. Input objects are strict so misspelled filters fail loudly.
Analyst streaming
Successful new analyst requests return Server-Sent Events. Heartbeat events keep intermediaries alive; the terminal final event contains the answer. A duplicate in-flight idempotency key returns 202 rather than opening a second stream. Clients that explicitly send Accept: application/json receive the completed answer as JSON, but must allow for the full analyst runtime.