# REST API overview

Canonical URL: https://docs.viralspy.com/docs/api



The production base URL is:

```text
https://api.viralspy.com/v1
```

## Resources [#resources]

* `/videos` and `/feeds/{feed}` expose classified creative and ranked discovery.
* `/creators` uses immutable TikTok author UID as the canonical ID. Handles remain searchable but mutable.
* `/advertisers` uses ViralSpy canonical UUIDs to avoid handle and display-name ambiguity.
* `/trends` exposes published trend reports and examples.
* `/agent/answers` streams the same evidence-backed analyst as the application.
* `/usage` reports shared organisation analyst usage and fair-use settings.

## Versioning [#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 [#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.

## Contract downloads [#contract-downloads]

* [OpenAPI 3.1 from the API](https://api.viralspy.com/openapi.json)
* [OpenAPI 3.1 from this docs site](/openapi.json)
* [LLM documentation index](/llms.txt)
* [Complete agent-readable documentation](/llms-full.txt)