# Overview
Base URL [#base-url]
All API requests are made to:
```
https://api.cyborux.com
```
Authentication [#authentication]
Cyborux uses **API key authentication** via Bearer tokens. Include your API key in the `Authorization` header of every request.
```ts
const res = await fetch("https://api.cyborux.com/api/user/domains", {
headers: {
Authorization: "Bearer YOUR_API_KEY",
},
});
```
User Tiers [#user-tiers]
Access levels control monthly quotas for analyses, reports, and deep scans.
| Tier | Analyses/mo | Reports/mo | Deep Scans/mo |
| -------------- | ----------- | ---------- | ------------- |
| **Basic** | 0 | 0 | 0 |
| **Protect** | 5 | 5 | 15 |
| **Vigilant** | 10 | 10 | 30 |
| **Enterprise** | Custom | Custom | Custom |
Yearly subscribers receive 12x the monthly allowance. One-shot credit packs can also be purchased to supplement subscription quotas.
Pagination [#pagination]
Paginated endpoints accept these query parameters:
| Parameter | Type | Default | Description |
| ---------- | ------- | -------------- | ------------------------------- |
| `page` | integer | `1` | Page number (1-indexed) |
| `per_page` | integer | `50` | Items per page (max 100) |
| `sort_by` | string | `"risk_level"` | Sort field — varies by endpoint |
Paginated responses include:
```json
{
"items": [],
"total": 142,
"page": 1,
"per_page": 50,
"total_pages": 3
}
```
Error Responses [#error-responses]
The API uses standard HTTP status codes. Error responses return JSON:
```json
{
"detail": "Human-readable error message"
}
```
| Status | Meaning |
| ------ | ---------------------------------------------- |
| `400` | Bad request — invalid parameters or body |
| `401` | Not authenticated — missing or invalid API key |
| `403` | Forbidden — insufficient permissions or tier |
| `404` | Resource not found |
| `429` | Rate limit or quota exceeded |
| `500` | Internal server error |
| `502` | Upstream service unavailable (e.g. Stripe) |
| `503` | Service not configured |
Rate Limiting [#rate-limiting]
* Domain analyses and deep scans are quota-limited per billing period
* Stripe checkout creation is rate-limited to 5 requests per 60 seconds per user
Domain Access [#domain-access]
All domain entity endpoints verify that the authenticated user has access to the requested domain. A user gains access to a domain when they run an analysis on it via `POST /api/analyze-domain`.
# MCP Server
The Cyborux MCP server connects your AI assistant to the Cyborux API using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) — an open standard that lets LLMs call external tools securely. Instead of copying data between apps, you ask questions in natural language and the AI calls the right Cyborux endpoints automatically.
What You Can Do [#what-you-can-do]
With the Cyborux MCP integration you can ask your AI assistant to:
* **Assess domain security** — *"What's the risk score for example.com? What are the main concerns?"*
* **Investigate email breaches** — *"Which emails on example.com have been in data breaches? Show me breach details for the most exposed one."*
* **Audit subdomains** — *"List all active subdomains sorted by risk. Are any vulnerable to takeover?"*
* **Find exposed people** — *"Who are the most exposed people at example.com? What data has been leaked about the CEO?"*
* **Search across everything** — *"Search for 'john' across all data we have on example.com"*
* **Generate reports** — *"Generate a PDF security report for example.com"*
* **Schedule vulnerability scans** — *"Schedule a deep scan for blog.example.com"*
Setup [#setup]
Install Node.js [#install-nodejs]
The Cyborux MCP server runs on Node.js. Make sure `npm` is available in your terminal:
```bash
node --version
```
If not installed, download it from [nodejs.org](https://nodejs.org/) (LTS recommended).
Get Your API Key [#get-your-api-key]
Sign in at [cyborux.com](https://cyborux.com) and go to **API Tokens**. Create a new token — it starts with `cbrx_`. Copy it immediately; it's only shown once.
Configure Claude Desktop [#configure-claude-desktop]
Open Claude Desktop settings and go to **Developer** → **Edit Config**:
This will open the folder containing `claude_desktop_config.json`. Open this file with your favourite editor:
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
```
%APPDATA%\Claude\claude_desktop_config.json
```
Add the Cyborux MCP server:
```json
{
"mcpServers": {
"cyborux": {
"command": "npx",
"args": ["-y", "@cyborux/mcp-server"],
"env": {
"CYBORUX_API_KEY": "cbrx_your_token_here"
}
}
}
}
```
Replace `cbrx_your_token_here` with the API token you created in step 2.
Restart Claude Desktop [#restart-claude-desktop]
Close and reopen Claude Desktop. The Cyborux integration will be available immediately — look for the hammer icon with 22 tools.
Verify [#verify]
Ask Claude:
> *"List my domains on Cyborux"*
It should call the `list_domains` tool and return your monitored domains.
Other Clients [#other-clients]
```bash
claude mcp add cyborux \
-e CYBORUX_API_KEY=cbrx_your_token_here \
-- npx -y @cyborux/mcp-server
```
Open **Settings → MCP Servers** and add:
```json
{
"mcpServers": {
"cyborux": {
"command": "npx",
"args": ["-y", "@cyborux/mcp-server"],
"env": {
"CYBORUX_API_KEY": "cbrx_your_token_here"
}
}
}
}
```
Available Tools [#available-tools]
Domain Analysis [#domain-analysis]
| Tool | Description |
| ---------------- | -------------------------------------------------------------- |
| `list_domains` | List all monitored domains with risk scores and status |
| `analyze_domain` | Start a new OSINT analysis for a domain |
| `domain_summary` | Risk score, security metrics, WHOIS/DNS, and analysis progress |
| `search_domain` | Search across all entity types in a single query |
Discovered Assets [#discovered-assets]
| Tool | Description |
| ------------------- | ---------------------------------------------------- |
| `list_emails` | Email addresses with breach counts and leak status |
| `email_breaches` | Breach timeline for a specific email |
| `list_people` | People profiles with linked entity counts |
| `person_details` | Full person detail with emails, files, and usernames |
| `list_files` | Discovered files with extracted metadata |
| `list_subdomains` | Subdomains with active status and takeover risk |
| `subdomain_details` | Technologies and vulnerabilities for a subdomain |
| `list_usernames` | Social media usernames with platform profiles |
Infrastructure [#infrastructure]
| Tool | Description |
| ---------------------- | ----------------------------------------------------------------- |
| `list_infrastructure` | Internal IPs, server names, and printer paths leaked in documents |
| `list_related_domains` | Related domains discovered through OSINT linkage |
Deep Scans [#deep-scans]
| Tool | Description |
| -------------------- | ------------------------------------------- |
| `list_deep_scans` | Vulnerability scan history and results |
| `schedule_deep_scan` | Schedule a new WordPress vulnerability scan |
Domain Ownership [#domain-ownership]
| Tool | Description |
| -------------------- | ----------------------------------- |
| `initiate_ownership` | Start DNS or HTML file verification |
| `ownership_status` | Check verification progress |
| `verify_ownership` | Trigger the verification check |
Reports & Account [#reports--account]
| Tool | Description |
| --------------------------- | ---------------------------------------- |
| `generate_domain_report` | Generate a PDF analysis report |
| `generate_deep_scan_report` | Generate a PDF vulnerability scan report |
| `subscription_status` | Current plan, usage, and credit balances |
Environment Variables [#environment-variables]
| Variable | Required | Description |
| ----------------- | -------- | ------------------------------------ |
| `CYBORUX_API_KEY` | Yes | Your API token (starts with `cbrx_`) |
Troubleshooting [#troubleshooting]
**Tools not appearing?**
Make sure you restarted the client after editing the config. Check that `npx` is available in your PATH by running `npx --version` in your terminal.
**Authentication errors?**
Verify your `CYBORUX_API_KEY` starts with `cbrx_` and that your subscription is active.
**"Domain not found" errors?**
You need to run an analysis on a domain before querying it. Use the `analyze_domain` tool first.
Links [#links]
* [npm package](https://www.npmjs.com/package/@cyborux/mcp-server)
* [API Reference](/)
* [Get an API key](https://cyborux.com)
# List Deep Scans
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Response [#response]
Returns up to the 20 most recent deep scans for the domain.
```json
{
"scans": [
{
"id": 11,
"target_url": "https://blog.example.com",
"technology_type": "wordpress",
"status": "completed",
"error_message": null,
"scheduled_at": "2026-03-10T14:00:00Z",
"started_at": "2026-03-10T14:00:12Z",
"finished_at": "2026-03-10T14:47:31Z",
"created_at": "2026-03-09T10:00:00Z",
"findings_count": 12,
"vulns": {
"critical": 0,
"high": 2,
"medium": 5,
"low": 3,
"info": 2
}
},
{
"id": 10,
"target_url": "https://shop.example.com",
"technology_type": "wordpress",
"status": "scheduled",
"error_message": null,
"scheduled_at": "2026-03-12T09:00:00Z",
"started_at": null,
"finished_at": null,
"created_at": "2026-03-10T16:30:00Z",
"findings_count": 0,
"vulns": {
"critical": 0,
"high": 0,
"medium": 0,
"low": 0,
"info": 0
}
}
],
"total": 2
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Scan Status Values [#scan-status-values]
| Status | Description |
| ----------- | ----------------------------------------------------------------------- |
| `scheduled` | Scan is queued and waiting for its `scheduled_at` time. |
| `running` | Scan is actively executing. |
| `completed` | Scan finished successfully. Results and `findings_count` are available. |
| `failed` | Scan encountered an unrecoverable error. Check `error_message`. |
Scan Object Fields [#scan-object-fields]
Unique identifier for the scan.
The URL that was or will be scanned.
Technology stack being scanned (e.g. `wordpress`).
Error details if the scan `status` is `failed`.
Total number of findings across all severity levels.
Vulnerability counts broken down by severity.
```bash
curl -X GET https://api.cyborux.com/api/domain/example.com/deep-scans \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/deep-scans",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/deep-scans",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Schedule Deep Scan
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------------ |
| `domain_name` | string | The root domain name (e.g. `example.com`). |
Prerequisites [#prerequisites]
1. **Domain ownership verified** — the authenticated user must have completed `POST /api/domain/{domain_name}/ownership/verify` successfully.
2. **Deep scan quota available** — the user's subscription or one-shot credits must have at least one deep scan remaining. Quota is consumed at scheduling time.
Request Body [#request-body]
| Field | Type | Description |
| ----------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `target_url` | string (max 2048) | The full URL to scan. Must be under the verified domain and, if a subdomain, must be a previously detected subdomain. |
| `technology_type` | string | Technology stack of the target. Currently only `"wordpress"` is supported; other technologies coming soon. |
| `scheduled_at` | string (ISO 8601) | When to run the scan. Must be a future datetime. |
```json
{
"target_url": "https://blog.example.com",
"technology_type": "wordpress",
"scheduled_at": "2026-03-15T09:00:00Z"
}
```
Response [#response]
```json
{
"id": 42,
"target_url": "https://blog.example.com",
"technology_type": "wordpress",
"status": "scheduled",
"scheduled_at": "2026-03-15T09:00:00Z",
"created_at": "2026-03-10T16:30:00Z"
}
```
| Status | Detail |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Invalid request — `target_url` is not under the verified domain, subdomain not previously detected, `scheduled_at` is in the past, or datetime format is invalid. |
| `422` | Validation error — missing required field or `technology_type` is not an accepted value. |
| `401` | Not authenticated. |
| `403` | Forbidden — domain ownership is not verified, or your plan does not include deep scans. |
| `429` | Deep scan quota exceeded. Purchase additional credits or wait for the next billing period. |
```json
{
"detail": "Domain ownership is not verified."
}
```
```bash
curl -X POST https://api.cyborux.com/api/domain/example.com/deep-scans \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"target_url": "https://blog.example.com",
"technology_type": "wordpress",
"scheduled_at": "2026-03-15T09:00:00Z"
}'
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/deep-scans",
{
method: "POST",
headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
body: JSON.stringify({
target_url: "https://blog.example.com",
technology_type: "wordpress",
scheduled_at: "2026-03-15T09:00:00Z",
}),
}
);
const data = await res.json();
```
```python
import requests
response = requests.post(
"https://api.cyborux.com/api/domain/example.com/deep-scans",
json={
"target_url": "https://blog.example.com",
"technology_type": "wordpress",
"scheduled_at": "2026-03-15T09:00:00Z",
},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Initiate Ownership Verification
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------------------------------ |
| `domain_name` | string | The domain name to verify ownership of (e.g. `example.com`). |
Request Body [#request-body]
| Field | Type | Description |
| -------- | ---- | ------------------------------------------------------------- |
| `method` | enum | Verification method. Accepted values: `dns_txt`, `html_file`. |
```json
{
"method": "dns_txt"
}
```
Response [#response]
Pending (verification initiated) [#pending-verification-initiated]
```json
{
"status": "pending",
"token": "cyborux-verify-a1b2c3d4e5f6789012345678",
"method": "dns_txt",
"instructions": {
"type": "dns_txt",
"record_name": "_cyborux-verify.example.com",
"record_value": "cyborux-verify-a1b2c3d4e5f6789012345678",
"description": "Add a TXT record to your DNS zone with the name and value above. DNS propagation may take up to 24 hours."
}
}
```
For `html_file` method:
```json
{
"status": "pending",
"token": "cyborux-verify-a1b2c3d4e5f6789012345678",
"method": "html_file",
"instructions": {
"type": "html_file",
"file_path": "/.well-known/cyborux-verify.html",
"file_content": "cyborux-verify-a1b2c3d4e5f6789012345678",
"description": "Create a publicly accessible file at the path above with the content shown."
}
}
```
Already Verified [#already-verified]
```json
{
"status": "already_verified",
"is_owner": true,
"verified_at": "2026-02-14T10:30:00Z"
}
```
| Status | Detail |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain, or your plan does not include domain ownership verification (deep scan tier required). |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
```bash
curl -X POST https://api.cyborux.com/api/domain/example.com/ownership/initiate \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{"method": "dns_txt"}'
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/ownership/initiate",
{
method: "POST",
headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
body: JSON.stringify({ method: "dns_txt" }),
}
);
const data = await res.json();
```
```python
import requests
response = requests.post(
"https://api.cyborux.com/api/domain/example.com/ownership/initiate",
json={"method": "dns_txt"},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Ownership Status
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ---------------------------------------------- |
| `domain_name` | string | The domain name to check (e.g. `example.com`). |
Response [#response]
The response shape varies depending on the current verification state.
Verified [#verified]
```json
{
"is_owner": true,
"status": "verified",
"verified_at": "2026-02-14T10:30:00Z",
"method": "dns_txt",
"requested_at": "2026-02-14T10:00:00Z"
}
```
Pending (challenge placed, not yet checked) [#pending-challenge-placed-not-yet-checked]
```json
{
"is_owner": false,
"status": "pending",
"verified_at": null,
"method": "html_file",
"requested_at": "2026-03-09T08:15:00Z"
}
```
Not Started [#not-started]
```json
{
"is_owner": false,
"status": "not_started",
"verified_at": null,
"method": null,
"requested_at": null
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Response Fields [#response-fields]
Whether ownership has been confirmed.
Current state: `verified`, `pending`, or `not_started`.
ISO 8601 timestamp of successful verification. `null` if not yet verified.
Challenge method used: `dns_txt` or `html_file`. `null` if not started.
ISO 8601 timestamp of when verification was initiated. `null` if not started.
```bash
curl -X GET https://api.cyborux.com/api/domain/example.com/ownership/status \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/ownership/status",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/ownership/status",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Verify Ownership
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ----------------------------------------------- |
| `domain_name` | string | The domain name to verify (e.g. `example.com`). |
Request Body [#request-body]
No request body required.
Response [#response]
Verification Succeeded [#verification-succeeded]
```json
{
"status": "verified",
"is_owner": true,
"verified_at": "2026-03-10T12:00:00Z"
}
```
Verification Failed [#verification-failed]
```json
{
"status": "failed",
"is_owner": false,
"message": "DNS TXT record not found. Ensure the record has propagated and try again."
}
```
| Status | Detail |
| ------ | ------------------------------------------------------------------------------------------- |
| `400` | No verification initiated — call `POST /api/domain/{domain_name}/ownership/initiate` first. |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "No verification initiated."
}
```
```bash
curl -X POST https://api.cyborux.com/api/domain/example.com/ownership/verify \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/ownership/verify",
{
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY" },
}
);
const data = await res.json();
```
```python
import requests
response = requests.post(
"https://api.cyborux.com/api/domain/example.com/ownership/verify",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Analyze Domain
Request Body [#request-body]
| Field | Type | Description |
| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `domain` | string | The domain to analyze (e.g. `example.com`). Auto-normalized: protocols, `www.`, ports, and path components are stripped. Lowercased. Subdomains are rejected. |
| `email_domain` | string | Override email domain for discovery if different from the main domain. |
| `organization_name` | string (max 100) | Human-readable organization name to associate with this domain. Control characters are stripped. |
| `employees` | enum | Estimated employee count range. |
| `sector` | enum | Industry sector of the organization. |
employees Values [#employees-values]
`1-10`, `11-50`, `51-100`, `101-500`, `501-1000`, `1000+`
sector Values [#sector-values]
`Technology`, `Finance`, `Healthcare`, `Education`, `Government`, `Retail`, `Manufacturing`, `Energy`, `Consulting`, `Other`
```json
{
"domain": "example.com",
"email_domain": "example.com",
"organization_name": "Example Corp",
"employees": "51-100",
"sector": "Technology"
}
```
Domain Normalization [#domain-normalization]
The `domain` field is automatically normalized before analysis:
| Input | Normalized |
| ------------------------------ | ------------------------------------- |
| `https://www.example.com/path` | `example.com` |
| `HTTP://EXAMPLE.COM:8080` | `example.com` |
| `www.example.com` | `example.com` |
| `sub.example.com` | Rejected — subdomains are not allowed |
Response [#response]
The analysis runs asynchronously. Poll the domain summary endpoint to track progress.
```json
{
"status": "success",
"message": "Domain analysis started",
"quota": {
"remaining": 4,
"limit": 5,
"period_end": "2026-04-01T00:00:00Z"
}
}
```
| Status | Detail |
| ------ | --------------------------------------------------------------------------------------------------------- |
| `400` | Invalid domain — could not parse or domain is a subdomain. |
| `401` | Not authenticated. |
| `429` | Analysis quota exceeded for the current billing period. Purchase additional credits or upgrade your plan. |
```json
{
"detail": "Invalid domain."
}
```
```bash
curl -X POST https://api.cyborux.com/api/analyze-domain \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d '{
"domain": "example.com",
"organization_name": "Example Corp",
"employees": "51-100",
"sector": "Technology"
}'
```
```js
const res = await fetch("https://api.cyborux.com/api/analyze-domain", {
method: "POST",
headers: { "Content-Type": "application/json", "Authorization": "Bearer YOUR_API_KEY" },
body: JSON.stringify({
domain: "example.com",
organization_name: "Example Corp",
employees: "51-100",
sector: "Technology",
}),
});
const data = await res.json();
```
```python
import requests
response = requests.post(
"https://api.cyborux.com/api/analyze-domain",
json={
"domain": "example.com",
"organization_name": "Example Corp",
"employees": "51-100",
"sector": "Technology",
},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Cross-Entity Search
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Query Parameters [#query-parameters]
| Parameter | Type | Default | Description |
| ----------- | ------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `q` | string | — | **Required.** Search query (1–200 characters). Matched against email addresses, names, filenames, subdomains, usernames, and related domain names. |
| `page?` | integer | `1` | Page number for each entity result set. |
| `per_page?` | integer | `50` | Items per page per entity type. Maximum `100`. |
| `sort_by?` | string | `risk_level` | Sort field for all result sets. Accepted values: `risk_level`, `discovered_at`. |
Response [#response]
Each entity type returns its own `items` array and a `total` count. The pagination parameters apply uniformly across all entity types.
```json
{
"query": "john",
"total_matches": 8,
"results": {
"emails": {
"count": 2,
"items": [
{
"id": 1201,
"email": "john.smith@example.com",
"is_leaked": true,
"spoofable": false,
"registered_services": ["LinkedIn"],
"linked_person_id": 18,
"email_type": "corporate",
"risk_level": "medium",
"breach_count": 3
}
],
"pagination": { "page": 1, "per_page": 50, "total": 2, "total_pages": 1, "has_more": false }
},
"people": {
"count": 1,
"items": [
{
"id": 18,
"name": "John Smith",
"role": "CTO",
"avatar": null,
"social_profiles": ["https://linkedin.com/in/jsmith"],
"email_count": 2,
"file_count": 1,
"username_count": 1,
"password_count": 0,
"risk_level": "high"
}
],
"pagination": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1, "has_more": false }
},
"files": {
"count": 1,
"items": [
{
"name": "john-smith-report.pdf",
"file_metadata": { "author": "John Smith", "company": "Example Corp", "created_date": "2025:01:15" },
"software_used": ["Microsoft Word"],
"file_size_bytes": 45200,
"people_count": 1,
"risk_level": "info"
}
],
"pagination": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1, "has_more": false }
},
"subdomains": {
"count": 2,
"items": [
{
"subdomain": "john-dev.example.com",
"takeover": null,
"is_active": true,
"service": null,
"technology_count": 3,
"risk_level": "medium",
"is_internal": false,
"has_login_page": false,
"is_dev": true
}
],
"pagination": { "page": 1, "per_page": 50, "total": 2, "total_pages": 1, "has_more": false }
},
"usernames": {
"count": 1,
"items": [
{
"username": "jsmith_dev",
"has_password": true,
"profiles": ["https://github.com/jsmith_dev"],
"people_id": 18,
"risk_level": "medium"
}
],
"pagination": { "page": 1, "per_page": 50, "total": 1, "total_pages": 1, "has_more": false }
},
"related_domains": {
"count": 0,
"items": [],
"pagination": { "page": 1, "per_page": 50, "total": 0, "total_pages": 0, "has_more": false }
}
}
}
```
| Status | Detail |
| ------ | -------------------------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
| `422` | Validation error — `q` is missing, empty, or exceeds 200 characters. |
```json
{
"detail": "Not authenticated."
}
```
```bash
curl -X GET "https://api.cyborux.com/api/domain/example.com/search?q=john&page=1&per_page=10&sort_by=risk_level" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/search?q=john&page=1&per_page=10&sort_by=risk_level",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/search",
params={"q": "john", "page": 1, "per_page": 10, "sort_by": "risk_level"},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Domain Summary
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Response [#response]
```json
{
"domain": "example.com",
"last_analyzed": "2026-03-08T14:22:00Z",
"status": "completed",
"counts": {
"emails": 134,
"people": 18,
"files": 9,
"subdomains": 47,
"usernames": 22,
"related_domains": 5
},
"security_metrics": {
"spoofable_emails": 12,
"leaked_emails": 27,
"active_subdomains": 38,
"takeover_vulnerable": 2,
"passwords_exposed": 5,
"people_with_emails": 15,
"people_in_files": 3,
"critical_vulnerabilities": 1,
"high_vulnerabilities": 4,
"is_domain_spoofable": true,
"login_pages_count": 3,
"usernames_in_files": 8,
"avg_services_emails": 4.2,
"avg_services_usernames": 2.1
},
"risk_score": 67,
"risk_level": "high",
"tls_grade": "A",
"tls_scanned": true,
"highlights": {
"most_exposed_people": [],
"interesting_subdomains": [],
"interesting_files": []
},
"domain_info": {
"registrar": "GoDaddy",
"creation_date": "2010-05-15",
"expiration_date": "2027-05-15",
"dnssec": "unsigned",
"name_servers": ["ns1.example.com", "ns2.example.com"]
},
"is_fully_analyzed": true,
"analysis_progress": null,
"tech_summary": {
"categories": [
{ "name": "Web servers", "count": 3 },
{ "name": "JavaScript frameworks", "count": 5 }
],
"total": 12
},
"organization_name": "Example Corp"
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Response Fields [#response-fields]
The domain name.
ISO 8601 timestamp of when the authenticated user last submitted this domain for analysis. Each user sees their own analysis date, not a global timestamp.
Analysis status: `pending`, `processing`, or `completed`.
Total entity counts: `emails`, `people`, `files`, `subdomains`, `usernames`, `related_domains`.
Security indicators including `spoofable_emails`, `leaked_emails`, `active_subdomains`, `takeover_vulnerable`, `passwords_exposed`, `people_with_emails`, `people_in_files`, `critical_vulnerabilities`, `high_vulnerabilities`, `is_domain_spoofable`, `login_pages_count`, `usernames_in_files`, `avg_services_emails`, `avg_services_usernames`.
Aggregated risk score from 0 to 100. `null` if not yet calculated.
Risk classification: `info`, `low`, `medium`, `high`, or `critical`. `null` if not yet calculated.
TLS/SSL security grade (`A+`, `A`, `A-`, `B`, `C`, `D`, `E`, `F`, `T`, `M`). `null` when not yet scanned, when HTTPS is not available, or when the TLS scanner could not complete the assessment. Use `tls_scanned` to check whether a scan was attempted.
Whether a TLS assessment has been attempted. A `null` grade with `tls_scanned: true` indicates the domain either does not serve HTTPS or the scanner could not complete the assessment.
Dashboard highlights: `most_exposed_people` (excludes people with `unlikely` affiliation), `interesting_subdomains`, `interesting_files`.
WHOIS and DNS data: `registrar`, `creation_date`, `expiration_date`, `dnssec`, `name_servers`.
Whether all analysis phases (including deep enrichment) have completed.
Progress indicator with `phase` and `percentage`. Only present when `status` is `processing`.
Technology stack summary with `categories` (name + count + percentage).
Organization name provided when the domain was first analyzed.
```bash
curl -X GET https://api.cyborux.com/api/domain/example.com/summary \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/summary",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/summary",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Email Breaches
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------- | ----------------------------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
| `email_id` | integer | The ID of the email record (from the List Emails endpoint). |
Response [#response]
```json
[
{
"name": "LinkedIn",
"title": "LinkedIn Scrape",
"domain": "linkedin.com",
"breach_date": "2021-04-08",
"pwn_count": 500000000,
"description": "In April 2021, a large-scale scrape of LinkedIn...",
"data_classes": ["Email addresses", "Names", "Social media profiles"],
"is_verified": true,
"logo_path": "LinkedIn.png"
}
]
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain or email record not found. |
```json
{
"detail": "Not authenticated."
}
```
Breach Object Fields [#breach-object-fields]
Unique identifier for the breach.
Human-readable title of the breach.
Domain associated with the breached service.
Date the breach occurred (`YYYY-MM-DD`).
Number of accounts affected.
Summary of the breach.
Categories of data exposed (e.g. `Email addresses`, `Passwords`, `Names`).
Whether the breach has been verified.
Logo filename for the breached service.
```bash
curl -X GET https://api.cyborux.com/api/domain/example.com/emails/1201/breaches \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/emails/1201/breaches",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/emails/1201/breaches",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# List Emails
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Query Parameters [#query-parameters]
| Parameter | Type | Default | Description |
| ----------- | ------- | ------------ | ------------------------------------------------ |
| `page?` | integer | `1` | Page number (1-indexed). |
| `per_page?` | integer | `50` | Items per page. Maximum `100`. |
| `sort_by?` | string | `risk_level` | Sort field. Accepted values: `risk_level`, `id`. |
Response [#response]
```json
{
"items": [
{
"id": 1201,
"email": "john.smith@example.com",
"is_leaked": true,
"spoofable": false,
"registered_services": ["LinkedIn", "Dropbox"],
"linked_person_id": 18,
"email_type": "corporate",
"risk_level": "medium",
"breach_count": 3
}
],
"count": 134,
"page": 1,
"per_page": 50,
"total_pages": 3
}
```
| Status | Detail |
| ------ | ------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — no access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Item Fields [#item-fields]
Unique email record identifier.
The discovered email address.
Whether the email was found in known data breaches.
Whether the email domain lacks proper email authentication.
Online services the email is registered on.
ID of the linked person profile, if any.
Classification: `corporate`, `personal`, `generic`, or `unknown`.
Risk classification: `info`, `low`, `medium`, `high`, or `critical`.
Number of known data breaches containing this email.
```bash
curl -X GET "https://api.cyborux.com/api/domain/example.com/emails?page=1&per_page=50&sort_by=risk_level" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/emails?page=1&per_page=50&sort_by=risk_level",
{
headers: {
Authorization: "Bearer YOUR_API_KEY",
},
}
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/emails",
params={"page": 1, "per_page": 50, "sort_by": "risk_level"},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# List Files
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Query Parameters [#query-parameters]
| Parameter | Type | Default | Description |
| ----------- | ------- | ------------ | ----------------------------------------------------------- |
| `page?` | integer | `1` | Page number (1-indexed). |
| `per_page?` | integer | `50` | Items per page. Maximum `100`. |
| `sort_by?` | string | `risk_level` | Sort field. Accepted values: `risk_level`, `discovered_at`. |
Response [#response]
```json
{
"items": [
{
"name": "Q3_Strategy_2025.pdf",
"file_metadata": {
"author": "John Smith",
"company": "Example Corp",
"created_date": "2025:07:10 09:15:00"
},
"software_used": ["Microsoft Word"],
"file_size_bytes": 2048576,
"people_count": 1,
"risk_level": "high"
}
],
"count": 9,
"page": 1,
"per_page": 50,
"total_pages": 1
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Item Fields [#item-fields]
Filename including extension.
Extracted metadata with `author`, `company`, and `created_date` fields.
Software detected from file metadata.
File size in bytes.
Number of people linked to this file through metadata.
Risk classification: `info`, `low`, `medium`, `high`, or `critical`.
```bash
curl -X GET "https://api.cyborux.com/api/domain/example.com/files?page=1&per_page=50&sort_by=risk_level" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/files?page=1&per_page=50&sort_by=risk_level",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/files",
params={"page": 1, "per_page": 50, "sort_by": "risk_level"},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# List Domains
Response [#response]
```json
{
"domains": [
{
"domain": "example.com",
"last_analyzed": "2026-03-08T14:22:00Z",
"status": "completed",
"counts": {
"emails": 134,
"people": 18,
"subdomains": 47,
"files": 9,
"usernames": 22
},
"risk_level": "high",
"risk_score": 67,
"analysis_progress": null
},
{
"domain": "acme.io",
"last_analyzed": null,
"status": "processing",
"counts": {
"emails": 12,
"people": 3,
"subdomains": 8,
"files": 0,
"usernames": 4
},
"risk_level": null,
"risk_score": null,
"analysis_progress": {
"phase": "Analyzing",
"percentage": 65
}
]
}
```
| Status | Detail |
| ------ | ------------------ |
| `401` | Not authenticated. |
```json
{
"detail": "Not authenticated."
}
```
Response Fields [#response-fields]
The analyzed domain name.
ISO 8601 timestamp of when the authenticated user last submitted this domain for analysis. `null` if never analyzed. Each user sees their own analysis date.
Analysis status: `pending`, `processing`, or `completed`.
Entity counts: `emails`, `people`, `subdomains`, `files`, `usernames`.
Risk classification: `info`, `low`, `medium`, `high`, or `critical`. `null` if not yet calculated.
Aggregated risk score (0–100). `null` if not yet calculated.
Progress indicator with `phase` and `percentage` fields. Only present when `status` is `processing`.
```bash
curl -X GET https://api.cyborux.com/api/user/domains \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch("https://api.cyborux.com/api/user/domains", {
headers: { "Authorization": "Bearer YOUR_API_KEY" },
});
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/user/domains",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Subscription Status
Response [#response]
```json
{
"user_type": "protect",
"billing_interval": "monthly",
"has_subscription": true,
"subscription_status": "active",
"current_period_end": "2026-04-10T00:00:00Z",
"one_shot_credits": {
"analyses": 2,
"reports": 0,
"deep_scans": 5
},
"usage": {
"analyses_used": 3,
"reports_used": 2,
"deep_scans_used": 7
}
}
```
| Status | Detail |
| ------ | ---------------------------------------------------------------------------------- |
| `401` | Not authenticated. |
| `503` | Stripe not configured — the billing integration is not set up in this environment. |
```json
{
"detail": "Not authenticated."
}
```
Response Fields [#response-fields]
Current plan tier: `basic`, `protect`, `vigilant`, `enterprise`.
Billing cycle: `monthly`, `yearly`, or `null` for no subscription.
Whether the user has an active paid subscription.
Stripe subscription status. See values below.
ISO 8601 timestamp when the current billing period ends.
Remaining one-shot credits not tied to the subscription quota.
How many of each resource the user has consumed in the current period.
subscription_status Values [#subscription_status-values]
| Value | Description |
| ---------- | -------------------------------------------------------------------- |
| `active` | Subscription is current and in good standing. |
| `trialing` | Subscription is in a free trial period. |
| `past_due` | Payment failed — subscription features are still active but at risk. |
| `canceled` | Subscription has been cancelled. |
| `disputed` | A dispute has been opened on a charge. |
| `null` | No subscription exists (basic tier or one-shot only user). |
```bash
curl -X GET https://api.cyborux.com/api/stripe/subscription-status \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/stripe/subscription-status",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/stripe/subscription-status",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# List People
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Query Parameters [#query-parameters]
| Parameter | Type | Default | Description |
| ----------- | ------- | ------------ | ------------------------------------------------ |
| `page?` | integer | `1` | Page number (1-indexed). |
| `per_page?` | integer | `50` | Items per page. Maximum `100`. |
| `sort_by?` | string | `risk_level` | Sort field. Accepted values: `risk_level`, `id`. |
Response [#response]
```json
{
"items": [
{
"id": 18,
"name": "John Smith",
"role": "Chief Technology Officer",
"avatar": null,
"social_profiles": ["https://linkedin.com/in/jsmith"],
"email_count": 2,
"file_count": 1,
"username_count": 4,
"password_count": 1,
"risk_level": "high",
"affiliation": "confirmed"
}
],
"count": 18,
"page": 1,
"per_page": 50,
"total_pages": 1
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Item Fields [#item-fields]
Unique person record identifier.
Full name of the person.
Job title or role.
URL to profile picture.
URLs of linked social media profiles.
Number of email addresses linked to this person.
Number of files linked to this person.
Number of usernames linked to this person.
Number of exposed passwords across linked usernames.
Risk classification: `info`, `low`, `medium`, `high`, or `critical`.
Organization affiliation classification: `confirmed`, `likely`, `unlikely`, `former`, `skipped` (insufficient data to classify), or `null` (not yet classified). People with `unlikely` affiliation are sorted to the end of results.
```bash
curl -X GET "https://api.cyborux.com/api/domain/example.com/people?page=1&per_page=50&sort_by=risk_level" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/people?page=1&per_page=50&sort_by=risk_level",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/people",
params={"page": 1, "per_page": 50, "sort_by": "risk_level"},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Person Details
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------- | ------------------------------------------------------------ |
| `domain_name` | string | The domain name (e.g. `example.com`). |
| `person_id` | integer | The ID of the person record (from the List People endpoint). |
Response [#response]
```json
{
"id": 18,
"name": "John Smith",
"job_title": "Chief Technology Officer",
"occupation_summary": "Technology executive with 15+ years experience",
"affiliation": "confirmed",
"social_profiles": ["https://linkedin.com/in/jsmith"],
"avatar": null,
"emails": [
{
"id": 1201,
"email": "john.smith@example.com",
"is_leaked": true,
"spoofable": false,
"registered_services": ["LinkedIn"],
"email_type": "corporate",
"is_valid_match": true,
"breach_count": 3
}
],
"emails_count": 1,
"files": [
{
"name": "Q3_Strategy_2025.pdf",
"role": "author",
"file_size_bytes": 2048576,
"technologies": []
}
],
"files_count": 1,
"usernames": [
{
"username": "jsmith_dev",
"has_password": true,
"profiles": [{"service": "GitHub", "link": "https://github.com/jsmith_dev", "tags": ["coding"]}]
}
],
"usernames_count": 1,
"passwords_exposed": 1
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain or person not found. |
```json
{
"detail": "Not authenticated."
}
```
Response Fields [#response-fields]
Unique person record identifier.
Full name of the person.
Job title or role.
Brief description of the person's professional background.
Organization affiliation classification: `confirmed`, `likely`, `unlikely`, `former`, `skipped` (insufficient data to classify), or `null` (not yet classified).
URLs of linked social media profiles.
URL to profile picture.
Email addresses linked to this person, with breach and spoofability info.
Total email count.
Files linked to this person, with role (author/creator) and technologies.
Total file count.
Usernames with password exposure and social profiles.
Total username count.
Number of exposed passwords across linked usernames.
```bash
curl -X GET https://api.cyborux.com/api/domain/example.com/person/18 \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/person/18",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/person/18",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Infrastructure
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Query Parameters [#query-parameters]
| Parameter | Type | Default | Description |
| ----------- | ------- | ------- | ------------------------------ |
| `page?` | integer | `1` | Page number (1-indexed). |
| `per_page?` | integer | `50` | Items per page. Maximum `100`. |
Response [#response]
This endpoint surfaces internal network artifacts found embedded in the metadata of publicly accessible documents.
```json
{
"internal_ips": [
{
"ip": "192.168.1.50",
"occurrences": 4,
"files": ["Q3_Strategy_2025.pdf", "annual-report-2024.docx"]
},
{
"ip": "10.0.0.12",
"occurrences": 1,
"files": ["vendor-contract.pdf"]
}
],
"server_names": [
{
"name": "WIN-FILESERVER01",
"occurrences": 3
},
{
"name": "EXMPL-DC-PROD",
"occurrences": 1
}
],
"printer_paths": [
{
"path": "\\\\PRINT-SRV\\HP-LJ-4200",
"occurrences": 2
}
],
"unix_usernames": [
{
"username": "jsmith",
"occurrences": 5
},
{
"username": "build-agent",
"occurrences": 2
}
],
"total": 11,
"page": 1,
"per_page": 50,
"total_pages": 1
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Response Fields [#response-fields]
Private IP addresses (RFC 1918) found in file metadata.
The internal IP address.
Number of files containing this IP.
Filenames where this IP was found.
Windows hostnames or NetBIOS names found in metadata.
UNC printer paths found in document print metadata.
Unix/macOS usernames found in file path metadata.
```bash
curl -X GET "https://api.cyborux.com/api/domain/example.com/infrastructure?page=1&per_page=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/infrastructure?page=1&per_page=50",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/infrastructure",
params={"page": 1, "per_page": 50},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Related Domains
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Query Parameters [#query-parameters]
| Parameter | Type | Default | Description |
| ----------- | ------- | ------- | ------------------------------ |
| `page?` | integer | `1` | Page number (1-indexed). |
| `per_page?` | integer | `50` | Items per page. Maximum `100`. |
Response [#response]
```json
{
"items": [
{ "related_domain": "example.net" },
{ "related_domain": "examplecorp.com" },
{ "related_domain": "example-cdn.com" }
],
"count": 5,
"page": 1,
"per_page": 50,
"total_pages": 1
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Item Fields [#item-fields]
The related domain name.
```bash
curl -X GET "https://api.cyborux.com/api/domain/example.com/related-domains?page=1&per_page=50" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/related-domains?page=1&per_page=50",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/related-domains",
params={"page": 1, "per_page": 50},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# Generate Deep Scan Report
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------------- | --------------------------------------------------------------------------- |
| `domain_name` | string | The domain name the scan belongs to (e.g. `example.com`). |
| `scan_id` | string (UUID) | The unique identifier of the deep scan (from the List Deep Scans endpoint). |
Request Body [#request-body]
No request body required.
Prerequisites [#prerequisites]
* The scan must have `status: "completed"`. Attempting to generate a report for a scan with any other status will return `400`.
* The authenticated user must be the user who scheduled the deep scan.
Response [#response]
On success, returns the PDF file as a streaming binary response.
```
Content-Type: application/pdf
Content-Disposition: attachment; filename="cyborux-deep-scan-report-example.com-2026-03-10.pdf"
```
The response body is the raw PDF binary. Save it directly to a file.
| Status | Detail |
| ------ | ---------------------------------------------------------------------------------------------------- |
| `400` | Scan not completed — the deep scan must have `status: "completed"` before a report can be generated. |
| `401` | Not authenticated. |
| `403` | Forbidden — you are not the owner of this scan. |
| `404` | Domain or scan not found. |
| `500` | Report generation failed — an internal error occurred during PDF rendering. |
```json
{
"detail": "Scan not completed."
}
```
```bash
curl -X POST https://api.cyborux.com/api/domain/example.com/deep-scans/f1e2d3c4-b5a6-7890-abcd-ef1234567890/report \
-H "Authorization: Bearer YOUR_API_KEY" \
-o "cyborux-deep-scan-report.pdf"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/deep-scans/f1e2d3c4-b5a6-7890-abcd-ef1234567890/report",
{
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY" },
}
);
const blob = await res.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "cyborux-deep-scan-report.pdf";
a.click();
```
```python
import requests
response = requests.post(
"https://api.cyborux.com/api/domain/example.com/deep-scans/f1e2d3c4-b5a6-7890-abcd-ef1234567890/report",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
with open("cyborux-deep-scan-report.pdf", "wb") as f:
f.write(response.content)
```
# Generate Domain Report
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | -------------------------------------------------------------- |
| `domain_name` | string | The domain name to generate a report for (e.g. `example.com`). |
Request Body [#request-body]
No request body required.
Prerequisites [#prerequisites]
* The domain must have completed at least one analysis (status `completed`). An analysis that is still `processing` will return `400`.
* If you are a verified domain owner, the report will automatically include detailed findings with specific affected assets and evidence data.
Response [#response]
On success, returns the PDF file as a streaming binary response.
```
Content-Type: application/pdf
Content-Disposition: attachment; filename="cyborux-report-example.com-2026-03-10.pdf"
```
The response body is the raw PDF binary. Save it directly to a file.
Report quota is only consumed after successful generation — a failed generation does not deduct from your quota.
| Status | Detail |
| ------ | -------------------------------------------------------------------------------------------------- |
| `400` | Analysis still in progress — wait for the current analysis to complete before generating a report. |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
| `429` | Report quota exceeded. Purchase additional report credits or upgrade your plan. |
| `500` | Report generation failed — an internal error occurred during PDF rendering. |
```json
{
"detail": "Analysis still in progress."
}
```
```bash
curl -X POST https://api.cyborux.com/api/report/example.com/generate \
-H "Authorization: Bearer YOUR_API_KEY" \
-o "cyborux-report-example.com.pdf"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/report/example.com/generate",
{
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY" },
}
);
const blob = await res.blob();
const url = URL.createObjectURL(blob);
const a = document.createElement("a");
a.href = url;
a.download = "cyborux-report-example.com.pdf";
a.click();
```
```python
import requests
response = requests.post(
"https://api.cyborux.com/api/report/example.com/generate",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
with open("cyborux-report-example.com.pdf", "wb") as f:
f.write(response.content)
```
# Subdomain Details
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ---------------- | ------ | ----------------------------------------------------- |
| `domain_name` | string | The root domain name (e.g. `example.com`). |
| `subdomain_name` | string | The full subdomain hostname (e.g. `api.example.com`). |
Response [#response]
```json
{
"subdomain": "api.example.com",
"is_active": true,
"takeover": false,
"service": null,
"risk_level": "high",
"has_http": true,
"is_internal": false,
"has_login_page": false,
"is_dev": false,
"technologies": [
{ "name": "nginx", "version": "1.24.0", "categories": ["Web servers"] },
{ "name": "Python", "version": "3.11", "categories": ["Programming languages"] }
],
"technologies_count": 2,
"vulnerabilities": [
{ "identifier": "CVE-2024-1234", "severity": "high", "title": "nginx buffer overflow", "technology_type": "web" }
],
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain or subdomain not found. |
```json
{
"detail": "Not authenticated."
}
```
Response Fields [#response-fields]
Whether the subdomain has an active DNS record.
Whether the subdomain is vulnerable to takeover.
Whether the subdomain serves content over HTTP/HTTPS. `true` means a web page was successfully loaded. `null` means not yet scanned.
Whether the subdomain is classified as an internal-facing service.
Whether a login or authentication page was detected on this subdomain.
Whether the subdomain is identified as a development, staging, or test environment.
Detected technologies with `name`, `version`, and `categories`.
Number of detected technologies.
Known vulnerabilities in detected technologies, with `identifier` (CVE), `severity`, `title`, and `technology_type`.
```bash
curl -X GET https://api.cyborux.com/api/domain/example.com/subdomain/api.example.com \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/subdomain/api.example.com",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/subdomain/api.example.com",
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# List Subdomains
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Query Parameters [#query-parameters]
| Parameter | Type | Default | Description |
| -------------- | ------- | ------------ | -------------------------------------------------------------------------- |
| `page?` | integer | `1` | Page number (1-indexed). |
| `per_page?` | integer | `50` | Items per page. Maximum `100`. |
| `active_only?` | boolean | `false` | When `true`, only returns subdomains with a confirmed active DNS response. |
| `sort_by?` | string | `risk_level` | Sort field. Accepted values: `risk_level`, `subdomain`. |
Response [#response]
```json
{
"items": [
{
"subdomain": "api.example.com",
"is_active": true,
"takeover": false,
"service": null,
"risk_level": "high",
"technology_count": 3,
"has_http": true,
"is_internal": false,
"has_login_page": false,
"is_dev": false,
"is_wordpress": false,
},
{
"subdomain": "intranet.example.com",
"is_active": true,
"takeover": false,
"service": null,
"risk_level": "medium",
"technology_count": 5,
"has_http": true,
"is_internal": true,
"has_login_page": true,
"is_dev": false,
"is_wordpress": false,
}
],
"count": 47,
"page": 1,
"per_page": 50,
"total_pages": 1
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Item Fields [#item-fields]
The full subdomain hostname.
Whether the subdomain has an active DNS record.
Whether the subdomain is vulnerable to takeover.
Takeover service name if identified (e.g. `GitHub Pages`, `Heroku`).
Risk classification: `info`, `low`, `medium`, `high`, `critical`.
Number of web technologies detected on this subdomain.
Whether the subdomain serves content over HTTP/HTTPS. `true` means a web page was successfully loaded. `false` means all HTTP/HTTPS attempts failed. `null` means not yet scanned.
Whether the subdomain is classified as an internal-facing service (e.g. intranets, admin panels, dev environments).
Whether a login or authentication page was detected on this subdomain.
Whether the subdomain is identified as a development, staging, or test environment.
Whether WordPress was detected on this subdomain.
```bash
curl -X GET "https://api.cyborux.com/api/domain/example.com/subdomains?page=1&per_page=50&active_only=true&sort_by=risk_level" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/subdomains?page=1&per_page=50&active_only=true&sort_by=risk_level",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/subdomains",
params={"page": 1, "per_page": 50, "active_only": True, "sort_by": "risk_level"},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```
# List Usernames
Path Parameters [#path-parameters]
| Parameter | Type | Description |
| ------------- | ------ | ------------------------------------- |
| `domain_name` | string | The domain name (e.g. `example.com`). |
Query Parameters [#query-parameters]
| Parameter | Type | Default | Description |
| ----------- | ------- | ------------ | ----------------------------------------------------------- |
| `page?` | integer | `1` | Page number (1-indexed). |
| `per_page?` | integer | `50` | Items per page. Maximum `100`. |
| `sort_by?` | string | `risk_level` | Sort field. Accepted values: `risk_level`, `discovered_at`. |
Response [#response]
```json
{
"items": [
{
"username": "jsmith_dev",
"has_password": true,
"profiles": ["https://github.com/jsmith_dev", "https://linkedin.com/in/jsmith"],
"people_id": 18,
"risk_level": "medium"
},
{
"username": "example_corp",
"has_password": false,
"profiles": ["https://twitter.com/example_corp"],
"people_id": null,
"risk_level": "low"
}
],
"count": 22,
"page": 1,
"per_page": 50,
"total_pages": 1
}
```
| Status | Detail |
| ------ | -------------------------------------------------- |
| `401` | Not authenticated. |
| `403` | Forbidden — you do not have access to this domain. |
| `404` | Domain not found. |
```json
{
"detail": "Not authenticated."
}
```
Item Fields [#item-fields]
The discovered username or handle.
Whether a password was found exposed for this username.
URLs of social media or platform profiles associated with this username.
ID of the linked person profile, if any.
Risk classification: `info`, `low`, `medium`, `high`, or `critical`.
```bash
curl -X GET "https://api.cyborux.com/api/domain/example.com/usernames?page=1&per_page=50&sort_by=risk_level" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```js
const res = await fetch(
"https://api.cyborux.com/api/domain/example.com/usernames?page=1&per_page=50&sort_by=risk_level",
{ headers: { "Authorization": "Bearer YOUR_API_KEY" } }
);
const data = await res.json();
```
```python
import requests
response = requests.get(
"https://api.cyborux.com/api/domain/example.com/usernames",
params={"page": 1, "per_page": 50, "sort_by": "risk_level"},
headers={"Authorization": "Bearer YOUR_API_KEY"},
)
data = response.json()
```