Skip to main content

​
Overview

Track competitor brands, monitor changes, and receive alerts when competitors update messaging, visuals, or positioning. Base Endpoint: /v1/competitors Required Scopes:
  • read:competitors - Retrieve tracked competitors
  • write:competitors - Add/remove competitors
Pro/Agency Tier Only — Competitor tracking requires Pro or Agency subscription.

​
Add Competitor

Track a new competitor brand.

​
POST /v1/competitors

curl https://api.branddna.app/v1/competitors \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://competitor.com",
    "name": "Competitor Inc.",
    "check_frequency": "daily"
  }'

​
Request Parameters

ParameterTypeRequiredDescription
urlstringYesCompetitor website URL
namestringNoCompetitor name (auto-detected if omitted)
check_frequencystringNodaily, weekly, monthly (default: daily)
notify_on_changebooleanNoSend webhook on changes (default: true)

​
Response

{
  "data": {
    "id": "cmp_xyz789",
    "url": "https://competitor.com",
    "name": "Competitor Inc.",
    "check_frequency": "daily",
    "status": "active",
    "last_checked": null,
    "next_check": "2026-01-28T02:00:00Z",
    "created_at": "2026-01-27T14:23:45Z"
  }
}

​
List Competitors

Get all tracked competitors.

​
GET /v1/competitors

curl https://api.branddna.app/v1/competitors \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": [
    {
      "id": "cmp_xyz789",
      "url": "https://competitor.com",
      "name": "Competitor Inc.",
      "check_frequency": "daily",
      "status": "active",
      "last_checked": "2026-01-27T14:00:00Z",
      "changes_detected": 3,
      "created_at": "2026-01-20T10:00:00Z"
    }
  ]
}
Status Values:
  • active - Monitoring enabled
  • paused - Monitoring paused (manually or due to error)
  • failed - Unable to access website (403, 404, etc.)

​
Get Competitor Details

Retrieve competitor info and change history.

​
GET /v1/competitors/:id

curl https://api.branddna.app/v1/competitors/cmp_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "cmp_xyz789",
    "url": "https://competitor.com",
    "name": "Competitor Inc.",
    "status": "active",
    "last_checked": "2026-01-27T14:00:00Z",
    "snapshot": {
      "headline": "The Future of Project Management",
      "primary_color": "#3b82f6",
      "cta_text": "Start Free Trial",
      "meta_description": "Modern project management..."
    },
    "changes": [
      {
        "id": "chg_001",
        "detected_at": "2026-01-25T08:30:00Z",
        "type": "headline_change",
        "field": "headline",
        "old_value": "Best Project Management Software",
        "new_value": "The Future of Project Management"
      },
      {
        "id": "chg_002",
        "detected_at": "2026-01-20T12:00:00Z",
        "type": "visual_change",
        "field": "primary_color",
        "old_value": "#ef4444",
        "new_value": "#3b82f6"
      }
    ]
  }
}

​
Update Competitor

Modify competitor tracking settings.

​
PATCH /v1/competitors/:id

curl https://api.branddna.app/v1/competitors/cmp_xyz789 \
  -X PATCH \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "check_frequency": "weekly",
    "notify_on_change": false
  }'

​
Request Parameters

ParameterTypeDescription
namestringUpdate competitor name
check_frequencystringdaily, weekly, monthly
notify_on_changebooleanEnable/disable webhooks
statusstringactive or paused

​
Delete Competitor

Stop tracking a competitor.

​
DELETE /v1/competitors/:id

curl https://api.branddna.app/v1/competitors/cmp_xyz789 \
  -X DELETE \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Response

{
  "data": {
    "id": "cmp_xyz789",
    "deleted": true
  }
}

​
Detected Changes

​
Change Types

TypeDescriptionExample
headline_changeHomepage hero headline changed”Best Software” → “Future of Work”
cta_changePrimary CTA button text changed”Learn More” → “Start Free Trial”
visual_changeBrand colors or visuals updatedColor palette shift
pricing_changePricing page updatesPrice increase/decrease
feature_changeNew features addedNew integration announced
content_changeBlog posts, case studies added5 new blog posts

​
Get Changes

Retrieve recent changes across all competitors.

​
GET /v1/competitors/changes

curl "https://api.branddna.app/v1/competitors/changes?days=7" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Query Parameters

ParameterTypeDefaultDescription
daysinteger7Changes in last N days
typestring—Filter by change type
competitor_idstring—Filter by competitor

​
Response

{
  "data": [
    {
      "id": "chg_001",
      "competitor_id": "cmp_xyz789",
      "competitor_name": "Competitor Inc.",
      "detected_at": "2026-01-25T08:30:00Z",
      "type": "headline_change",
      "field": "headline",
      "old_value": "Best Project Management Software",
      "new_value": "The Future of Project Management",
      "url": "https://competitor.com"
    }
  ]
}

​
Quotas

Competitor tracking limits by tier:
TierMax CompetitorsCheck Frequency
Pro10Daily
Agency50Hourly
Need to track more competitors? Contact enterprise@branddna.app

​
Webhooks

Receive real-time notifications when competitors change:

​
Event: competitor.changed

{
  "event": "competitor.changed",
  "timestamp": "2026-01-25T08:30:00Z",
  "data": {
    "competitor_id": "cmp_xyz789",
    "competitor_name": "Competitor Inc.",
    "url": "https://competitor.com",
    "change": {
      "type": "headline_change",
      "field": "headline",
      "old_value": "Best Project Management Software",
      "new_value": "The Future of Project Management"
    }
  }
}
See Webhooks for setup.

​
Use Cases

Competitive Intelligence

Monitor competitor positioning shifts and messaging changes

Pricing Monitoring

Track competitor pricing updates and promotions

Feature Parity

Alert when competitors add new features

Market Trends

Identify patterns across multiple competitors
Next: Team Management API →