API Documentation

Integrate RivalScraper into your workflow. Manage competitors, fetch alerts, and trigger scans programmatically.

Authentication

All API requests require a Bearer token. Generate one from Settings → Browser Extension & API.

Authorization: Bearer YOUR_TOKEN

Include this header in every request. Tokens do not expire but can be regenerated (which invalidates the previous one).

Plan Requirements

API token access requires an Operator plan or above. Scout and Free plan users will receive a 403 error when using Bearer token authentication.

Rate Limits

API requests are rate-limited per user on a sliding 1-hour window. Limits vary by plan:

Plan	Requests / hour
Operator	100
Command	500

Every response includes standard rate-limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1709312400

When the limit is exceeded, you'll receive a 429 response with a Retry-After header indicating seconds to wait.

Competitors

GET/api/competitors

List all your tracked competitors with their tracking configurations.

Example Request

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://rivalscraper.com/api/competitors

Example Response

[
  {
    "id": "uuid",
    "name": "Competitor Store",
    "url": "https://example.com",
    "platform": "shopify",
    "created_at": "2025-01-01T00:00:00Z",
    "tracking_configs": [...]
  }
]

POST/api/competitors

Add a new competitor to track. Requires name and URL. Platform is auto-detected if not provided.

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Acme Store","url":"https://acme.com","platform":"shopify"}' \
  https://rivalscraper.com/api/competitors

Example Response

{
  "id": "uuid",
  "name": "Acme Store",
  "url": "https://acme.com",
  "platform": "shopify",
  "created_at": "2025-01-01T00:00:00Z"
}

DELETE/api/competitors?id=UUID

Remove a competitor and all associated data (snapshots, alerts, products).

Example Request

curl -X DELETE \
  -H "Authorization: Bearer YOUR_TOKEN" \
  "https://rivalscraper.com/api/competitors?id=COMPETITOR_UUID"

Example Response

{ "success": true }

Alerts

GET/api/alerts

Fetch your alerts. Supports query params: read (true/false), limit, offset.

Example Request

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://rivalscraper.com/api/alerts?read=false&limit=20"

Example Response

[
  {
    "id": "uuid",
    "type": "price_change",
    "message": "Price dropped from $49 to $39",
    "read": false,
    "created_at": "2025-01-01T12:00:00Z",
    "competitor_id": "uuid"
  }
]

PATCH/api/alerts

Mark alerts as read. Pass an array of alert IDs.

Example Request

curl -X PATCH \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ids":["uuid1","uuid2"]}' \
  https://rivalscraper.com/api/alerts

Example Response

{ "updated": 2 }

Briefs

GET/api/briefs

Fetch your AI-generated intelligence briefs. Available on Operator and Command plans.

Example Request

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://rivalscraper.com/api/briefs

Example Response

[
  {
    "id": "uuid",
    "content": "## Daily Brief\n\n- Competitor A dropped prices...",
    "period": "daily",
    "generated_at": "2025-01-01T07:00:00Z"
  }
]

Scrape

POST/api/scrape

Trigger a manual scan for a competitor. Costs 1 scan credit. Returns scraped data.

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"competitorId":"COMPETITOR_UUID"}' \
  https://rivalscraper.com/api/scrape

Example Response

{
  "success": true,
  "products": 42,
  "snapshots": 42,
  "alerts": 3
}

Discover

POST/api/discover

Use AI to discover competitors based on a query. Returns a list of potential competitors with relevance scores.

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"organic skincare brands in Europe"}' \
  https://rivalscraper.com/api/discover

Example Response

{
  "results": [
    {
      "name": "Brand Name",
      "url": "https://example.com",
      "platform": "shopify",
      "relevance": 0.92,
      "reason": "Direct competitor in organic skincare"
    }
  ]
}

Analyze URL

POST/api/analyze-url

Analyze a URL to detect the e-commerce platform and extract store metadata before adding as a competitor.

Example Request

curl -X POST \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example-store.com"}' \
  https://rivalscraper.com/api/analyze-url

Example Response

{
  "platform": "shopify",
  "name": "Example Store",
  "description": "An online store selling...",
  "products_detected": true
}

Products

GET/api/competitors/:id/products

List all tracked products for a competitor. Supports pagination with limit (max 500) and offset.

Example Request

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://rivalscraper.com/api/competitors/COMPETITOR_UUID/products?limit=50&offset=0"

Example Response

{
  "data": [
    {
      "id": "uuid",
      "product_url": "https://example.com/product-1",
      "product_name": "Product One",
      "latest_price": 29.99,
      "currency": "USD",
      "in_stock": true,
      "variant_count": 3,
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "total": 142,
  "limit": 50,
  "offset": 0
}

Price History

GET/api/competitors/:id/prices

Fetch price snapshots for a competitor. History depth depends on your plan (7d Scout, 30d Operator, unlimited Command). Supports limit (max 1000), offset, and days filter.

Example Request

curl -H "Authorization: Bearer YOUR_TOKEN" \
  "https://rivalscraper.com/api/competitors/COMPETITOR_UUID/prices?days=30&limit=100"

Example Response

{
  "data": [
    {
      "id": "uuid",
      "product_url": "https://example.com/product-1",
      "product_name": "Product One",
      "price": 29.99,
      "currency": "USD",
      "captured_at": "2025-01-15T12:00:00Z"
    }
  ],
  "total": 850,
  "limit": 100,
  "offset": 0
}