Build a research workflow

The strongest workflow separates retrieval from synthesis.

1. Retrieve narrowly

Search with a clear subject and a small limit. Use ranked feeds when you need discovery without a text query. Add ad or hook filters only when they express a real constraint.

2. Resolve canonical entities

Save video aweme IDs, creator UIDs, and advertiser UUIDs. Handles and display names can change or collide. Canonical IDs keep bookmarks, caches, and joins stable.

3. Inspect evidence

Fetch detail records and representative videos. Record the time window and URLs used. ViralSpy classifications can guide research, but a model-assisted label should not be presented as a legal determination.

4. Synthesize once

Call the analyst after you have a focused question. Supply relevant context, use an idempotency key, and retain the final evidence-bearing result. This consumes one shared organisation request; primitive search does not.

const idempotencyKey = crypto.randomUUID();
const response = await fetch('https://api.viralspy.com/v1/agent/answers', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.VIRALSPY_API_KEY}`,
    Accept: 'text/event-stream',
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    question: 'Which three hook mechanics recur across these examples?',
    context: 'Video IDs: 755…, 754…, 753…',
  }),
});

If the connection drops, retry with the same key or fetch /v1/agent/answers/{id}. Do not submit a new key for the same work.

SSE is the default and recommended mode for multi-minute analysis. Set Accept: application/json only when your HTTP client is configured to wait for the complete answer; idempotency and status polling still apply.