Documentation

Complete guide to using WebScope API and integrating website intelligence into your applications.

Quick Links

Getting Started

Quick Start
Get up and running with your first scan in minutes
Authentication
Learn how to authenticate your API requests
Rate Limits
Understanding request limits and concurrency

API Reference

Create Scan
Initiate a new website scan
Get Scan Results
Retrieve completed scan data
List Scans
Browse your scan history
Webhooks
Configure scan completion notifications

Analysis Lenses

SEO Analysis
Understanding SEO scan results
Security Check
Interpreting security findings
Performance Audit
Reading performance metrics
Tech Stack Detection
Technology identification data

Quick Start

Run WebScope locally with Docker, then open the frontend on port 3000 and the backend Swagger UI on 8000/docs.

cp .env.example .env
docker compose up --build

Authentication

API requests to /api/v1/* require a Bearer token.

Authorization: Bearer sk_test_...

Rate Limits

Rate limit status is returned via response headers. You can also call GET /api/v1/limits for your configured tier and concurrency limit.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1704153600

Create Scan

POST /api/v1/scans returns 202 Accepted and a scan_id you can poll for results.

Get Scan Results

Status: GET /api/v1/scans/{scan_id}
Full report: GET /api/v1/scans/{scan_id}/full

List Scans

List recent scans (paginated) via GET /api/v1/scans?limit=50&offset=0.

Webhooks

Webhook callbacks are planned. For now, poll scan status via GET /api/v1/scans/{scan_id} or fetch the full report when completed.

SEO Analysis

SEO lens extracts titles, meta descriptions, canonical URLs, headings, and social tags (OG/Twitter) when available.

Security Check

Security lens highlights verdicts and common hardening issues. See Security Checks for focused guidance.

Performance Audit

Performance lens summarizes request counts, page weight, and timing metrics (when HAR is available).

Tech Stack Detection

Tech lens lists detected technologies and categories. Browse Technology Pages for more context on common detections.

Troubleshooting

  • 401 Unauthorized: missing/invalid API key.
  • 429 Rate limited: slow down and retry after X-RateLimit-Reset.
  • 503: Cloudflare credentials are missing or invalid.

Environment Variables

Configure these environment variables for your frontend application:

VariableDescriptionDefaultRequired
WEBSCOPE_BACKEND_URLBackend API endpoint URLhttp://localhost:8000Yes
WEBSCOPE_API_KEYAPI key for server-side requests to backend(your API key)Yes
NEXT_PUBLIC_WEBSCOPE_API_KEYPublic API key for client-side requests (not recommended)(your public key)No

Code Examples

Create a Scan

curl -X POST https://api.webscope.dev/api/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

Get Scan Results

curl https://api.webscope.dev/api/v1/scans/SCAN_ID/full \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript/Node.js

const response = await fetch('https://api.webscope.dev/api/v1/scans', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ url: 'https://example.com' })
});

const { scan_id } = await response.json();

Python

import requests

response = requests.post(
    'https://api.webscope.dev/api/v1/scans',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={'url': 'https://example.com'}
)

scan_id = response.json()['scan_id']

Backend API Documentation

For complete API reference including all endpoints, request/response schemas, and authentication details, visit the backend Swagger UI:

/docs on port 8000(when running locally) or https://api.webscope.dev/docs in production

Frequently Asked Questions

How do I get an API key?

Sign up for a free account at webscope.dev to get your API key. Free tier includes 60 requests per minute.

What is the scan completion time?

Most scans complete within 10-30 seconds. Complex pages or slower websites may take longer.

Are scan results retained?

Free tier retains results for 7 days. Pro and Enterprise plans offer extended retention (90 days to unlimited).

Need Help Getting Started?

Check out our pricing plans or contact our support team for assistance.