Dupe Research

Dupe.com AI Product Research

Launch deep product research tasks from your terminal or AI agent — the same research pipeline that powers the dupe.com web app.

What This Skill Does

This skill lets AI agents:

1. Start a research task — provide a search query and shopper archetype
2. Track progress — poll the task status as it moves through research phases
3. Get results — receive product candidates, a research article, and a link to the published report

Research tasks run an AI-powered pipeline that discovers products, gathers reviews, analyzes video content, structures data, and writes a comprehensive research article.

When to Use

Use this skill when the user wants to:

• Research the best products in a category ("best wireless earbuds under $100")
• Compare products with specific priorities (value, quality, reviews, etc.)
• Get AI-powered product recommendations with reasoning
• Generate a detailed research report for a product category

When NOT to Use

• For finding visual dupes/lookalikes of a specific product URL — use the dupe skill instead
• For quick price comparisons without deep research

Background or Foreground?

Research takes 2-5 minutes. After the user picks an archetype, ask them:

"Research takes a few minutes. Want me to run it in the background so we can keep chatting, or wait here for results?"

If background:

1. Spawn a background agent / subagent / task to handle Steps 0-5
2. Tell the user: "Research is running in the background. I'll share results when it's ready."
3. Continue the conversation — the background task will complete on its own
4. For Claude Code: Use the Task tool with subagent_type: "general" and pass the full research prompt (query, archetype, instructions from Steps 0-5)
5. For other agents: Use whatever background task or subagent mechanism is available

If foreground:

1. Run Steps 0-5 directly in the conversation thread
2. Warn the user that polling will block the thread for a few minutes

Instructions

Step 0: Authenticate User (One-Time)

Before using the API, check if the user has a saved auth token. This is a one-time browser sign-in that produces a 30-day JWT.

Check for existing token:

USER_TOKEN=$(python3 -c "
import json, os, time, base64
path = os.path.expanduser('~/.dupe/auth.json')
if not os.path.exists(path):
    exit(1)
data = json.load(open(path))
token = data.get('token', '')
# Check expiry (JWT payload is base64-encoded second segment)
payload = json.loads(base64.urlsafe_b64decode(token.split('.')[1] + '=='))
if payload.get('exp', 0) < time.time():
    exit(1)
print(token)
" 2>/dev/null) || USER_TOKEN=""

If no token (or expired), run the auth flow:

if [ -z "$USER_TOKEN" ]; then
  # Step 1: Initiate auth session
  AUTH_RESPONSE=$(curl -s -X POST "https://api.dupe.com/api/cli-auth/initiate")
  SESSION_ID=$(echo "$AUTH_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['sessionId'])")
  AUTH_URL=$(echo "$AUTH_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['authUrl'])")
  POLL_URL=$(echo "$AUTH_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['pollUrl'])")

  # Step 2: Tell the user to open the URL in their browser
  echo "Please open this URL to sign in: $AUTH_URL"

  # Step 3: Poll until verified (15 minute timeout)
  while true; do
    STATUS_RESPONSE=$(curl -s "$POLL_URL")
    STATUS=$(echo "$STATUS_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('status',''))")
    if [ "$STATUS" = "verified" ]; then
      USER_TOKEN=$(echo "$STATUS_RESPONSE" | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
      mkdir -p ~/.dupe
      echo "{\"token\": \"$USER_TOKEN\"}" > ~/.dupe/auth.json
      echo "Authenticated successfully."
      break
    fi
    sleep 3
  done
fi

Important:

• The user only needs to do this once per 30 days
• The token is saved to ~/.dupe/auth.json and reused automatically
• Tell the user to open the URL — do NOT open it silently
• The auth session expires after 15 minutes if not completed

Step 1: Choose an Archetype

Before starting a research task, ask the user which research style they prefer. Present these options:

If the user doesn't specify a preference, default to option 5 (Deep Research & Comparison).

Step 2: Authenticate with BOTCHA

The API is protected by BOTCHA — a reverse CAPTCHA for AI agents. Run this single command to get a token. It fetches the challenge, solves all 5 SHA-256 hashes, and submits the answer — all in one shot:

TOKEN=$(python3 -c "
import urllib.request, json, hashlib
APP_ID = 'app_b397bc17769877f7'
headers = {'User-Agent': 'dupe-research-skill/1.1', 'Content-Type': 'application/json'}
req = urllib.request.Request(f'https://botcha.ai/v1/token?app_id={APP_ID}', headers=headers)
with urllib.request.urlopen(req) as r:
    data = json.loads(r.read())
ch = data['challenge']
answers = [hashlib.sha256(str(p['num']).encode()).hexdigest()[:8] for p in ch['problems']]
payload = json.dumps({'id': ch['id'], 'answers': answers, 'audience': 'https://api.dupe.com', 'app_id': APP_ID}).encode()
req2 = urllib.request.Request('https://botcha.ai/v1/token/verify', data=payload, headers=headers, method='POST')
with urllib.request.urlopen(req2) as r2:
    result = json.loads(r2.read())
print(result.get('access_token', ''))
")
echo "Token obtained: ${TOKEN:0:20}..."

Critical details:

• The audience field MUST be "https://api.dupe.com" — without it the token will be rejected by the API
• The User-Agent header is required — BOTCHA returns 403 without it
• The entire solve must complete within 500ms of receiving the challenge — python3 handles this easily in a single script
• Tokens expire in 1 hour. If you get a 401, re-run this command
• Uses only python3 (available on macOS and Linux) — no jq, node, or other dependencies

Step 3: Start the Research Task

RESULT=$(curl -s -X POST "https://api.dupe.com/api/research/agent-skill/start" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-User-Auth: $USER_TOKEN" \
  -d "{
    \"title\": \"<USER_SEARCH_QUERY>\",
    \"archetype\": \"<FULL_ARCHETYPE_DESCRIPTION>\",
    \"count\": 10
  }")
TASK_ID=$(echo "$RESULT" | sed -n 's/.*"taskId":"\([^"]*\)".*/\1/p')
REPORT_URL=$(echo "$RESULT" | sed -n 's/.*"reportUrl":"\([^"]*\)".*/\1/p')
echo "Task: $TASK_ID"
echo "Report will be at: $REPORT_URL"

Request body fields:

If a task with the same title already exists for this month, the API returns the existing task (200) so you can resume polling.

Step 4: Poll Until Complete

Run this polling loop. It checks every 10 seconds and exits when research reaches a terminal state:

while true; do
  STATUS_JSON=$(curl -s "https://api.dupe.com/api/research/agent-skill/$TASK_ID/status" \
    -H "Authorization: Bearer $TOKEN" \
    -H "X-User-Auth: $USER_TOKEN")
  PROGRESS=$(echo "$STATUS_JSON" | sed -n 's/.*"progress":\([0-9]*\).*/\1/p')
  TASK_STATUS=$(echo "$STATUS_JSON" | sed -n 's/.*"status":"\([^"]*\)".*/\1/p')
  PHASE=$(echo "$STATUS_JSON" | sed -n 's/.*"currentPhase":"\([^"]*\)".*/\1/p')
  echo "[$PROGRESS%] $PHASE — $TASK_STATUS"
  case "$TASK_STATUS" in
    researched|published|complete|failed|cancelled) break ;;
  esac
  sleep 10
done
echo "Final status: $TASK_STATUS"
echo "$STATUS_JSON"

Research phases (in order):

Terminal statuses — stop polling when you see one of these:

Step 5: Present Results

When the task reaches a terminal status, parse the final STATUS_JSON and present:

## Research Complete: <title>

Found <productsTotal> products.

### Top Picks

1. **<candidate.name>** (<candidate.brand>)
   - Price: $<candidate.priceLow> - $<candidate.priceHigh>
   - [View product details]

2. ...

### Full Report

Read the complete research article: <reportUrl>

---
Powered by dupe.com AI Research

If article is present in the response, you can also display or summarize the full article content directly.

If reportUrl is available, always include it — it links to a beautifully formatted research report page.

Error Handling

Links

• dupe.com: https://dupe.com
• BOTCHA (agent auth): https://botcha.ai
• dupe.com skills repo: github.com/dupe-com/skills

Converted and distributed by TomeVault — claim your Tome and manage your conversions.