dupe-com/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:

| # | Label | Pass this as archetype | |---|-------|--------------------------| | 1 | Best Value (Deal Hunter) | Shoppers who prioritize getting the best price-to-quality ratio. They compare prices across retailers, look for sales and discounts, and want products that deliver good performance without overpaying. Budget-conscious but quality-aware. Typical budget: $50-$150. | | 2 | Highest Quality Only | Shoppers who only want the absolute best version of a product. They prioritize premium materials, superior construction, and long-term durability. Price is secondary to quality. They read expert reviews and trust established premium brands. Typical budget: $200+. | | 3 | Just Tell Me Which One | Busy shoppers who want a clear, confident recommendation without spending hours researching. They trust expert guidance and want a single "best" option that works for most people. They value convenience and quick decision-making over deep analysis. | | 4 | Social Proof Focused | Shoppers who heavily rely on customer reviews, ratings, and real user experiences. They read both positive and negative reviews, look for patterns in feedback, and trust the wisdom of the crowd over marketing claims. They want products with 4+ star ratings and hundreds of reviews. | | 5 | Deep Research & Comparison | Detail-oriented shoppers who want comprehensive breakdowns of specs, features, pros/cons, and side-by-side comparisons. They enjoy the research process and want all the data before deciding. They compare multiple options across different criteria. |

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:

| Field | Type | Required | Description | |-------|------|----------|-------------| | title | string | Yes | The user's search query (min 5 characters) | | archetype | string | Yes | Full archetype description from table above (NOT the label) | | count | number | No | Number of products to research (2-20, default: 10) |

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):

| Phase | Description | |-------|-------------| | initializing | Setting up the research task | | brief | Writing research brief | | discovery | Discovering products | | gather | Gathering detailed product info | | video_insights | Analyzing video reviews | | social_insights | Analyzing social media | | schema | Structuring product data | | writing_article | Writing the research article | | finalize | Final processing |

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

| Status | Meaning | |--------|---------| | researched | Research is complete, article is ready | | published | Research report website is deployed | | complete | Everything is done | | failed | Research failed (check error message) | | cancelled | Task was cancelled |

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

| Status Code | Meaning | Action | |-------------|---------|--------| | 401 | BOTCHA token missing/invalid/expired | Re-run the BOTCHA auth command from Step 2 | | 400 | Invalid request body | Check title (min 5 chars) and archetype (min 10 chars) | | 404 | Task not found | Verify the taskId is correct | | 500 | Server error | Retry after a few seconds |

Links

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