Skip to main content
POST

​
Start scan

Creates a stored scan and returns the scan_id you will use for follow-up retrieval.
The live API uses keywords. If you still send queries, your request will not match the current contract.

​
Choose one input mode

  • keywords: send one or more search terms such as emails, phone numbers, usernames, IPs, passwords, car plates, social IDs, or composite strings.
  • domain: send a single domain to enumerate breached emails and scan the discovered addresses automatically.
Do not send both in the same request.

​
Keyword guidance

  • Each keyword is queried independently against the breach dataset.
  • Composite queries are supported when you want to correlate multiple terms inside a single search string.
  • Domain scans can return discovered_emails immediately in the POST /scan response.

​
Response semantics

  • scan_id is the durable identifier for the stored scan.
  • status can be success, no_results, or no_queries.
  • total_breaches is the number of matched breach sources.
  • Full raw breach records are not returned by POST /scan; retrieve them with GET /scan/{scan_id}.

​
Error behavior

  • 422: request validation failed, including a missing X-API-Key header or malformed request structure.
  • 403: the API key could not be validated.
  • 502: the upstream breach-data provider returned an error.

Authorizations

​
X-API-Key
string
header
required

API key for authentication. Create keys via the admin dashboard.

Body

application/json

Send exactly one of keywords or domain.

​
keywords
string[]

List of search terms — emails, phone numbers, usernames, IPs, passwords, car plates, social account IDs, or composite queries. Provide this OR domain, not both.

Example:
​
domain
string

Domain name to enumerate emails from and scan. Provide this OR keywords, not both.

Example:

"example.com"

Response

Scan completed

Initial acknowledgement returned by POST /scan. Use scan_id with GET /scan/{scan_id} to retrieve full records.

​
scan_id
string<uuid>

Unique identifier for retrieving scan results via GET /scan/{scan_id}

​
status
enum<string>

Scan result status

Available options:
success,
no_results,
no_queries
​
total_breaches
integer

Number of breach databases found

Required range: x >= 0
​
discovered_emails
string[]

Emails discovered from domain enumeration (only present when domain was provided)

​
message
string

Additional context (e.g. when no keywords were provided)