API Documentation

Integrate Spyglass competitive intelligence data into your own tools, dashboards, and workflows. The API is available on the Tracker and Command plans.

Overview

The Spyglass API allows you to programmatically access competitive intelligence reports, request new analysis, and integrate competitor insights into your own applications. All API endpoints are hosted at the same domain as the web application and return JSON responses.

Base URL

https://spyglassci.com/api

Content Type

All requests and responses use application/json. Include the Content-Type: application/json header on all requests with a body.

Authentication

API requests are authenticated using a Supabase access token. Include it as a Bearer token in the Authorization header:

Authorization: Bearer <your_supabase_access_token>

You can obtain an access token by signing in through the login page. The token is available from supabase.auth.getSession() in the client-side SDK. Tokens expire after 1 hour — use the refresh token to obtain a new one.

For public endpoints (Quick Scan, Roast), no authentication is required — but rate limits apply.

Rate Limiting

Rate limits vary by endpoint and authentication status:

Endpoint	Auth Required	Rate Limit
GET /api/reports/get	No (report ID as token)	60 requests/minute
POST /api/reports/request	No — email-based	5 requests/hour per IP
POST /api/scan	No	10 requests/session
POST /api/roast	No	10 requests/session
POST /api/billing/portal	Yes	10 requests/minute

Rate limit headers (X-RateLimit-Remaining) are included in responses from rate-limited endpoints. When exceeded, a 429 Too Many Requests response is returned.

Get Report

Tracker

Retrieve a complete competitive intelligence report by its ID. The report contains competitor analysis, feature comparisons, pricing data, and strategic recommendations.

GET /api/reports/get?id={report_id} Retrieve a report

Query Parameters

Parameter	Type	Required	Description
id	string	Required	The UUID of the report to retrieve

Response

{
  "id": "uuid",
  "user_id": "uuid",
  "status": "completed",
  "tier": "snapshot",
  "summary": {
    "competitors": ["url1", "url2", "url3"],
    "analysis_date": "2026-04-25",
    "overview": "Market positioning analysis...",
    "per_competitor": [...],
    "cross_analysis": {...},
    "recommendations": [...]
  },
  "created_at": "2026-04-25T12:00:00Z"
}

Request Report

Public

Submit competitor URLs for a full analysis report. Creates a pending report and returns a Stripe checkout URL for payment. After payment, the report is generated and stored.

POST /api/reports/request Request a new report

Request Body

Parameter	Type	Required	Description
name	string	Required	Your full name
email	string	Required	Your email address (used for account + delivery)
competitor_urls	string[]	Required	Array of competitor website URLs (up to 5)

Example Request

curl -X POST https://spyglassci.com/api/reports/request \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Founder",
    "email": "jane@myapp.com",
    "competitor_urls": [
      "https://competitor1.com",
      "https://competitor2.com"
    ]
  }'

Response

{
  "report_id": "uuid",
  "checkout_url": "https://buy.stripe.com/..."
}

Quick Scan

Free — No Auth Required

Perform a quick head-to-head positioning scan between your startup and a competitor. Returns pricing comparison, feature gaps, differentiation score, and strategic insight.

POST /api/scan Compare two companies

Request Body

Parameter	Type	Required	Description
your_url	string	Required	Your SaaS product URL
competitor_url	string	Required	Your competitor's URL

Roast Competitor

Free — No Auth Required

Get a quick competitive analysis of any SaaS product. Returns estimated size, top features, weaknesses, and a positioning score.

POST /api/roast Analyze any SaaS

Request Body

Parameter	Type	Required	Description
url	string	Required	The SaaS URL to analyze

Webhooks

Spyglass can send webhook notifications when key events occur. Webhooks are available on the Command plan. Currently supported event types:

Report Completed

Triggered when a requested competitive intelligence report finishes generation. Includes the report ID and a preview link.

{
  "event": "report.completed",
  "report_id": "uuid",
  "tier": "snapshot",
  "competitors": 3,
  "preview_url": "https://spyglassci.com/dashboard/report?id=uuid",
  "timestamp": "2026-04-25T12:00:00Z"
}

Competitor Change Detected

Triggered when a significant change is detected on a tracked competitor. Only sent for Tracker and Command plan subscribers.

{
  "event": "competitor.changed",
  "competitor_id": "uuid",
  "competitor_name": "Competitor Inc",
  "change_type": "pricing_change",
  "summary": "Changed pricing from $79/mo to $99/mo",
  "severity": "high",
  "timestamp": "2026-04-25T12:00:00Z"
}

Subscription Events

Triggered on subscription lifecycle changes: created, renewed, upgraded, downgraded, canceled, or payment failed.

Webhook Security

Webhook payloads are signed with an HMAC-SHA256 signature using your unique webhook secret. Verify the signature on your end to confirm the payload wasn't tampered with:

const crypto = require('crypto');

// Your webhook secret (provided when you configure webhooks)
const secret = 'whsec_your_secret_here';

const sig = request.headers['x-spyglass-signature'];
const payload = JSON.stringify(request.body);
const expected = crypto
  .createHmac('sha256', secret)
  .update(payload)
  .digest('hex');

if (sig !== expected) {
  // Reject — payload may be compromised
  return res.status(401).end();
}

// Process the webhook event

Webhook URLs are configured through the dashboard. You can set up to 3 webhook endpoints on the Command plan. All webhook delivery attempts have a 5-second timeout with 3 retries (exponential backoff).

Error Codes

Status	Code	Description
400	bad_request	Invalid request parameters or malformed JSON
401	not_authenticated	Missing or invalid authentication token
404	not_found	The requested resource was not found
405	method_not_allowed	HTTP method not supported for this endpoint
429	rate_limited	Too many requests — check Retry-After header
500	internal_error	Server error — try again later

Support

Questions about the API? We're here to help:

Email: hello@spyglassci.com
Dashboard: Access your account settings for API key management
Command tier includes priority API support with 24-hour response time