API Documentation

Integrate ViralVideoSearch into your apps, workflows, and automations.

Getting Started

1. Get an API key

Create an API key from your API Keys dashboard (sign in required). Keys start with vvs_.

2. Base URL

https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1

3. Authentication

Pass your API key in the X-API-Key header with every request.

Example

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/videos?limit=5"

Errors & Limits

Rate Limits

API requests are rate-limited to 100 requests per minute per API key. Exceeding this returns 429 Too Many Requests.

Error Format

{
  "error": "Description of the error"
}

Status	Meaning
200	Success
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
404	Resource not found
429	Rate limit exceeded
500	Internal server error

Endpoints

All endpoints require authentication via the X-API-Key header.

Videos

GET

/v1/videos

List your saved viral videos, sorted by most recent.

Parameters

Name	Type	Required	Description
platform	string	Optional	Filter by platform (tiktok, instagram, youtube)
limit	integer	Optional	Max results (1–50, default 20)
offset	integer	Optional	Pagination offset (default 0)

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/videos?platform=tiktok&limit=10"

GET

/v1/videos/search

Search your saved videos by caption text.

Parameters

Name	Type	Required	Description
q	string	Required	Search query
platform	string	Optional	Filter by platform
limit	integer	Optional	Max results (1–50, default 20)

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/videos/search?q=fitness&platform=tiktok"

GET

/v1/videos/:id

Get a single video by its ID. Returns all available fields.

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/videos/abc-123"

GET

/v1/videos/:id/analysis

Get the AI analysis for a specific video.

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/videos/abc-123/analysis"

Analyses

GET

/v1/analyses

List all your AI analyses, sorted by most recent.

Parameters

Name	Type	Required	Description
limit	integer	Optional	Max results (1–50, default 20)
offset	integer	Optional	Pagination offset (default 0)

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/analyses?limit=5"

GET

/v1/analyses/:id

Get a single analysis by its ID.

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/analyses/ana-789"

Niche intelligence

The curated layer: the niches we scrape every day, their ranked feeds with acceleration scores, and pattern aggregates computed from analysed videos. These endpoints never return private libraries, user identifiers or transcripts.

GET

/v1/niches

List the active curated niches.

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/niches"

GET

/v1/niches/:slug/feed

Recent videos captured for a niche, with rank, velocity score, platform-wide and niche-scoped percentiles, and the flags behind the score.

Parameters

Name	Type	Required	Description
days	integer	Optional	Look-back window in days (1–90, default 7)
from	date	Optional	Start date YYYY-MM-DD (overrides days)
to	date	Optional	End date YYYY-MM-DD
limit	integer	Optional	Max results (1–100, default 25)
offset	integer	Optional	Pagination offset (default 0)

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/niches/manifestation/feed?days=7&limit=25"

GET

/v1/niches/:slug/patterns

Aggregated pattern intelligence for a niche over a date range — hook style, format, pacing and psychological pattern distributions from real analyses, plus engagement rate, follower, caption length and hashtag distributions.

Parameters

Name	Type	Required	Description
days	integer	Optional	Look-back window in days (1–180, default 30)
from	date	Optional	Start date YYYY-MM-DD (overrides days)
to	date	Optional	End date YYYY-MM-DD
min_percentile	integer	Optional	Percentile floor for the hashtag set (50–99, default 80)

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/niches/manifestation/patterns?days=30"

GET

/v1/analyses/public

Published analyses — the derived layer only (hook style, format, pacing, scene count, psychological pattern, pattern lesson). Transcripts and recreation prompts are not returned.

Parameters

Name	Type	Required	Description
limit	integer	Optional	Max results (1–100, default 25)
offset	integer	Optional	Pagination offset (default 0)

Request

curl -H "X-API-Key: vvs_YOUR_KEY" \
  "https://hjiellrqkxqlhpzwlfns.supabase.co/functions/v1/public-api/v1/analyses/public?limit=25"

Ready to integrate?

Create your first API key to get started.