API reference · ViralHits

Overview

The ViralHits API is a thin wrapper around the same primitives the web app uses. Anything you can do on the site, you can do over HTTP: paste a URL to analyze, list your past analyses, browse the shared library, and read your campaign data.

Base URL: https://viralhits.app/api/v1
Auth: Personal API keys via the Authorization: Bearer <key> header.
Response format: JSON, UTF-8.
Rate limit: 60 requests per rolling 60-second window per key. Exceeding it returns 429 with a Retry-After header.
Tier gate: API access requires an Agency plan. Free / Starter / Pro keys will return 401.

Authentication

Create a key at Settings → API. Each key is shown once at creation time — copy it into your secret store immediately. Revoke a compromised key from the same page; revocation is instant.

Example:

curl https://viralhits.app/api/v1/me \
  -H "Authorization: Bearer vh_live_xxxxxxxxxxxxxxxxxxxxxxxxx"

Error shape

Non-2xx responses return a JSON body with an error field and, where useful, a code for programmatic handling:

{
  "error": "You've used your free analysis. Upgrade for unlimited.",
  "code": "FREE_TIER_EXCEEDED"
}

Endpoints

GET/me

Return the authenticated user. Useful for key validation + checking plan tier.

Example

curl https://viralhits.app/api/v1/me \
  -H "Authorization: Bearer vh_live_..."

Response

{
  "id": "9f10…",
  "email": "you@example.com",
  "display_name": "You",
  "subscription_tier": "agency",
  "subscription_status": "active"
}

POST/analyze

Submit a TikTok or Instagram URL. Returns the full analysis bundle — video metadata, latest metrics, and classifier tags. Respects the same cache the web app uses; repeat calls with the same URL are cheap.

Request body

`url`required	string	TikTok or Instagram video URL.
`force`	boolean	Bypass the cache and re-run extractor + classifier.

Example

curl -X POST https://viralhits.app/api/v1/analyze \
  -H "Authorization: Bearer vh_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.tiktok.com/@user/video/1234","force":false}'

Response

{
  "video_id": "8e91…",
  "cache_hit": false,
  "synthetic_metrics": false,
  "video": { "id": "8e91…", "platform": "tiktok", "title": "…", "thumbnail_url": "…" },
  "metrics": { "views": 125400, "likes": 8210, "shares": 540, "saves": 940, "comments": 73 },
  "tags": {
    "industry": "Education",
    "content_format": "Problem/Solution",
    "hook_type": "Curiosity gap",
    "hook_timeline": [ /* beat-by-beat breakdown */ ],
    "remix_suggestion": "…",
    "tags": ["hook:curiosity", "niche:education", "format:tutorial", /* … */]
  }
}

GET/analyses

List the authenticated user's analyses, newest first. Paginated.

Example

curl "https://viralhits.app/api/v1/analyses?page=1&per_page=50" \
  -H "Authorization: Bearer vh_live_..."

Response

{
  "data": [
    { "analyzed_at": "…", "cache_hit": false, "video": { /* … */ } }
  ],
  "pagination": { "page": 1, "per_page": 50, "total": 137, "has_more": true }
}

GET/videos

Browse the shared library. Same filters as the /explore UI. Cached cross-user, so don't be surprised if a newly-analyzed video takes up to an hour to appear.

Query parameters

`q`	string	Search in titles + creator usernames.
`industry`	string	e.g. Education, Finance, E-commerce.
`format`	string	e.g. Tutorial, Before/After, Testimonial.
`platform`	string	tiktok \| instagram.
`sort`	string	analyzed (default) \| recent \| outlier \| trending.
`page`	integer	1-indexed.
`per_page`	integer	Default 24, max 100.

Example

curl "https://viralhits.app/api/v1/videos?platform=tiktok&industry=Education&sort=outlier" \
  -H "Authorization: Bearer vh_live_..."

Response

{
  "data": [ /* explore items with video + latest metrics + tags */ ],
  "pagination": { "page": 1, "per_page": 24, "total": 842, "has_more": true }
}

GET/videos/{id}

Fetch the full analysis bundle for a specific video — the same payload POST /analyze returns.

Example

curl https://viralhits.app/api/v1/videos/8e91... \
  -H "Authorization: Bearer vh_live_..."

Response

{ "video": { /* … */ }, "metrics": { /* … */ }, "tags": { /* … */ } }

GET/campaigns

List your campaigns (Agency feature).

Example

curl https://viralhits.app/api/v1/campaigns \
  -H "Authorization: Bearer vh_live_..."

Response

{ "data": [ /* campaigns, newest first */ ] }

GET/campaigns/{id}

Pull one campaign with its creators and recent payout entries.

Example

curl https://viralhits.app/api/v1/campaigns/abcd... \
  -H "Authorization: Bearer vh_live_..."

Response

{
  "campaign": { /* … */ },
  "creators": [ /* … */ ],
  "payouts": [ /* 20 most recent */ ]
}

Versioning

Breaking changes land under a new major version (e.g. /api/v2). /api/v1 will remain stable; additive fields (new keys on response objects) are not considered breaking.

Support

Found a bug or want a new endpoint? Email api@viralhits.app.