Quickstart | viralquery

Set a research brief, add rules, and run your first personalized research scroll.

You'll need a key (see Get an API key). Have your secret manager inject it as VIRALQUERY_API_KEY; for an interactive shell, use the non-echo setup. Never type a literal key into shell history.

# VIRALQUERY_API_KEY is already present in this process environment.

# 1. Set your one research workspace. Add an App Store URL, website, or both when useful.
curl -X POST https://api.viralquery.com/v1/workspace \
  -H "Authorization: Bearer $VIRALQUERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description":"Calorie tracking apps and the organic videos that make them spread","appStoreUrl":"https://apps.apple.com/us/app/cal-ai-food-calorie-tracker/id6480417616","competitors":["MyFitnessPal","Lose It!"]}'

# 2. Add plain-English research rules
curl -X PUT https://api.viralquery.com/v1/rules \
  -H "Authorization: Bearer $VIRALQUERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Find organic demos and strong visual hooks. Prefer recent posts. Skip reposts."}'

# 3. Run a scroll
curl -X POST https://api.viralquery.com/v1/scrolls \
  -H "Authorization: Bearer $VIRALQUERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"idempotencyKey":"first-scroll-2026-07-10","prompt":"Prioritize recent organic demos and unusual view outliers.","template":"weekly-niche-scan"}'
# → { "outcome": "queued", "scroll": { "id": "...", "status": "queued" } }

Check the returned scroll ID until it completes, then read the personalized results:

curl "https://api.viralquery.com/v1/scrolls?id=$SCROLL_ID" -H "Authorization: Bearer $VIRALQUERY_API_KEY"
curl https://api.viralquery.com/v1/library -H "Authorization: Bearer $VIRALQUERY_API_KEY"
curl https://api.viralquery.com/v1/outliers -H "Authorization: Bearer $VIRALQUERY_API_KEY"
curl https://api.viralquery.com/v1/trends -H "Authorization: Bearer $VIRALQUERY_API_KEY"
curl https://api.viralquery.com/v1/hooks -H "Authorization: Bearer $VIRALQUERY_API_KEY"

Every result endpoint returns at most 25 items. Use GET /v1/usage to confirm subscription state and see consumption as daily/monthly budget percentages.