Caspori API
Build powerful cybersecurity integrations with the Caspori API. Scan domains, investigate threats, assess compliance, explore digital footprints, and isolate web browsing sessions.
Sign in to api.caspori.com and navigate to your dashboard settings to generate an API key.
Available Modules
| Module | Base | Description |
|---|---|---|
| Authentication | api.caspori.com | User auth, token exchange, profile |
| Domain Security | domain.caspori.com | Domain scanning and vulnerability reports |
| Explore | explore.caspori.com | Email, username, phone, and footprint investigations |
| Compliance | compliance.caspori.com | Framework assessments and compliance reports |
| Threat Intelligence | threat.caspori.com | IP, domain, URL, and hash threat lookups |
| Remote Browser (RBI) | rbi.caspori.com | Isolated 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.
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:
- User signs in via Firebase Authentication
- Send the Firebase ID token to
POST /v1/auth/exchange - Receive a Caspori JWT access token and refresh token
- Include the JWT in the
Authorizationheader as a Bearer token
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
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.
# 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.
| Plan | Requests / minute | Scans / day | Explore / day |
|---|---|---|---|
| Free | 30 | 5 | 10 |
| Starter | 120 | 50 | 100 |
| Pro | 600 | 500 | 1,000 |
| Enterprise | Custom | Custom | Custom |
Rate limit headers are included in every response:
X-RateLimit-Limit: 120 X-RateLimit-Remaining: 117 X-RateLimit-Reset: 1712678400
Error Format
All error responses follow the RFC 7807 Problem Details standard.
{
"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
Authentication API
Exchange Firebase tokens, manage sessions, and retrieve user profiles. All auth endpoints live on api.caspori.com.
Exchanges a Firebase ID token for a Caspori access token and refresh token. This is the primary entry point for user authentication.
| Parameter | Type | Required | Description |
|---|---|---|---|
| firebase_token | string | Required | The Firebase ID token obtained from client-side Firebase Auth |
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"refresh_token": "dGhpcyBpcyBhIHJlZnJl...",
"token_type": "Bearer",
"expires_in": 3600
}
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();
Uses a refresh token to obtain a new access token without requiring the user to re-authenticate with Firebase.
| Parameter | Type | Required | Description |
|---|---|---|---|
| refresh_token | string | Required | The refresh token from the exchange response |
{
"access_token": "eyJhbGciOiJSUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}
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();
Returns the profile of the currently authenticated user, including plan details and account metadata.
{
"id": "usr_a1b2c3d4",
"email": "developer@example.com",
"display_name": "Jane Developer",
"plan": "pro",
"created_at": "2025-01-15T10:30:00Z",
"email_verified": true
}
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();
Revokes the current access token and its associated refresh token. The tokens become invalid immediately.
{
"message": "Session revoked successfully"
}
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.
Returns all available subscription plans with pricing, limits, and included features.
{
"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"]
}
]
}
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();
Returns the authenticated user's active subscription, including plan details, billing period, and renewal date.
{
"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
}
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.
Initiates a comprehensive security scan for the specified domain. Scans run asynchronously. Poll the scan status endpoint to check progress.
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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" |
{
"id": "scan_7f8a9b0c",
"domain": "example.com",
"status": "pending",
"scan_type": "full",
"created_at": "2026-04-09T14:30:00Z",
"estimated_duration": 120
}
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}`);
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The scan ID returned from the create scan endpoint |
{
"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"
}
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}`); }
Downloads a detailed PDF report of the scan results. The scan must be completed before the report can be generated.
Returns a PDF file with Content-Type: application/pdf.
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
Adds a domain to your asset inventory. The domain must be verified before you can run recurring scans or access continuous monitoring.
| Parameter | Type | Required | Description |
|---|---|---|---|
| domain | string | Required | The domain to add (e.g., "example.com") |
{
"id": "asset_d4e5f6",
"domain": "example.com",
"verified": false,
"verification_method": "dns_txt",
"verification_token": "caspori-verify=abc123def456",
"created_at": "2026-04-09T15:00:00Z"
}
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}`);
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Required | The asset ID |
{
"id": "asset_d4e5f6",
"domain": "example.com",
"verified": true,
"verified_at": "2026-04-09T15:05:00Z"
}
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.
Performs an OSINT investigation on an email address. Returns associated accounts, breach history, social profiles, and reputation data.
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Required | The email address to investigate |
{
"email": "target@example.com",
"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"
}
curl -X POST https://explore.caspori.com/v1/email/investigate \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \ -H "Content-Type: application/json" \ -d '{ "email": "target@example.com" }'
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: "target@example.com" }) }); const data = await response.json(); console.log(`Breaches found: ${data.breaches.length}`);
Searches for a username across platforms and services. Returns discovered profiles and associated information.
| Parameter | Type | Required | Description |
|---|---|---|---|
| username | string | Required | The username to investigate |
{
"username": "johndoe42",
"profiles": [
{
"platform": "github",
"url": "https://github.com/johndoe42",
"exists": true
},
{
"platform": "twitter",
"url": "https://twitter.com/johndoe42",
"exists": true
}
],
"total_found": 7
}
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();
Performs an OSINT investigation on a phone number. Returns carrier information, associated accounts, and risk assessment.
| Parameter | Type | Required | Description |
|---|---|---|---|
| phone | string | Required | Phone number in E.164 format (e.g., "+14155551234") |
{
"phone": "+14155551234",
"valid": true,
"carrier": "T-Mobile",
"type": "mobile",
"country": "US",
"risk_score": 15,
"associated_profiles": 3
}
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();
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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 |
At least one of email, username, or phone must be provided.
{
"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)" }
]
}
curl -X POST https://explore.caspori.com/v1/footprint \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \ -H "Content-Type: application/json" \ -d '{ "email": "target@example.com", "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: "target@example.com", 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.
Returns all supported compliance frameworks with their IDs, names, and descriptions.
{
"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
}
]
}
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();
Returns the overall compliance status for a domain across all assessed frameworks.
| Parameter | Type | Required | Description |
|---|---|---|---|
| domain | string | Required | The domain to check compliance for |
{
"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"
}
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();
Returns detailed compliance results for a specific domain and framework combination, including individual control statuses.
| Parameter | Type | Required | Description |
|---|---|---|---|
| domain | string | Required | The domain to check |
| framework | string | Required | Framework ID (e.g., "gdpr", "soc2", "iso27001") |
{
"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"
}
]
}
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}`);
Generates a detailed compliance report PDF for the specified domain and framework. The report includes all control assessments, recommendations, and remediation steps.
| Parameter | Type | Required | Description |
|---|---|---|---|
| domain | string | Required | The domain to generate the report for |
| framework | string | Required | Framework ID |
| format | string | Optional | "pdf" or "json". Defaults to "pdf" |
Returns a PDF or JSON report depending on the format parameter.
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.
Returns threat intelligence data for an IP address, including reputation score, geolocation, associated threats, and blocklist status.
| Parameter | Type | Required | Description |
|---|---|---|---|
| ip | string | Required | IPv4 or IPv6 address |
{
"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"
}
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)`);
Returns threat intelligence data for a domain, including malware hosting history, phishing indicators, and domain age.
{
"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": []
}
}
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();
Submits a URL for threat analysis. Checks against known malicious URL databases, performs live analysis, and returns threat indicators.
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Required | The full URL to scan |
{
"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
}
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}`);
Checks a file hash (MD5, SHA-1, or SHA-256) against known malware databases and returns threat classification.
| Parameter | Type | Required | Description |
|---|---|---|---|
| hash | string | Required | MD5, SHA-1, or SHA-256 hash |
{
"hash": "e3b0c44298fc1c149afbf4c8996fb924",
"hash_type": "md5",
"malicious": true,
"malware_family": "Emotet",
"threat_type": "trojan",
"first_seen": "2025-11-20",
"detections": 48,
"total_engines": 72
}
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();
Checks the reputation of an email domain. Useful for detecting disposable email services, spam domains, and fraudulent email providers.
{
"domain": "tempmail.xyz",
"disposable": true,
"reputation_score": 12,
"mx_valid": true,
"spf": false,
"dkim": false,
"dmarc": false,
"category": "disposable"
}
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.
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| 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 } |
{
"session_id": "sess_a1b2c3d4e5",
"ws_url": "wss://rbi.caspori.com/ws/sess_a1b2c3d4e5",
"expires_at": "2026-04-09T15:05:00Z",
"status": "ready"
}
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);
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
// 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
// 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" }
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.
Returns the current billing period usage for the authenticated user, broken down by module.
{
"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 }
}
}
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}`);
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.
| Parameter | Type | Required | Description |
|---|---|---|---|
| operation | string | Required | Operation to check: "scan", "explore", "threat", "compliance", "rbi" |
{
"allowed": true,
"remaining": 373,
"limit": 500,
"resets_at": "2026-05-01T00:00:00Z"
}
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}`); }