API Docs

Public API usage

This page documents the real API-key public API hosted on the TiktokScraper backend.

Authentication

curl https://viralbuilder.io/api/v1/videos/trending \
  -H "X-Api-Key: vb_live_your_key_here"

The public backend API uses the X-Api-Key header. You can create and manage keys from /api-keys.

Public API v1

These are the database-backed public endpoints mounted at /api/v1 and protected by the backend public API key verifier. This is the primary public API surface.

GET/api/v1/videos/trending

Returns the current top trending videos from the public API.

X-Api-Key

curl https://viralbuilder.io/api/v1/videos/trending \
  -H "X-Api-Key: vb_live_your_key_here"

{
  "meta": { "api_version": "v1" },
  "data": [
    {
      "video_id": "...",
      "username": "...",
      "caption": "...",
      "hashtags": [],
      "views": 123456,
      "view_delta_24h": 42000,
      "likes": 12000,
      "comments": 340,
      "shares": 890,
      "duration": 0,
      "thumbnail_url": "https://...",
      "tiktok_url": "https://www.tiktok.com/@username/video/...",
      "presigned_url": null,
      "products": [],
      "created_at": "2026-05-02T18:00:00Z"
    }
  ]
}

POST/api/v1/videos/search

Time-aware full-text video search with cursor pagination. Defaults to recent viral growth ranking.

time_range values: recent (last 3 days), week (last 7 days), month (last 30 days), all (no time filter)

sort_by values: viral-growth (24h view growth), most-viewed (lifetime views), newest (video creation time)

X-Api-Key

curl https://viralbuilder.io/api/v1/videos/search \
  -H "X-Api-Key: vb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
  "query": "supplements for gut health",
  "time_range": "recent",
  "sort_by": "viral-growth",
  "cursor": null
}'

{
  "meta": { "api_version": "v1" },
  "data": [
    {
      "video_id": "...",
      "username": "...",
      "caption": "...",
      "hashtags": [],
      "views": 123456,
      "view_delta_24h": 42000,
      "likes": 12000,
      "comments": 340,
      "shares": 890,
      "duration": 0,
      "thumbnail_url": "https://...",
      "tiktok_url": "https://www.tiktok.com/@username/video/...",
      "presigned_url": null,
      "products": [],
      "created_at": "2026-05-02T18:00:00Z"
    }
  ],
  "pagination": {
    "cursor": "...",
    "has_more": true
  }
}

GET/api/v1/videos/{video_id}

Returns one public video record by video ID.

X-Api-Key

curl https://viralbuilder.io/api/v1/videos/{video_id} \
  -H "X-Api-Key: vb_live_your_key_here"

{
  "meta": { "api_version": "v1" },
  "data": {
    "video_id": "...",
    "username": "...",
    "caption": "...",
    "hashtags": [],
    "views": 123456,
    "view_delta_24h": 42000,
    "likes": 12000,
    "comments": 340,
    "shares": 890,
    "duration": 0,
    "thumbnail_url": "https://...",
    "tiktok_url": "https://www.tiktok.com/@username/video/...",
    "presigned_url": null,
    "products": [
      {
        "product_id": "...",
        "title": "...",
        "price": 29.99,
        "currency": "USD",
        "cover_url": "https://..."
      }
    ],
    "created_at": "2026-05-02T18:00:00Z"
  }
}

GET/api/v1/products/trending

Returns the current top trending products from the public API.

X-Api-Key

curl https://viralbuilder.io/api/v1/products/trending \
  -H "X-Api-Key: vb_live_your_key_here"

{
  "meta": { "api_version": "v1" },
  "data": [
    {
      "product_id": "...",
      "title": "...",
      "price": 29.99,
      "currency": "USD",
      "category": null,
      "cover_url": "https://...",
      "video_count": 12,
      "creator_count": 8,
      "total_view_delta_24h": 0,
      "total_views": 1200000
    }
  ]
}

POST/api/v1/products/search

Time-aware product search with cursor pagination. Defaults to weekly aggregate viral growth ranking.

X-Api-Key

curl https://viralbuilder.io/api/v1/products/search \
  -H "X-Api-Key: vb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
  "query": "postpartum recovery products",
  "time_range": "week",
  "sort_by": "viral-growth",
  "cursor": null
}'

{
  "meta": { "api_version": "v1" },
  "data": [
    {
      "product_id": "...",
      "title": "...",
      "price": 29.99,
      "currency": "USD",
      "category": null,
      "cover_url": "https://...",
      "video_count": 12,
      "creator_count": 8,
      "total_view_delta_24h": 250000,
      "total_views": 1200000
    }
  ],
  "pagination": {
    "cursor": "...",
    "has_more": true
  }
}

GET/api/v1/products/{product_id}

Returns one public product record by product ID.

X-Api-Key

curl https://viralbuilder.io/api/v1/products/{product_id} \
  -H "X-Api-Key: vb_live_your_key_here"

{
  "meta": { "api_version": "v1" },
  "data": {
    "product_id": "...",
    "title": "...",
    "price": 29.99,
    "currency": "USD",
    "category": null,
    "cover_url": "https://...",
    "video_count": 12,
    "creator_count": 8,
    "total_view_delta_24h": 0,
    "total_views": 0
  }
}

GET/api/v1/opportunities/hot

Returns products with the strongest recent aggregate opportunity signal.

X-Api-Key

curl https://viralbuilder.io/api/v1/opportunities/hot \
  -H "X-Api-Key: vb_live_your_key_here"

{
  "meta": { "api_version": "v1" },
  "data": [
    {
      "product": {
        "product_id": "...",
        "title": "...",
        "price": 29.99,
        "currency": "USD",
        "category": null,
        "cover_url": "https://...",
        "video_count": 12,
        "creator_count": 8,
        "total_view_delta_24h": 0,
        "total_views": 0
      },
      "score": 87.5,
      "competition_level": "medium",
      "viral_video_count": 12,
      "top_video": {
        "video_id": "...",
        "views": 123456,
        "username": "",
        "thumbnail_url": "https://..."
      }
    }
  ]
}

GET/api/v1/opportunities/rising

Returns products with the strongest recent growth signal.

X-Api-Key

curl https://viralbuilder.io/api/v1/opportunities/rising \
  -H "X-Api-Key: vb_live_your_key_here"

{
  "meta": { "api_version": "v1" },
  "data": [
    {
      "product": {
        "product_id": "...",
        "title": "...",
        "price": 29.99,
        "currency": "USD",
        "category": null,
        "cover_url": "https://...",
        "video_count": 12,
        "creator_count": 8,
        "total_view_delta_24h": 0,
        "total_views": 0
      },
      "score": 64.2,
      "competition_level": "medium",
      "viral_video_count": 12,
      "top_video": null
    }
  ]
}

GET/api/v1/creators/{username}

Looks up a public creator profile by username.

X-Api-Key

curl https://viralbuilder.io/api/v1/creators/{username} \
  -H "X-Api-Key: vb_live_your_key_here"

{
  "meta": { "api_version": "v1" },
  "data": {
    "username": "...",
    "avatar_url": "https://...",
    "video_count": 42,
    "total_views": 12000000,
    "total_likes": 850000
  }
}

GET/api/v1/creators/{username}/videos

Returns a creator's videos with cursor pagination.

X-Api-Key

curl https://viralbuilder.io/api/v1/creators/{username}/videos \
  -H "X-Api-Key: vb_live_your_key_here"

{
  "meta": { "api_version": "v1" },
  "data": [
    {
      "video_id": "...",
      "username": "...",
      "caption": "...",
      "hashtags": [],
      "views": 123456,
      "view_delta_24h": 0,
      "likes": 12000,
      "comments": 340,
      "shares": 890,
      "duration": 0,
      "thumbnail_url": "https://...",
      "tiktok_url": "https://www.tiktok.com/@username/video/...",
      "presigned_url": null,
      "products": [],
      "created_at": "2026-05-02T18:00:00Z"
    }
  ],
  "pagination": {
    "cursor": "...",
    "has_more": true
  }
}