API Reference

RivalEye 提供 REST API，讓你用程式碼查詢競品報告、觸發掃描，輕鬆整合到自己的工具中。

🔑 Authentication

所有 API 請求需在 Header 加入 API Key：

Authorization: Bearer re_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

前往設定頁面建立 API Key。每個 Key 每分鐘限制 60 次請求。

🌐 Base URL

https://rivaleye.biginttech.com/api/v1

📋 Endpoints

GET

/api/v1/competitors

列出所有我的競品

Response

{
  "data": [
    {
      "id": "uuid",
      "name": "Competitor Inc.",
      "url": "https://competitor.com",
      "twitter_handle": "competitor",
      "created_at": "2026-01-01T00:00:00Z"
    }
  ]
}

curl 範例

curl -X GET \
  https://rivaleye.biginttech.com/api/v1/competitors \
  -H "Authorization: Bearer re_live_your_key_here"

POST

/api/v1/competitors

新增競品

Request Body

{
  "name": "Competitor Inc.",       // required
  "url": "https://competitor.com", // required
  "twitter_handle": "competitor"   // optional
}

Response

{
  "data": {
    "id": "uuid",
    "name": "Competitor Inc.",
    "url": "https://competitor.com",
    "created_at": "2026-01-01T00:00:00Z"
  }
}

curl 範例

curl -X POST \
  https://rivaleye.biginttech.com/api/v1/competitors \
  -H "Authorization: Bearer re_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Competitor Inc.", "url": "https://competitor.com"}'

POST

/api/v1/competitors/:id/scan

觸發指定競品的掃描（立即抓取並生成報告）

Path Parameters

競品 UUID

Response

{
  "message": "Scan triggered for Competitor Inc.",
  "data": { ... }
}

curl 範例

curl -X POST \
  https://rivaleye.biginttech.com/api/v1/competitors/COMPETITOR_ID/scan \
  -H "Authorization: Bearer re_live_your_key_here"

GET

/api/v1/reports

查看競品報告列表

Query Parameters

competitorId	（可選）過濾特定競品的報告
limit	（可選）每次回傳筆數，預設 10，最大 100

Response

{
  "data": [
    {
      "id": "uuid",
      "competitor_id": "uuid",
      "summary": "AI 生成的變化摘要...",
      "created_at": "2026-01-01T00:00:00Z",
      "competitors": {
        "name": "Competitor Inc.",
        "url": "https://competitor.com"
      }
    }
  ],
  "total": 1
}

curl 範例

curl -X GET \
  "https://rivaleye.biginttech.com/api/v1/reports?competitorId=COMPETITOR_ID&limit=5" \
  -H "Authorization: Bearer re_live_your_key_here"

⚡ Rate Limits

限制	說明
60 req/min	每個 API Key 每分鐘最多 60 次請求
5	每個帳號最多追蹤 5 個競品

超過 rate limit 時，API 回傳 429 Too Many Requests。

❌ Error Responses

HTTP Status	說明
401	API Key 無效或缺少
403	方案限制（Trial 過期等）
404	資源不存在
429	Rate limit 超過
500	伺服器錯誤

← 前往設定頁面建立 API Key