API Reference

Overview

The Unveil API will provide RESTful endpoints for programmatic scanning and analysis. This enables integration with CI/CD pipelines, due diligence workflows, and automated monitoring systems.

Scan Endpoint

Request Body

{
  "url": "https://example.com",
  "options": {
    "waitForSelector": ".main-content",  // optional
    "timeout": 30000,                     // optional, ms
    "userAgent": "custom-agent"           // optional
  }
}

Response

{
  "id": "scan_abc123",
  "status": "complete",
  "url": "https://example.com",
  "domain": "example.com",
  "createdAt": "2024-01-15T10:30:00Z",
  "score": 78,
  "verdict": "legitimate",
  "verdictLabel": "Appears Legitimate",
  ...
}

Response Schema

The complete scan response includes the following structure:

interface ScanReport {
  id: string;
  url: string;
  domain: string;
  createdAt: string;
  status: "pending" | "scanning" | "complete" | "error";
  score: number;                    // 0-100
  verdict: "legitimate" | "suspicious" | "likely-fake" | "insufficient-data";
  verdictLabel: string;
  summaryBullets: string[];
  
  detections: {
    framework: string | null;       // React, Vue, etc.
    cms: string | null;             // WordPress, Shopify, etc.
    analytics: string[];            // Google Analytics, Segment, etc.
    web3: string[];                 // MetaMask, WalletConnect, etc.
    hosting: string[];              // Vercel, Netlify, etc.
  };
  
  network: {
    domains: string[];              // Connected domains
    calls: NetworkCall[];           // Individual requests
  };
  
  security: {
    tls: {
      version: string;              // TLS 1.3, etc.
      cipher: string;
      valid: boolean;
      issuer: string;
      expiresAt: string;
    };
    hsts: boolean;
    headers: {
      contentSecurityPolicy: boolean;
      xFrameOptions: boolean;
      xContentTypeOptions: boolean;
      referrerPolicy: boolean;
      permissionsPolicy: boolean;
    };
  };
  
  evidence: {
    markers: EvidenceMarker[];
    notes: string[];
  };
}

Error Handling

Rate Limits