---
name: product-arena-api
description: Use when the user wants to integrate with Product Arena — vote on products (hits/misses/tbd), manage personal lists, manage bookmarks, post comments, or fetch leaderboard data. Covers both the REST API (with x-api-key authentication) and the official CLI tool (productarena-cli).
license: MIT
compatibility:
  - Claude Code
  - Cursor
  - Gemini CLI
  - VS Code
metadata:
  author: Product Arena
  version: "2.0"
  tags: api, cli, product-arena, hits, misses, tbd, bookmarks, leaderboard, comments
---

# Product Arena API Skill

Integrate with Product Arena to vote on products, manage your Hits, Misses & TBD lists, manage bookmarks, post comments, and fetch leaderboard data — via REST API or the official CLI.

## Base URL

`https://www.productarena.co`

## Authentication

Include your API key in the request header:

```
x-api-key: pa_your_key_here
```

Create API keys at [Product Arena Docs](https://www.productarena.co/docs) after signing in.

---

## REST API Endpoints

### 1. Get My Products (Hits, Misses & TBD)

**GET** `/api/products`

Fetch your personal Hits, Misses and TBD lists. Requires authentication.

**Response:**
```json
{
  "hits": [
    { "id": "clx...", "url": "https://...", "title": "...", "domain": "...", "arenaType": "hits", ... }
  ],
  "misses": [
    { "id": "clx...", "url": "https://...", "title": "...", "domain": "...", "arenaType": "misses", ... }
  ],
  "tbd": [
    { "id": "clx...", "url": "https://...", "title": "...", "domain": "...", "arenaType": "tbd", ... }
  ]
}
```

### 2. Add a Product (Hit, Miss, or TBD)

**POST** `/api/products`

Add a product to your personal Hits, Misses or TBD list.

**Request body:**
```json
{
  "url": "https://example.com",
  "arenaType": "hits"
}
```

`arenaType` must be `"hits"`, `"misses"`, or `"tbd"`.

**Response:** `201`
```json
{
  "id": "clx...",
  "url": "https://example.com",
  "title": "Example",
  "domain": "example.com",
  "arenaType": "hits",
  "existsGlobally": false
}
```

### 3. Remove a Product

**DELETE** `/api/products`

Remove a product from your list by its URL or domain.

**Request body (by URL):**
```json
{
  "url": "https://example.com"
}
```

**Request body (by domain):**
```json
{
  "domain": "example.com"
}
```

**Response:**
```json
{ "success": true }
```

### 4. Get My Bookmarks

**GET** `/api/bookmarks`

Fetch your bookmarked URLs. Requires authentication.

**Response:**
```json
[
  {
    "id": "clx...",
    "url": "https://...",
    "title": "...",
    "favicon": "...",
    "position": 0
  }
]
```

### 5. Add a Bookmark

**POST** `/api/bookmarks`

Bookmark a URL. The title and favicon will be fetched automatically.

**Request body:**
```json
{
  "url": "https://example.com"
}
```

**Response:** `201`
```json
{
  "id": "clx...",
  "url": "https://example.com",
  "title": "Example",
  "favicon": "...",
  "position": 0
}
```

### 6. Remove a Bookmark

**DELETE** `/api/bookmarks`

Remove a bookmark by its ID.

**Request body:**
```json
{
  "id": "clx..."
}
```

**Response:**
```json
{ "success": true }
```

### 7. Post a Comment

**POST** `/api/comments`

Add a comment to a product (identified by domain).

**Request body:**
```json
{
  "domain": "example.com",
  "content": "Great product!"
}
```

**Response:**
```json
{
  "id": "clx...",
  "content": "Great product!",
  "createdAt": "2026-02-27T...",
  "user": { "displayName": "...", "username": "..." }
}
```

### 8. Get Leaderboard

**GET** `/api/leaderboard?sort=all&range=all`

Fetch the public leaderboard. No authentication required.

**Query params:**
- `sort`: `all` | `hits` | `misses`
- `range`: `all` | `1d` | `1w` | `1m`

**Response:**
```json
[
  { "domain": "example.com", "title": "Example", "hits": 12, "misses": 3 }
]
```

### 9. Get Comments

**GET** `/api/comments?domain=example.com&page=0`

Fetch comments for a product. No authentication required.

**Response:**
```json
{ "comments": [...], "total": 5, "pageSize": 8 }
```

---

## CLI Tool (`productarena-cli`)

A command-line tool for interacting with the Product Arena API — vote on products, manage your Hits, Misses & TBD lists, manage bookmarks, explore leaderboards, and post comments, all from your terminal.

### Installation

Install globally from npm:

```bash
npm install -g productarena-cli
```

Or install from source:

```bash
git clone https://github.com/haofanwang/productarena-cli.git
cd productarena-cli
npm install
npm link
```

### Quick Start

```bash
# 1. Set your API key (get one at https://www.productarena.co/docs)
productarena config set-key pa_your_key_here

# 2. Verify it works
productarena whoami

# 3. Explore the leaderboard
productarena leaderboard
```

### Configuration

```bash
# Save your API key
productarena config set-key pa_xxxx

# Set a custom base URL
productarena config set-url https://www.productarena.co

# View current config
productarena config show
```

Environment variables (override saved config):
- `PRODUCTARENA_API_KEY` — overrides the saved API key
- `PRODUCTARENA_BASE_URL` — overrides the saved base URL

### Products

```bash
# List your Hits, Misses & TBD
productarena products list

# Filter by type
productarena products list --type hits
productarena products list --type tbd

# Add a product to Hits
productarena products add https://cursor.com --type hits

# Add a product to TBD
productarena products add https://example.com --type tbd

# Add with a category
productarena products add https://suno.ai --type hits --category audio

# Remove a product
productarena products remove https://cursor.com

# Remove by domain
productarena products remove cursor.com --by domain
```

### Bookmarks

```bash
# List your bookmarks
productarena bookmarks list

# Bookmark a URL
productarena bookmarks add https://example.com

# Remove a bookmark by ID
productarena bookmarks remove clx...
```

### Leaderboard

```bash
# Full leaderboard
productarena leaderboard

# Top hits this week
productarena leaderboard --sort hits --range 1w

# Filter by category, show top 10
productarena leaderboard --category agent --limit 10
```

### Comments

```bash
# View comments for a product
productarena comments list cursor.com

# Post a comment
productarena comments add cursor.com "Amazing code editor!"
```

### Other Commands

```bash
# Platform stats
productarena stats

# Test your API key (shows hits, misses, and tbd counts)
productarena whoami

# Version info
productarena --version
```

### Global Options

Every command supports these flags:

```bash
# Override API key for a single command
productarena --key pa_xxxx products list

# Override base URL
productarena --base-url https://www.productarena.co leaderboard
```

---

## Rate Limits

API requests are limited to **60 requests per minute** per API key. Read-only endpoints (GET) do not require authentication.

## Example: cURL

```bash
# Add a hit
curl -X POST "https://www.productarena.co/api/products" \
  -H "x-api-key: pa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","arenaType":"hits"}'

# Add a TBD
curl -X POST "https://www.productarena.co/api/products" \
  -H "x-api-key: pa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","arenaType":"tbd"}'

# Remove a product by domain
curl -X DELETE "https://www.productarena.co/api/products" \
  -H "x-api-key: pa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com"}'

# Add a bookmark
curl -X POST "https://www.productarena.co/api/bookmarks" \
  -H "x-api-key: pa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

# Get bookmarks
curl -H "x-api-key: pa_your_key" \
  "https://www.productarena.co/api/bookmarks"

# Remove a bookmark
curl -X DELETE "https://www.productarena.co/api/bookmarks" \
  -H "x-api-key: pa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"id":"clx..."}'

# Post a comment
curl -X POST "https://www.productarena.co/api/comments" \
  -H "x-api-key: pa_your_key" \
  -H "Content-Type: application/json" \
  -d '{"domain":"example.com","content":"Great product!"}'

# Get leaderboard (no auth)
curl "https://www.productarena.co/api/leaderboard?sort=all&range=1w"

# Get comments (no auth)
curl "https://www.productarena.co/api/comments?domain=example.com&page=0"
```

## Example: CLI

```bash
# Configure
productarena config set-key pa_your_key

# Add a product as a Hit
productarena products add https://cursor.com --type hits

# Add a product as TBD
productarena products add https://example.com --type tbd

# List your products
productarena products list

# Add a bookmark
productarena bookmarks add https://example.com

# List bookmarks
productarena bookmarks list

# View leaderboard
productarena leaderboard --sort hits --range 1w

# Post a comment
productarena comments add cursor.com "Love this editor!"

# Platform stats
productarena stats
```