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://www.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
GET /api/tools	No	120 requests/minute
GET /api/battle	No	120 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://www.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

Tools Database

Free — No Auth Required

Access Spyglass's competitor intelligence database programmatically. Get structured data on 126+ SaaS tools across 16 categories — pricing, features, categories, and competitive positioning. Perfect for building comparison widgets, market research tools, or enriching your own app with competitive data.

GET /api/tools List all tools

Query Parameters

Parameter	Type	Required	Description
category	string	Optional	Filter by category (e.g. "Analytics", "CRM", "Design", "Development")
search	string	Optional	Search by name, category, or description (case-insensitive)
sort	string	Optional	Sort order: "name" (default) or "category"
limit	integer	Optional	Max results to return (defaults to all)
offset	integer	Optional	Results offset for pagination (default 0)

Response

{
  "total": 126,
  "offset": 0,
  "limit": 10,
  "categories": [
    "AI & ML", "Analytics", "CRM", "Communication",
    "Customer Support", "Data & BI", "Design",
    "Development", "E-commerce", "Finance",
    "HR & Recruiting", "Marketing", "Productivity",
    "Security"
  ],
  "tools": [
    {
      "n": "Linear",
      "u": "https://linear.app",
      "c": "Project Management",
      "m": "Freemium",
      "p": "$0",
      "f": true,
      "d": "Developer-first project management...",
      "k": "Blazing speed, purpose-built...",
      "e": "Keyboard-first UI, cycles...",
      "t": "Engineering teams at startups..."
    }
  ]
}

Example: Search

curl "https://www.spyglassci.com/api/tools?search=linear&limit=5"

Example: By Category

curl "https://www.spyglassci.com/api/tools?category=CRM&sort=name"

Tool Object Schema

Field	Type	Description
n	string	Tool name
u	string	Tool website URL
c	string	Category (e.g. "CRM", "Analytics", "Design")
m	string	Monetization model (e.g. "Freemium", "Subscription", "Free")
p	string	Starting price (e.g. "$29/mo", "Free", "Contact")
f	boolean	Whether the tool offers a free tier
d	string	Short description (1-2 sentences)
k	string	Key differentiator
e	string	Key features (comma-separated)
t	string	Target audience description

Use Cases

Build custom comparison widgets — Use the tools data to power your own "Tool A vs Tool B" comparison pages.
Market research dashboards — Pull category data to analyze competitive landscapes programmatically.
Enrich your SaaS with CI data — Embed Spyglass tool data in your own product's admin panels or dashboards.
Automated monitoring scripts — Use the API to periodically check tool data for your own monitoring pipelines.

Battle Compare

Free — No Auth Required

Compare any two SaaS tools side-by-side. Returns full tool profiles, pricing comparison, competitive analysis, and links to the OG image and interactive battle page. Perfect for building custom comparison widgets, dashboards, or enriching SaaS directories with comparison data.

GET /api/battle?tool1=Linear&tool2=Jira Compare two tools

Query Parameters

Parameter	Type	Required	Description
tool1	string	Required	Name of the first tool (exact or partial match supported)
tool2	string	Required	Name of the second tool (exact or partial match supported)

Response

{
  "tool1": {
    "name": "Linear",
    "url": "https://linear.app",
    "category": "Project Management",
    "pricing_model": "Freemium",
    "starting_price": "$0",
    "free_tier": true,
    "description": "Developer-first project management...",
    "differentiator": "Blazing speed for engineering teams",
    "features": "Keyboard-first UI, cycles, roadmaps...",
    "target_audience": "Engineering teams at startups..."
  },
  "tool2": { ... },
  "comparison": {
    "same_category": true,
    "free_tier": { "tool1": true, "tool2": true },
    "pricing": {
      "tool1": { "model": "Freemium", "starting_price": "$0", "numeric": 0 },
      "tool2": { "model": "Freemium", "starting_price": "$0", "numeric": 0 },
      "difference_percent": 0,
      "cheaper": "equal"
    },
    "differentiators": {
      "tool1": "Blazing speed...",
      "tool2": "Most powerful issue tracking..."
    },
    "feature_overlap": {
      "overlapping_count": 5,
      "overlapping": ["roadmaps","integrations","...],
      "unique_to_tool1": ["Keyboard-first UI",...],
      "unique_to_tool2": ["Advanced permissions",...],
      "tool1_total": 8,
      "tool2_total": 12,
      "overlap_percent": 33
    },
    "analysis": [
      "Category: Both compete in Project Management.",
      "Pricing: Same starting price — $0/mo each.",
      "Free tier: Both offer free tiers — risk-free to evaluate both.",
      "Feature overlap: 5 shared features (33% overlap). 8 tracked for Linear, 12 for Jira."
    ],
    "verdict": "Both have free tiers — try both before committing. Same starting price: $0/mo. Linear best for: Engineering teams at startups. Jira best for: Enterprise product teams."
  },
  "links": {
    "og_image": "https://www.spyglassci.com/api/og-battle?tool1=Linear&tool2=Jira",
    "battle_url": "https://www.spyglassci.com/battle?tool1=Linear&tool2=Jira"
  },
  "request": {
    "timestamp": "2026-05-13T12:00:00Z",
    "query": { "tool1": "Linear", "tool2": "Jira" }
  }
}

Example: Compare Notion vs Confluence

curl "https://www.spyglassci.com/api/battle?tool1=Notion&tool2=Confluence"

Example: Partial match

curl "https://www.spyglassci.com/api/battle?tool1=slack&tool2=teams"

Error Responses

Returns 400 if either parameter is missing. Returns 404 if a tool name cannot be matched. Returns 400 if both tools resolve to the same entry.

Use Cases

Build custom comparison widgets — Use the battle API to power your own "Tool A vs Tool B" comparison pages or embeddable widgets.
SaaS directory enrichment — Pull comparison data to add "vs" pages to your own SaaS discovery product.
Market research automation — Programmatically compare pricing, features, and positioning across your competitive landscape.
Slack bots and internal tools — Build `/compare` commands that pull real-time comparison data from Spyglass.

Suggest a Tool

Help us grow our tools database. If a tool is missing from our comparison engine, submit it via this endpoint. Submissions are reviewed and added to the database.

POST /api/suggest-tool Submit a missing tool for review

Request Body (JSON)

Field	Type	Required	Description
name	string	Required	Tool name (max 200 chars)
url	string	Optional	Tool website URL (max 500 chars)
category	string	Optional	Tool category (e.g. Analytics, CRM, max 100 chars)
price	string	Optional	Starting price (max 50 chars)

Example Request

curl -X POST https://www.spyglassci.com/api/suggest-tool \
  -H "Content-Type: application/json" \
  -d '{"name":"Notion","url":"https://notion.so","category":"Productivity","price":"$0"}'

Success Response

{
  "ok": true,
  "message": "Tool suggestion received."
}

Error Response

Returns 400 if the name field is missing.

All submissions are stored and reviewed periodically. Quality suggestions are added to our public tools database and become available via /api/tools and /api/battle.

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://www.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