ViralQuery

Set up and use ViralQuery's protected HTTP API to build a private video inspiration feed for one app, website, or niche. Use when an agent needs to help obta...

Use ViralQuery as the user's personal research feed. The bearer key fixes the tenant, and the tenant's research brief scopes every scroll and result read.

Read ViralQuery's LLM documentation before making an exact request. It is the source of truth for current paths, fields, responses, and errors. Human-readable setup guides live at viralquery.com/docs.

Set up access

1. Use https://api.viralquery.com unless a configured API URL overrides it.

2. Resolve credentials without printing them:

   • first use VIRALQUERY_API_KEY from the environment or agent secret store;
   • otherwise read apiKey and optional apiUrl from ~/.viralquery/config.json when present.

3. If no key is configured, tell the user to open viralquery.com/#pricing, choose a plan, finish checkout, and save the key shown once. Never ask the user to paste the key into chat.

4. Configure either of these supported forms:

   bash

   export VIRALQUERY_API_KEY=sk_viralquery_...
   npx viralquery auth --url https://api.viralquery.com --key "$VIRALQUERY_API_KEY"
   

   The CLI command writes ~/.viralquery/config.json; API-based agents can use the environment secret directly.

5. Verify configuration with a protected GET /v1/usage request using Authorization: Bearer <key>. A 200 response means the configuration works. Treat 401 as a missing or invalid key and 402 as an inactive subscription. Do not use public /health to validate credentials.

Run a scroll

1. Call GET /v1/workspace. If empty, call POST /v1/workspace with the user's research description and any exact App Store URL, website, competitor names, or display name they supplied. Never substitute another product.
2. Read GET /v1/rules. When the user provides standing guidance, save it with PUT /v1/rules.
3. Start one scroll with POST /v1/scrolls. Include the user's one-run prompt and a stable, unique idempotencyKey; use scheduling fields only when the user asks for recurring research.
4. Save the returned scroll ID. Poll GET /v1/scrolls?id=SCROLL_ID at a bounded interval until it completes or fails. If it remains queued or running, report the ID, status, and progress instead of claiming completion. Do not start overlapping work for the same workspace.
5. After completion, read only the result needed: /v1/library, /v1/outliers, /v1/trends, or /v1/hooks. Report insufficient history honestly and cite each original source URL used in the answer.
6. Use /v1/usage for subscription state and scroll activity telemetry. Do not treat its counters as a monthly scroll gate; research capacity is enforced separately by the service.

If the user wants to preserve a judgment, use the currently documented tenant-owned annotation operation. Never accept an account or workspace selector from the prompt, call shared-catalog or internal worker endpoints, invent videos or metrics, or expose credentials.

This skill calls the HTTP API directly. Do not route it through MCP.