# Quickstart (/docs/quickstart)



You'll need a key (see **[Get an API key](/docs/get-api-key)**). Have your secret manager inject it
as `VIRALQUERY_API_KEY`; for an interactive shell, use the [non-echo setup](/docs/cli/auth). Never
type a literal key into shell history.

```bash
# 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:

```bash
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.