API quickstart

1. Reveal your default key

Every organisation membership has a one-time Default key slot. Open API settings, confirm the organisation shown, then reveal the key. Store it in a secret manager; ViralSpy only stores an HMAC digest and cannot show the secret again.

export VIRALSPY_API_KEY='vsp_live_…'

2. Search videos

curl --get 'https://api.viralspy.com/v1/videos' \
  --header "Authorization: Bearer $VIRALSPY_API_KEY" \
  --data-urlencode 'q=protein snack' \
  --data-urlencode 'hook=yes' \
  --data-urlencode 'sort=trending' \
  --data-urlencode 'limit=5'

3. Paginate safely

When meta.has_more is true, send meta.next_cursor back unchanged. Cursors are signed, expire after 24 hours, bind to the original query, and cap a single traversal at 20 pages. Do not parse or construct them.

Response shape

{
  "data": [{ "id": "755…", "desc": "…", "play_count": 1834000 }],
  "meta": { "count": 1, "total": 241, "has_more": true, "next_cursor": "eyJ…" },
  "request_id": "9f5f1b55-7c04-4a99-84a5-fce7f2fb6ca6"
}

Keep request_id when contacting support. See authentication, rate limits, and the API reference.