API Documentation

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header as a Bearer token.

⚠️ Keep your API keys secure - Never expose them in client-side code or public repositories

Authorization: Bearer YOUR_API_KEY

Get your API key from the Settings page.

Rate Limits

API calls are limited based on your subscription tier:

Free Tier

100

calls per month

Pro Tier

10,000

calls per month

When you exceed your limit, the API returns a 429 Too Many Requests response.

Competitors

Manage the competitors you're monitoring

GET /api/competitors

Retrieve all competitors you're monitoring

curl -X GET https://vigil-15.polsia.app/api/competitors \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://vigil-15.polsia.app/api/competitors",
    headers=headers
)
data = response.json()
print(data)

const response = await fetch(
  'https://vigil-15.polsia.app/api/competitors',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();
console.log(data);

Response

{
  "success": true,
  "competitors": [
    {
      "id": 1,
      "name": "Acme Corp",
      "website_url": "https://acme.com",
      "description": "Primary competitor",
      "active": true,
      "check_frequency_hours": 24,
      "last_checked_at": "2026-02-26T10:00:00Z",
      "created_at": "2026-02-20T08:00:00Z"
    }
  ],
  "usage": {
    "usage": 15,
    "limit": 100,
    "tier": "free"
  }
}

POST /api/competitors

Add a new competitor to monitor

Body Parameters

name string required

Competitor's name

website_url string required

URL to monitor

description string

Optional description

check_frequency_hours integer

How often to check (default: 24)

curl -X POST https://vigil-15.polsia.app/api/competitors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "website_url": "https://acme.com/pricing",
    "description": "Primary competitor in SaaS space"
  }'

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {
    "name": "Acme Corp",
    "website_url": "https://acme.com/pricing",
    "description": "Primary competitor in SaaS space"
}
response = requests.post(
    "https://vigil-15.polsia.app/api/competitors",
    headers=headers,
    json=data
)
print(response.json())

const response = await fetch(
  'https://vigil-15.polsia.app/api/competitors',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Acme Corp',
      website_url: 'https://acme.com/pricing',
      description: 'Primary competitor in SaaS space'
    })
  }
);
const data = await response.json();
console.log(data);

Changes

Track detected changes in competitor websites

GET /api/competitors/:id/changes

Get change history for a specific competitor

Query Parameters

limit integer

Number of changes to return (default: 50)

curl -X GET "https://vigil-15.polsia.app/api/competitors/1/changes?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://vigil-15.polsia.app/api/competitors/1/changes",
    headers=headers,
    params={"limit": 10}
)
print(response.json())

const response = await fetch(
  'https://vigil-15.polsia.app/api/competitors/1/changes?limit=10',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();
console.log(data);

Response

{
  "success": true,
  "changes": [
    {
      "id": 42,
      "competitor_id": 1,
      "change_type": "pricing",
      "severity": "high",
      "title": "Pricing increased by 20%",
      "description": "Pro plan increased from $49 to $59/month",
      "old_value": "$49/month",
      "new_value": "$59/month",
      "detected_at": "2026-02-26T09:15:00Z"
    }
  ],
  "usage": {
    "usage": 16,
    "limit": 100,
    "tier": "free"
  }
}

Reports

Access intelligence reports generated by Vigil

GET /api/reports

List all intelligence reports

curl -X GET https://vigil-15.polsia.app/api/reports \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://vigil-15.polsia.app/api/reports",
    headers=headers
)
print(response.json())

const response = await fetch(
  'https://vigil-15.polsia.app/api/reports',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();
console.log(data);

GET /api/reports/:id

Get a specific report by ID

curl -X GET https://vigil-15.polsia.app/api/reports/1 \
  -H "Authorization: Bearer YOUR_API_KEY"

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(
    "https://vigil-15.polsia.app/api/reports/1",
    headers=headers
)
print(response.json())

const response = await fetch(
  'https://vigil-15.polsia.app/api/reports/1',
  {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  }
);
const data = await response.json();
console.log(data);

Response

{
  "success": true,
  "report": {
    "id": 1,
    "title": "Weekly Intelligence Brief - Feb 26, 2026",
    "summary": "3 competitors made significant changes this week",
    "content": "Full report content with detailed analysis...",
    "report_type": "weekly",
    "created_at": "2026-02-26T08:00:00Z"
  }
}

Webhooks

Receive real-time notifications when events occur

Event Types

competitor_changed - When a competitor's website changes
new_report - When a new intelligence report is generated
pricing_update - When pricing changes are detected

Webhook Security

All webhook requests are signed with HMAC-SHA256. Verify the signature to ensure requests are from Vigil.

// Headers sent with each webhook
X-Webhook-Signature: 
X-Webhook-Timestamp: 

// Verify signature
const crypto = require('crypto');
const signature = req.headers['x-webhook-signature'];
const timestamp = req.headers['x-webhook-timestamp'];
const body = JSON.stringify(req.body);

const expectedSignature = crypto
  .createHmac('sha256', YOUR_WEBHOOK_SECRET)
  .update(`${timestamp}.${body}`)
  .digest('hex');

if (signature === expectedSignature) {
  // Valid webhook from Vigil
}

Webhook Payload Example

{
  "event_type": "competitor_changed",
  "data": {
    "competitor": {
      "id": 1,
      "name": "Acme Corp",
      "website_url": "https://acme.com"
    },
    "change": {
      "id": 42,
      "change_type": "pricing",
      "severity": "high",
      "title": "Pricing increased by 20%",
      "description": "Pro plan increased from $49 to $59/month",
      "detected_at": "2026-02-26T09:15:00Z"
    }
  },
  "timestamp": 1740560100000
}

Configure webhooks from the Settings page.