Caspori API

Build powerful cybersecurity integrations with the Caspori API. Scan domains, investigate threats, assess compliance, explore digital footprints, and isolate web browsing sessions.

Getting your API key

Sign in to api.caspori.com and navigate to your dashboard settings to generate an API key.

Available Modules

ModuleBaseDescription
Authenticationapi.caspori.comUser auth, token exchange, profile
Domain Securitydomain.caspori.comDomain scanning and vulnerability reports
Exploreexplore.caspori.comEmail, username, phone, and footprint investigations
Compliancecompliance.caspori.comFramework assessments and compliance reports
Threat Intelligencethreat.caspori.comIP, domain, URL, and hash threat lookups
Remote Browser (RBI)rbi.caspori.comIsolated browser sessions via WebSocket

Authentication

The Caspori API uses two authentication methods depending on the context.

API Key Authentication

For server-to-server integrations, include your API key in the X-Api-Key header with every request.

HTTP Header
X-Api-Key: your_api_key_here

User Token Authentication (Bearer)

For user-facing integrations, obtain a JWT by exchanging a Firebase ID token. The flow works like this:

  1. User signs in via Firebase Authentication
  2. Send the Firebase ID token to POST /v1/auth/exchange
  3. Receive a Caspori JWT access token and refresh token
  4. Include the JWT in the Authorization header as a Bearer token
HTTP Header
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Token Expiry

Access tokens expire after 1 hour. Use the /v1/auth/refresh endpoint to obtain a new token without re-authenticating.

Base URL

All API requests are made over HTTPS. Each module has its own subdomain.

Base URLs
# Core API (auth, plans, subscriptions, usage)
https://api.caspori.com/v1

# Domain Security
https://domain.caspori.com/v1

# Explore (OSINT)
https://explore.caspori.com/v1

# Compliance
https://compliance.caspori.com/v1

# Threat Intelligence
https://threat.caspori.com/v1

# Remote Browser Isolation
https://rbi.caspori.com

Rate Limits

Rate limits vary by plan. When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header.

PlanRequests / minuteScans / dayExplore / day
Free 30510
Starter 12050100
Pro 6005001,000
Enterprise CustomCustomCustom

Rate limit headers are included in every response:

Response Headers
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 1712678400

Error Format

All error responses follow the RFC 7807 Problem Details standard.

JSON
{
  "type": "https://api.caspori.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded 120 requests per minute. Please wait before retrying.",
  "instance": "/v1/scans"
}

Common Error Codes

400Bad Request. The request body is malformed or missing required fields.
401Unauthorized. Missing or invalid authentication credentials.
403Forbidden. Valid credentials but insufficient permissions for this resource.
404Not Found. The requested resource does not exist.
409Conflict. The resource already exists or there is a state conflict.
422Unprocessable Entity. Validation failed on one or more fields.
429Too Many Requests. Rate limit exceeded.
500Internal Server Error. Something went wrong on our end.
503Service Unavailable. The service is temporarily down for maintenance.

Authentication API

Exchange Firebase tokens, manage sessions, and retrieve user profiles. All auth endpoints live on api.caspori.com.

POST /v1/auth/exchange Exchange Firebase token for Caspori JWT
Description

Exchanges a Firebase ID token for a Caspori access token and refresh token. This is the primary entry point for user authentication.

Authentication
No auth required
Request Body
ParameterTypeRequiredDescription
firebase_token string Required The Firebase ID token obtained from client-side Firebase Auth
Response
JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
  "token_type": "Bearer",
  "expires_in": 3600
}
Errors
400Missing or invalid firebase_token field
401Firebase token is expired or invalid
Examples
curl -X POST https://api.caspori.com/v1/auth/exchange \
  -H "Content-Type: application/json" \
  -d '{
    "firebase_token": "eyJhbGciOiJSUzI1NiIs..."
  }'
const response = await fetch("https://api.caspori.com/v1/auth/exchange", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    firebase_token: "eyJhbGciOiJSUzI1NiIs..."
  })
});

const { access_token, refresh_token } = await response.json();
POST /v1/auth/refresh Refresh an expired access token
Description

Uses a refresh token to obtain a new access token without requiring the user to re-authenticate with Firebase.

Authentication
No auth required
Request Body
ParameterTypeRequiredDescription
refresh_token string Required The refresh token from the exchange response
Response
JSON
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}
Errors
400Missing refresh_token field
401Refresh token is expired or revoked
Examples
curl -X POST https://api.caspori.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{ "refresh_token": "dGhpcyBpcyBhIHJlZnJl..." }'
const response = await fetch("https://api.caspori.com/v1/auth/refresh", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    refresh_token: "dGhpcyBpcyBhIHJlZnJl..."
  })
});

const { access_token } = await response.json();
GET /v1/auth/me Get authenticated user profile
Description

Returns the profile of the currently authenticated user, including plan details and account metadata.

Authentication
Bearer token required
Response
JSON
{
  "id": "usr_a1b2c3d4",
  "email": "[email protected]",
  "display_name": "Jane Developer",
  "plan": "pro",
  "created_at": "2025-01-15T10:30:00Z",
  "email_verified": true
}
Errors
401Missing or invalid Bearer token
Examples
curl https://api.caspori.com/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
const response = await fetch("https://api.caspori.com/v1/auth/me", {
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

const user = await response.json();
POST /v1/auth/logout Revoke current session
Description

Revokes the current access token and its associated refresh token. The tokens become invalid immediately.

Authentication
Bearer token required
Response
JSON
{
  "message": "Session revoked successfully"
}
Examples
curl -X POST https://api.caspori.com/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
await fetch("https://api.caspori.com/v1/auth/logout", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

Plans & Subscriptions

Retrieve available plans and check the current user's subscription status.

GET /v1/plans List all available plans
Description

Returns all available subscription plans with pricing, limits, and included features.

Authentication
API key or Bearer token
Response
JSON
{
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "price_monthly": 0,
      "limits": {
        "scans_per_day": 5,
        "explore_per_day": 10,
        "requests_per_minute": 30
      },
      "features": ["domain_scan", "threat_lookup"]
    },
    {
      "id": "pro",
      "name": "Pro",
      "price_monthly": 49,
      "limits": {
        "scans_per_day": 500,
        "explore_per_day": 1000,
        "requests_per_minute": 600
      },
      "features": ["domain_scan", "threat_lookup", "explore", "compliance", "rbi"]
    }
  ]
}
Examples
curl https://api.caspori.com/v1/plans \
  -H "X-Api-Key: your_api_key"
const response = await fetch("https://api.caspori.com/v1/plans", {
  headers: { "X-Api-Key": "your_api_key" }
});

const { plans } = await response.json();
GET /v1/subscriptions/me Get current subscription
Description

Returns the authenticated user's active subscription, including plan details, billing period, and renewal date.

Authentication
Bearer token required
Response
JSON
{
  "plan": "pro",
  "status": "active",
  "current_period_start": "2026-03-01T00:00:00Z",
  "current_period_end": "2026-04-01T00:00:00Z",
  "cancel_at_period_end": false
}
Examples
curl https://api.caspori.com/v1/subscriptions/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
const response = await fetch("https://api.caspori.com/v1/subscriptions/me", {
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

const subscription = await response.json();

Domain Security API

Scan domains for vulnerabilities, misconfigurations, and security issues. All domain endpoints live on domain.caspori.com.

POST /v1/scans Trigger a new domain scan
Description

Initiates a comprehensive security scan for the specified domain. Scans run asynchronously. Poll the scan status endpoint to check progress.

Authentication
Bearer token or API key
Request Body
ParameterTypeRequiredDescription
domain string Required The domain to scan (e.g., "example.com")
scan_type string Optional Type of scan: "full", "quick", "ssl", "dns". Defaults to "full"
Response
JSON
{
  "id": "scan_7f8a9b0c",
  "domain": "example.com",
  "status": "pending",
  "scan_type": "full",
  "created_at": "2026-04-09T14:30:00Z",
  "estimated_duration": 120
}
Errors
400Invalid domain format
422Domain is not resolvable
429Daily scan limit reached
Examples
curl -X POST https://domain.caspori.com/v1/scans \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "scan_type": "full"
  }'
const response = await fetch("https://domain.caspori.com/v1/scans", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    domain: "example.com",
    scan_type: "full"
  })
});

const scan = await response.json();
console.log(`Scan started: ${scan.id}`);
GET /v1/scans/:id Get scan results
Description

Retrieves the current status and results of a domain scan. While the scan is running, the status will be "processing". Once complete, the full results are included.

Authentication
Bearer token or API key
URL Parameters
ParameterTypeRequiredDescription
id string Required The scan ID returned from the create scan endpoint
Response
JSON
{
  "id": "scan_7f8a9b0c",
  "domain": "example.com",
  "status": "completed",
  "score": 78,
  "grade": "B+",
  "findings": {
    "critical": 0,
    "high": 2,
    "medium": 5,
    "low": 8,
    "info": 12
  },
  "categories": {
    "ssl": { "score": 90, "issues": 1 },
    "headers": { "score": 65, "issues": 4 },
    "dns": { "score": 85, "issues": 2 }
  },
  "completed_at": "2026-04-09T14:32:15Z"
}
Examples
curl https://domain.caspori.com/v1/scans/scan_7f8a9b0c \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
const response = await fetch(`https://domain.caspori.com/v1/scans/${scanId}`, {
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

const scan = await response.json();

if (scan.status === "completed") {
  console.log(`Score: ${scan.score}, Grade: ${scan.grade}`);
}
GET /v1/scans/:id/report Download PDF report
Description

Downloads a detailed PDF report of the scan results. The scan must be completed before the report can be generated.

Authentication
Bearer token or API key
Response

Returns a PDF file with Content-Type: application/pdf.

Errors
404Scan not found
409Scan is still in progress
Examples
curl https://domain.caspori.com/v1/scans/scan_7f8a9b0c/report \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -o report.pdf
const response = await fetch(
  `https://domain.caspori.com/v1/scans/${scanId}/report`,
  {
    headers: {
      "Authorization": `Bearer ${accessToken}`
    }
  }
);

const blob = await response.blob();
// Save or display the PDF
POST /v1/assets Add a domain asset
Description

Adds a domain to your asset inventory. The domain must be verified before you can run recurring scans or access continuous monitoring.

Authentication
Bearer token or API key
Request Body
ParameterTypeRequiredDescription
domain string Required The domain to add (e.g., "example.com")
Response
JSON
{
  "id": "asset_d4e5f6",
  "domain": "example.com",
  "verified": false,
  "verification_method": "dns_txt",
  "verification_token": "caspori-verify=abc123def456",
  "created_at": "2026-04-09T15:00:00Z"
}
Examples
curl -X POST https://domain.caspori.com/v1/assets \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com" }'
const response = await fetch("https://domain.caspori.com/v1/assets", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ domain: "example.com" })
});

const asset = await response.json();
console.log(`Add TXT record: ${asset.verification_token}`);
POST /v1/assets/:id/verify Verify domain ownership
Description

Triggers verification of domain ownership by checking for the DNS TXT record. Add the verification token from the asset creation response to your domain's DNS records before calling this endpoint.

Authentication
Bearer token or API key
URL Parameters
ParameterTypeRequiredDescription
id string Required The asset ID
Response
JSON
{
  "id": "asset_d4e5f6",
  "domain": "example.com",
  "verified": true,
  "verified_at": "2026-04-09T15:05:00Z"
}
Errors
404Asset not found
422DNS TXT record not found or does not match
Examples
curl -X POST https://domain.caspori.com/v1/assets/asset_d4e5f6/verify \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
const response = await fetch(
  `https://domain.caspori.com/v1/assets/${assetId}/verify`,
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${accessToken}`
    }
  }
);

const result = await response.json();
console.log(`Verified: ${result.verified}`);

Explore API

Investigate emails, usernames, phone numbers, and digital footprints using OSINT techniques. All explore endpoints live on explore.caspori.com.

POST /v1/email/investigate Investigate an email address
Description

Performs an OSINT investigation on an email address. Returns associated accounts, breach history, social profiles, and reputation data.

Authentication
Bearer token or API key
Request Body
ParameterTypeRequiredDescription
email string Required The email address to investigate
Response
JSON
{
  "email": "[email protected]",
  "valid": true,
  "disposable": false,
  "reputation_score": 72,
  "breaches": [
    {
      "name": "ExampleBreach",
      "date": "2024-03-15",
      "data_types": ["email", "password"]
    }
  ],
  "profiles": [
    { "platform": "github", "url": "https://github.com/example" }
  ],
  "first_seen": "2019-06-12"
}
Errors
400Invalid email format
429Daily explore limit reached
Examples
curl -X POST https://explore.caspori.com/v1/email/investigate \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'
const response = await fetch("https://explore.caspori.com/v1/email/investigate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ email: "[email protected]" })
});

const data = await response.json();
console.log(`Breaches found: ${data.breaches.length}`);
POST /v1/username/investigate Investigate a username
Description

Searches for a username across platforms and services. Returns discovered profiles and associated information.

Authentication
Bearer token or API key
Request Body
ParameterTypeRequiredDescription
username string Required The username to investigate
Response
JSON
{
  "username": "johndoe42",
  "profiles": [
    {
      "platform": "github",
      "url": "https://github.com/johndoe42",
      "exists": true
    },
    {
      "platform": "twitter",
      "url": "https://twitter.com/johndoe42",
      "exists": true
    }
  ],
  "total_found": 7
}
Examples
curl -X POST https://explore.caspori.com/v1/username/investigate \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "johndoe42" }'
const response = await fetch("https://explore.caspori.com/v1/username/investigate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ username: "johndoe42" })
});

const data = await response.json();
POST /v1/phone/investigate Investigate a phone number
Description

Performs an OSINT investigation on a phone number. Returns carrier information, associated accounts, and risk assessment.

Authentication
Bearer token or API key
Request Body
ParameterTypeRequiredDescription
phone string Required Phone number in E.164 format (e.g., "+14155551234")
Response
JSON
{
  "phone": "+14155551234",
  "valid": true,
  "carrier": "T-Mobile",
  "type": "mobile",
  "country": "US",
  "risk_score": 15,
  "associated_profiles": 3
}
Examples
curl -X POST https://explore.caspori.com/v1/phone/investigate \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+14155551234" }'
const response = await fetch("https://explore.caspori.com/v1/phone/investigate", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ phone: "+14155551234" })
});

const data = await response.json();
POST /v1/footprint Generate digital footprint
Description

Generates a comprehensive digital footprint analysis by correlating data from email, username, and phone investigations. Provides a unified view of an identity's online presence.

Authentication
Bearer token or API key
Request Body
ParameterTypeRequiredDescription
email string Optional Email address to include in the footprint
username string Optional Username to include in the footprint
phone string Optional Phone number (E.164) to include in the footprint
Note

At least one of email, username, or phone must be provided.

Response
JSON
{
  "summary": {
    "total_accounts": 14,
    "total_breaches": 3,
    "risk_level": "medium",
    "exposure_score": 58
  },
  "accounts": [
    {
      "platform": "github",
      "identifier": "johndoe42",
      "url": "https://github.com/johndoe42",
      "source": "username"
    }
  ],
  "timeline": [
    { "date": "2019-06-12", "event": "First seen" },
    { "date": "2024-03-15", "event": "Data breach (ExampleBreach)" }
  ]
}
Examples
curl -X POST https://explore.caspori.com/v1/footprint \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "username": "johndoe42"
  }'
const response = await fetch("https://explore.caspori.com/v1/footprint", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    email: "[email protected]",
    username: "johndoe42"
  })
});

const footprint = await response.json();
console.log(`Total accounts: ${footprint.summary.total_accounts}`);

Compliance API

Assess domain compliance against industry frameworks and standards. All compliance endpoints live on compliance.caspori.com.

GET /v1/frameworks List compliance frameworks
Description

Returns all supported compliance frameworks with their IDs, names, and descriptions.

Authentication
API key or Bearer token
Response
JSON
{
  "frameworks": [
    {
      "id": "gdpr",
      "name": "GDPR",
      "description": "General Data Protection Regulation (EU)",
      "total_controls": 42
    },
    {
      "id": "soc2",
      "name": "SOC 2",
      "description": "Service Organization Control 2",
      "total_controls": 61
    },
    {
      "id": "iso27001",
      "name": "ISO 27001",
      "description": "Information Security Management",
      "total_controls": 93
    }
  ]
}
Examples
curl https://compliance.caspori.com/v1/frameworks \
  -H "X-Api-Key: your_api_key"
const response = await fetch("https://compliance.caspori.com/v1/frameworks", {
  headers: { "X-Api-Key": "your_api_key" }
});

const { frameworks } = await response.json();
GET /v1/compliance/:domain Get domain compliance status
Description

Returns the overall compliance status for a domain across all assessed frameworks.

Authentication
Bearer token or API key
URL Parameters
ParameterTypeRequiredDescription
domain string Required The domain to check compliance for
Response
JSON
{
  "domain": "example.com",
  "overall_score": 72,
  "frameworks": [
    {
      "id": "gdpr",
      "score": 80,
      "status": "partial",
      "controls_passed": 34,
      "controls_total": 42
    }
  ],
  "last_assessed": "2026-04-08T10:00:00Z"
}
Examples
curl https://compliance.caspori.com/v1/compliance/example.com \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
const domain = "example.com";
const response = await fetch(
  `https://compliance.caspori.com/v1/compliance/${domain}`,
  {
    headers: {
      "Authorization": `Bearer ${accessToken}`
    }
  }
);

const compliance = await response.json();
GET /v1/compliance/:domain/:framework Get framework-specific compliance
Description

Returns detailed compliance results for a specific domain and framework combination, including individual control statuses.

Authentication
Bearer token or API key
URL Parameters
ParameterTypeRequiredDescription
domain string Required The domain to check
framework string Required Framework ID (e.g., "gdpr", "soc2", "iso27001")
Response
JSON
{
  "domain": "example.com",
  "framework": "gdpr",
  "score": 80,
  "controls": [
    {
      "id": "gdpr-6.1",
      "name": "Lawfulness of Processing",
      "status": "pass",
      "details": "Privacy policy detected and accessible"
    },
    {
      "id": "gdpr-7.1",
      "name": "Conditions for Consent",
      "status": "fail",
      "details": "Cookie consent banner not detected"
    }
  ]
}
Examples
curl https://compliance.caspori.com/v1/compliance/example.com/gdpr \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
const response = await fetch(
  "https://compliance.caspori.com/v1/compliance/example.com/gdpr",
  {
    headers: {
      "Authorization": `Bearer ${accessToken}`
    }
  }
);

const result = await response.json();
const failed = result.controls.filter(c => c.status === "fail");
console.log(`Failed controls: ${failed.length}`);
POST /v1/compliance/report Generate compliance report
Description

Generates a detailed compliance report PDF for the specified domain and framework. The report includes all control assessments, recommendations, and remediation steps.

Authentication
Bearer token or API key
Request Body
ParameterTypeRequiredDescription
domain string Required The domain to generate the report for
framework string Required Framework ID
format string Optional "pdf" or "json". Defaults to "pdf"
Response

Returns a PDF or JSON report depending on the format parameter.

Examples
curl -X POST https://compliance.caspori.com/v1/compliance/report \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "framework": "gdpr"
  }' \
  -o compliance-report.pdf
const response = await fetch("https://compliance.caspori.com/v1/compliance/report", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    domain: "example.com",
    framework: "gdpr",
    format: "json"
  })
});

const report = await response.json();

Threat Intelligence API

Look up threat data for IPs, domains, URLs, file hashes, and email domains. All threat endpoints live on threat.caspori.com.

GET /v1/threat/ip/:ip IP threat lookup
Description

Returns threat intelligence data for an IP address, including reputation score, geolocation, associated threats, and blocklist status.

Authentication
Bearer token or API key
URL Parameters
ParameterTypeRequiredDescription
ip string Required IPv4 or IPv6 address
Response
JSON
{
  "ip": "203.0.113.42",
  "risk_score": 85,
  "risk_level": "high",
  "country": "US",
  "asn": "AS15169",
  "org": "Google LLC",
  "threats": ["malware_distribution", "brute_force"],
  "blocklists": ["spamhaus", "abuseipdb"],
  "last_seen": "2026-04-08T18:30:00Z"
}
Examples
curl https://threat.caspori.com/v1/threat/ip/203.0.113.42 \
  -H "X-Api-Key: your_api_key"
const ip = "203.0.113.42";
const response = await fetch(
  `https://threat.caspori.com/v1/threat/ip/${ip}`,
  {
    headers: { "X-Api-Key": "your_api_key" }
  }
);

const data = await response.json();
console.log(`Risk: ${data.risk_level} (${data.risk_score}/100)`);
GET /v1/threat/domain/:domain Domain threat lookup
Description

Returns threat intelligence data for a domain, including malware hosting history, phishing indicators, and domain age.

Authentication
Bearer token or API key
Response
JSON
{
  "domain": "suspicious-site.com",
  "risk_score": 92,
  "risk_level": "critical",
  "categories": ["phishing", "malware"],
  "registrar": "NameCheap",
  "created_date": "2026-03-28",
  "dns_records": {
    "a": ["203.0.113.42"],
    "mx": []
  }
}
Examples
curl https://threat.caspori.com/v1/threat/domain/suspicious-site.com \
  -H "X-Api-Key: your_api_key"
const response = await fetch(
  "https://threat.caspori.com/v1/threat/domain/suspicious-site.com",
  {
    headers: { "X-Api-Key": "your_api_key" }
  }
);

const data = await response.json();
POST /v1/threat/url Scan a URL for threats
Description

Submits a URL for threat analysis. Checks against known malicious URL databases, performs live analysis, and returns threat indicators.

Authentication
Bearer token or API key
Request Body
ParameterTypeRequiredDescription
url string Required The full URL to scan
Response
JSON
{
  "url": "https://suspicious-site.com/login",
  "safe": false,
  "risk_score": 95,
  "threats": ["phishing", "credential_harvesting"],
  "screenshot_url": "https://threat.caspori.com/screenshots/abc123.png",
  "final_url": "https://suspicious-site.com/login?redir=1",
  "redirects": 2
}
Examples
curl -X POST https://threat.caspori.com/v1/threat/url \
  -H "X-Api-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://suspicious-site.com/login" }'
const response = await fetch("https://threat.caspori.com/v1/threat/url", {
  method: "POST",
  headers: {
    "X-Api-Key": "your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://suspicious-site.com/login"
  })
});

const result = await response.json();
console.log(`Safe: ${result.safe}`);
GET /v1/threat/hash/:hash File hash lookup
Description

Checks a file hash (MD5, SHA-1, or SHA-256) against known malware databases and returns threat classification.

Authentication
Bearer token or API key
URL Parameters
ParameterTypeRequiredDescription
hash string Required MD5, SHA-1, or SHA-256 hash
Response
JSON
{
  "hash": "e3b0c44298fc1c149afbf4c8996fb924",
  "hash_type": "md5",
  "malicious": true,
  "malware_family": "Emotet",
  "threat_type": "trojan",
  "first_seen": "2025-11-20",
  "detections": 48,
  "total_engines": 72
}
Examples
curl https://threat.caspori.com/v1/threat/hash/e3b0c44298fc1c149afbf4c8996fb924 \
  -H "X-Api-Key: your_api_key"
const hash = "e3b0c44298fc1c149afbf4c8996fb924";
const response = await fetch(
  `https://threat.caspori.com/v1/threat/hash/${hash}`,
  {
    headers: { "X-Api-Key": "your_api_key" }
  }
);

const data = await response.json();
GET /v1/threat/email-domain/:domain Email domain reputation
Description

Checks the reputation of an email domain. Useful for detecting disposable email services, spam domains, and fraudulent email providers.

Authentication
Bearer token or API key
Response
JSON
{
  "domain": "tempmail.xyz",
  "disposable": true,
  "reputation_score": 12,
  "mx_valid": true,
  "spf": false,
  "dkim": false,
  "dmarc": false,
  "category": "disposable"
}
Examples
curl https://threat.caspori.com/v1/threat/email-domain/tempmail.xyz \
  -H "X-Api-Key: your_api_key"
const response = await fetch(
  "https://threat.caspori.com/v1/threat/email-domain/tempmail.xyz",
  {
    headers: { "X-Api-Key": "your_api_key" }
  }
);

const data = await response.json();
console.log(`Disposable: ${data.disposable}`);

Remote Browser Isolation (RBI) API

Create isolated browser sessions for safe web browsing. Sessions run in secure containers and stream rendered content via WebSocket. All RBI endpoints live on rbi.caspori.com.

POST /session/create Create an isolated browser session
Description

Creates a new isolated browser session. Returns a session ID and WebSocket URL for connecting to the remote browser. The session runs in a sandboxed container with no direct access to the user's network.

Authentication
Bearer token required
Request Body
ParameterTypeRequiredDescription
url string Optional Initial URL to navigate to
ttl number Optional Session time-to-live in seconds. Defaults to 300 (5 minutes)
viewport object Optional Viewport dimensions: { "width": 1280, "height": 720 }
Response
JSON
{
  "session_id": "sess_a1b2c3d4e5",
  "ws_url": "wss://rbi.caspori.com/ws/sess_a1b2c3d4e5",
  "expires_at": "2026-04-09T15:05:00Z",
  "status": "ready"
}
Errors
401Missing or invalid Bearer token
403RBI not available on current plan
429Concurrent session limit reached
Examples
curl -X POST https://rbi.caspori.com/session/create \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "ttl": 600
  }'
const response = await fetch("https://rbi.caspori.com/session/create", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    url: "https://example.com",
    ttl: 600
  })
});

const session = await response.json();
// Connect via WebSocket
const ws = new WebSocket(session.ws_url);
WS wss://rbi.caspori.com/ws/:session_id WebSocket protocol
Description

Connect to an active browser session via WebSocket. The connection streams rendered frames from the remote browser and accepts input events (mouse, keyboard, scroll) to control the session.

Client-to-Server Messages

JSON Messages
// Navigate to a URL
{ "type": "navigate", "url": "https://example.com" }

// Mouse click
{ "type": "click", "x": 400, "y": 300, "button": "left" }

// Keyboard input
{ "type": "keypress", "key": "Enter" }

// Scroll
{ "type": "scroll", "deltaX": 0, "deltaY": 100 }

// Type text
{ "type": "type", "text": "Hello world" }

Server-to-Client Messages

JSON Messages
// Frame update (binary data follows)
{ "type": "frame", "width": 1280, "height": 720 }

// URL changed
{ "type": "url_changed", "url": "https://example.com/page" }

// Session expiring soon
{ "type": "warning", "message": "Session expires in 60 seconds" }

// Session ended
{ "type": "session_ended", "reason": "ttl_expired" }
Example
JavaScript
const ws = new WebSocket("wss://rbi.caspori.com/ws/sess_a1b2c3d4e5");

ws.addEventListener("open", () => {
  // Navigate to a page
  ws.send(JSON.stringify({
    type: "navigate",
    url: "https://example.com"
  }));
});

ws.addEventListener("message", (event) => {
  if (typeof event.data === "string") {
    const msg = JSON.parse(event.data);

    if (msg.type === "url_changed") {
      console.log(`Navigated to: ${msg.url}`);
    }
  } else {
    // Binary frame data - render to canvas
    renderFrame(event.data);
  }
});

ws.addEventListener("close", () => {
  console.log("Session ended");
});

Usage & Quotas

Monitor your API usage and check remaining quotas. Usage endpoints live on api.caspori.com.

GET /v1/usage/me Get usage statistics
Description

Returns the current billing period usage for the authenticated user, broken down by module.

Authentication
Bearer token or API key
Response
JSON
{
  "period_start": "2026-04-01T00:00:00Z",
  "period_end": "2026-05-01T00:00:00Z",
  "usage": {
    "scans": { "used": 127, "limit": 500 },
    "explore": { "used": 43, "limit": 1000 },
    "threat_lookups": { "used": 892, "limit": 5000 },
    "compliance_reports": { "used": 5, "limit": 50 },
    "rbi_sessions": { "used": 12, "limit": 100 }
  }
}
Examples
curl https://api.caspori.com/v1/usage/me \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
const response = await fetch("https://api.caspori.com/v1/usage/me", {
  headers: {
    "Authorization": `Bearer ${accessToken}`
  }
});

const { usage } = await response.json();
console.log(`Scans: ${usage.scans.used}/${usage.scans.limit}`);
GET /v1/usage/check Check remaining quota
Description

Quick check to see if a specific operation can be performed within the current quota. Useful for pre-validating before making an expensive API call.

Authentication
Bearer token or API key
Query Parameters
ParameterTypeRequiredDescription
operation string Required Operation to check: "scan", "explore", "threat", "compliance", "rbi"
Response
JSON
{
  "allowed": true,
  "remaining": 373,
  "limit": 500,
  "resets_at": "2026-05-01T00:00:00Z"
}
Examples
curl "https://api.caspori.com/v1/usage/check?operation=scan" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..."
const response = await fetch(
  "https://api.caspori.com/v1/usage/check?operation=scan",
  {
    headers: {
      "Authorization": `Bearer ${accessToken}`
    }
  }
);

const quota = await response.json();

if (quota.allowed) {
  // Proceed with the scan
  console.log(`${quota.remaining} scans remaining`);
} else {
  console.log(`Quota exceeded. Resets at ${quota.resets_at}`);
}