API Documentation — Find The Breach

01. Quick Start

Get your API key

Authenticate

Include your token in every request header.

Authorization: Bearer YOUR_API_KEY

Start a scan

POST to /api/scan with your target.

Get results

Poll /api/scan/{id} or connect via WebSocket for real-time updates.

02. Authentication

The API uses JWT Bearer tokens. Obtain a token via POST /api/auth/login, then include it in every request.

Access token: Expires in 60 minutes. Returned in the access_token field.

Refresh: Re-authenticate via POST /api/auth/login when the token expires. A 401 response indicates an expired or invalid token.

API Key (alternative): Generate a long-lived API key from the dashboard. Pass it as a Bearer token in the same way.

curl -X POST https://findthebreach.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"user@example.com","password":"s3cureP@ss"}'

# Response
{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": { "id": 1, "username": "user@example.com", "tier": "standard" }
}

Authentication Endpoints

Authenticate with username and password. Returns a JWT access token.

Request Body

{ "username": "user@example.com", "password": "your_password" }

Response 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": { "id": 1, "username": "user@example.com", "tier": "standard" }
}

Request Body

{ "username": "newuser@example.com", "password": "s3cureP@ss", "company": "Acme Corp" }

Response 201

{ "user": { "id": 42, "username": "newuser@example.com" }, "access_token": "eyJ..." }

Returns the authenticated user's profile, subscription tier, and usage stats.

Response 200

{ "id": 1, "username": "user@example.com", "tier": "standard", "scans_used": 12, "scans_limit": 50 }

Update the authenticated user's profile fields (company, notification preferences).

Request Body

{ "company": "New Corp", "notifications_email": true }

Change the authenticated user's password. Requires current password.

Request Body

{ "current_password": "old_pass", "new_password": "new_s3cure_pass" }

Sends a password reset link to the user's email address.

Request Body

{ "email": "user@example.com" }

Complete password reset using the token from the email link.

Request Body

{ "token": "abc123resettoken", "new_password": "new_s3cure_pass" }

Scanning Endpoints

Launch a new vulnerability scan against a target. Supports multiple scan types and notification options.

Request Body

{
  "target": "example.com",
  "scan_type": "full",
  "notify_email": true,
  "scanners": ["nmap", "nikto", "zap"],
  "schedule": null
}

Response 202

{ "scan_id": "sc_7f3a9b2e", "status": "queued", "estimated_time": "15 min" }

curl -X POST https://findthebreach.com/api/scan \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"target":"example.com","scan_type":"full"}'

import requests

resp = requests.post("https://findthebreach.com/api/scan",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"target": "example.com", "scan_type": "full"})
print(resp.json()["scan_id"])

const resp = await fetch("https://findthebreach.com/api/scan", {
  method: "POST",
  headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ target: "example.com", scan_type: "full" })
});
const { scan_id } = await resp.json();

body := bytes.NewBuffer([]byte(`{"target":"example.com","scan_type":"full"}`))
req, _ := http.NewRequest("POST", "https://findthebreach.com/api/scan", body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")
resp, _ := http.DefaultClient.Do(req)

Retrieve the current status, progress, findings, severity breakdown, and remediation guidance for a scan.

Path Parameters

id string, required — The scan ID returned from POST /api/scan.

Response 200

{
  "scan_id": "sc_7f3a9b2e",
  "target": "example.com",
  "status": "completed",
  "progress": 100,
  "findings_count": 7,
  "severity": { "critical": 1, "high": 2, "medium": 3, "low": 1 },
  "started_at": "2025-07-01T10:00:00Z",
  "completed_at": "2025-07-01T10:14:32Z"
}

List all scans for the authenticated user. Supports pagination and status filtering.

Query Parameters

page int, default 1

per_page int, default 20

status string — queued, running, completed, failed

Stop a running or queued scan. Partial results are retained.

Response 200

{ "scan_id": "sc_7f3a9b2e", "status": "stopped", "partial_results": true }

View the current scan queue, including your position and estimated wait time.

Response 200

{ "queue_length": 3, "your_position": 1, "estimated_wait": "2 min" }

Report Endpoints

Download the scan report as a PDF file. Returns binary data with Content-Type: application/pdf.

Get the scan report as rendered HTML, suitable for embedding or browser viewing.

Get an AI-generated executive summary with prioritized remediation steps.

Response 200

{
  "summary": "7 vulnerabilities found. 1 critical SQL injection in /login endpoint...",
  "risk_score": 8.2,
  "top_actions": ["Patch SQL injection in /login", "Update TLS to 1.3", "Add CSP headers"]
}

List all reports available in the client portal. Supports pagination and date range filters.

Asset Endpoints

List all monitored assets (domains, IPs, applications) in your account.

Response 200

{
  "assets": [
    { "id": "ast_1", "type": "domain", "value": "example.com", "last_scan": "2025-07-01T10:14:32Z", "risk_grade": "B" }
  ],
  "total": 5
}

Add a new asset to your monitored inventory.

Request Body

{ "type": "domain", "value": "newsite.com", "tags": ["production"] }

Update an existing asset's metadata, tags, or monitoring settings.

Remove an asset from monitoring. Historical scan data is retained for 90 days.

List all known vulnerabilities for a specific asset, including severity and remediation status.

Vulnerability Endpoints

List all discovered vulnerabilities across scans. Filter by severity, status, or asset.

Query Parameters

severity string — critical, high, medium, low, info

status string — open, resolved, false_positive, accepted

asset_id string — filter by asset

Get aggregate vulnerability statistics: counts by severity, trends over time, and mean-time-to-remediate.

Response 200

{ "total": 42, "critical": 3, "high": 10, "medium": 18, "low": 11, "mttr_hours": 72 }

Update the status of a vulnerability (resolve, mark as false positive, or accept risk).

Request Body

{ "status": "resolved", "note": "Patched in v2.3.1" }

Portal Endpoints

List all scan requests submitted through the client portal.

Submit a new scan request through the portal with target and preferred scan type.

Request Body

{ "target": "example.com", "scan_type": "pentest", "notes": "Focus on auth endpoints" }

Get a comprehensive attack surface overview: exposed services, subdomains, open ports, and risk scores.

Response 200

{
  "domains": 3, "subdomains": 12, "open_ports": 47,
  "exposed_services": ["HTTP", "SSH", "SMTP"],
  "risk_score": 6.8
}

Check if an email address appears in known data breaches. Returns breach sources and dates.

Response 200

{ "breached": true, "count": 3, "breaches": [{ "source": "Example Corp", "date": "2024-03", "data_types": ["email","password_hash"] }] }

Detect the technology stack of a target: web server, CMS, frameworks, JavaScript libraries, and CDN.

Response 200

{ "web_server": "nginx/1.25", "cms": "WordPress 6.4", "frameworks": ["React"], "cdn": "Cloudflare" }

Utility Endpoints

Look up a CVE by ID. Returns description, CVSS score, affected products, and references.

Response 200

{
  "cve_id": "CVE-2024-1234",
  "description": "Remote code execution in...",
  "cvss": 9.8,
  "severity": "critical",
  "published": "2024-06-15"
}

Analyze HTTP security headers and return a letter grade (A+ through F) with per-header breakdown.

Response 200

{ "grade": "B", "headers": { "Strict-Transport-Security": "present", "Content-Security-Policy": "missing", "X-Frame-Options": "present" } }

Returns an SVG security status badge for embedding in READMEs, dashboards, or websites. Shows current risk grade.

Submit a contact request or support inquiry programmatically.

Request Body

{ "name": "Jane Doe", "email": "jane@example.com", "subject": "API question", "message": "..." }

WebSocket

Connect via WebSocket to receive real-time scan progress, findings as they're discovered, and completion events.

Event Types

Event	Description
`progress`	Scan progress update (percentage, current scanner)
`finding`	New vulnerability discovered during scan
`scanner_start`	Individual scanner module started
`scanner_complete`	Individual scanner module finished
`scan_complete`	Entire scan finished — includes final summary

JavaScript Example

const ws = new WebSocket(`wss://findthebreach.com/ws/scan/${scanId}?token=${TOKEN}`);
ws.onmessage = (e) => {
  const data = JSON.parse(e.data);
  if (data.type === "progress") console.log(`${data.percent}% — ${data.scanner}`);
  if (data.type === "finding") console.log(`Found: ${data.title} [${data.severity}]`);
  if (data.type === "scan_complete") console.log("Done!", data.summary);
};

03. Try It Preview

Interactive API testing coming soon. Use the code examples above to test endpoints now.

04. Scan Types

Type	Description	~Duration	Tier
`full`	Complete vulnerability assessment — all scanners	15–45 min	Standard+
`quick`	Fast top-10 vulnerability check	2–5 min	Free+
`ports_only`	Port scan and service detection only	3–8 min	Free+
`web_only`	Web application vulnerabilities (XSS, SQLi, CSRF, etc.)	10–30 min	Standard+
`pentest`	Simulated penetration test with exploit validation	30–90 min	Premium
`recon`	Passive reconnaissance — OSINT, DNS, subdomain enumeration	5–15 min	Standard+

05. Scanners

NmapFree

Port scanning & service detection

NiktoFree

Web server misconfiguration scanner

OWASP ZAPStandard

Dynamic application security testing

NucleiStandard

Template-based vulnerability scanner

SSLyzeStandard

TLS/SSL configuration analysis

SQLMapPremium

Automated SQL injection detection

MetasploitPremium

Exploit validation framework

SubfinderFree

Subdomain discovery

WhatWebStandard

Technology fingerprinting

06. Error Codes

Code	Meaning	Common Cause
400	Bad Request	Missing required field or invalid JSON body
401	Unauthorized	Missing, expired, or invalid Bearer token
403	Forbidden	Insufficient tier or permissions for this endpoint
404	Not Found	Resource does not exist (invalid scan ID, asset ID, etc.)
429	Too Many Requests	Rate limit exceeded — check `X-RateLimit-Reset` header
500	Internal Server Error	Unexpected error — retry or contact support

All errors return a JSON body: {"error": "message", "code": 400, "details": "..."}

07. Rate Limiting

Tier	Requests/hour	Concurrent scans	Burst
Free	100	1	20/min
Standard	1,000	5	100/min
Premium	10,000	20	500/min
Enterprise	Unlimited	Unlimited	Custom

Response headers:

X-RateLimit-Limit — Your tier's hourly limit

X-RateLimit-Remaining — Requests remaining in current window

X-RateLimit-Reset — UTC epoch seconds when the window resets

08. Webhooks & Notifications

Configure webhook URLs in the dashboard under Settings → Integrations → Webhooks. We'll send POST requests for scan events.

Supported Events

scan.started scan.completed scan.failed finding.critical report.ready

Webhook Payload Example

{
  "event": "scan.completed",
  "timestamp": "2025-07-01T10:14:32Z",
  "data": {
    "scan_id": "sc_7f3a9b2e",
    "target": "example.com",
    "findings_count": 7,
    "severity": { "critical": 1, "high": 2, "medium": 3, "low": 1 }
  }
}

Webhooks include an X-Signature-256 header for payload verification using your webhook secret.

Get Your API Key

Get Your API Key →