Incidents API Reference

The Incidents API provides programmatic access to all detections from DarkFlash, Shadowspot, and BrandSafe. Each product exposes its own endpoint under a common base URL.

Base URL

https://incidents.cyberxtron.com

Authentication

All endpoints require two custom request headers:

Header	Description
XTRON-ORG-KEY	Your organization's access key
XTRON-ORG-SECRET	Your organization's access secret

Requests missing these headers or with invalid credentials return 401 Unauthorized.

Credentials are provisioned by the CyberXTron team. Contact support@cyberxtron.com to request access.

curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/darkflash/incidents"

---

Endpoints

DarkFlash Incidents

Retrieve incidents detected by DarkFlash — credential leaks, data breach mentions, ransomware listings, and threat actor activity.

GET /api/v1/darkflash/incidents

Query Parameters

Parameter	Type	Default	Description
keyword	string	—	Filter by monitored keyword
status	string[]	—	Filter by status: Open, In Progress, Closed
severity	string	—	Filter by severity label
created_date	string	—	Filter by date (YYYY-MM-DD)
created_time	string	—	Filter by time (HH:MM:SS)
page	integer	1	Page number (min: 1)
size	integer	10	Results per page (min: 1, max: 100)

Example Requests

# All open DarkFlash incidents
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/darkflash/incidents?status=Open"

# Filter by keyword and severity
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/darkflash/incidents?keyword=acme+corp&severity=Critical&page=1&size=25"

# Filter by date
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/darkflash/incidents?created_date=2026-04-01&status=Open"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 12345,
      "title": "Employee credentials found in stealer log",
      "taskKey": "DFINC-123",
      "status_description": "Open",
      "status_statusCd": "Open",
      "severity_label": "Critical",
      "category_name": "Credential Leak",
      "taskType_name": "Stealer Log",
      "product_name": "DarkFlash",
      "description": "Employee credentials matching your monitored domain were found in a stealer log published on a dark web forum.",
      "createdDt": 1743494400,
      "updatedDt": 1743494400,
      "impact": "Compromised credentials may allow unauthorized access to corporate systems.",
      "recommendation": "Force a password reset for the affected accounts and review authentication logs.",
      "keyword": "example.com",
      "publisher_source": "Dark web forum",
      "retrieved_data": "username@example.com:password123"
    }
  ],
  "meta": {
    "pagination": {
      "total": 42,
      "page": 1,
      "page_size": 10,
      "total_pages": 5
    }
  }
}

---

Shadowspot Findings

Retrieve attack surface findings from Shadowspot — exposed services, CVEs, certificate issues, subdomain takeovers, and cloud misconfigurations.

GET /api/v1/shadowspot/findings

note

Shadowspot uses the path /findings rather than /incidents.

Query Parameters

Parameter	Type	Default	Description
domain	string	—	Filter by affected domain
status	string[]	—	Filter by status: Open, In Progress, Closed
severity	string	—	Filter by severity label
created_date	string	—	Filter by date (YYYY-MM-DD)
created_time	string	—	Filter by time (HH:MM:SS). Requires created_date.
page	integer	1	Page number (min: 1)
size	integer	10	Results per page (min: 1, max: 100)

Example Requests

# All open Shadowspot findings
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/shadowspot/findings?status=Open"

# Filter by domain and severity
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/shadowspot/findings?domain=example.com&severity=Critical"

# Paginate through all findings
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/shadowspot/findings?page=2&size=50"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 67890,
      "title": "Elasticsearch instance exposed on port 9200",
      "taskKey": "SSINC-456",
      "status_description": "Open",
      "status_statusCd": "Open",
      "severity_label": "Critical",
      "category_name": "Exposed Service",
      "taskType_name": "Open Port",
      "product_name": "Shadowspot",
      "description": "An Elasticsearch instance is publicly accessible without authentication.",
      "createdDt": 1743494400,
      "updatedDt": 1743494400,
      "priorty": "High",
      "assets": "api.example.com:9200",
      "url": "http://api.example.com:9200",
      "epss": "0.87",
      "cvss": "9.8",
      "ransomware_exploited_cve": "Yes",
      "in_the_wild": "Yes",
      "impact": "Unauthenticated access to all indexed data.",
      "remediation": "Restrict access using firewall rules or move behind VPN.",
      "domain": "example.com",
      "verification_details": "Confirmed accessible from public internet. Index listing returned without credentials."
    }
  ],
  "meta": {
    "pagination": {
      "total": 18,
      "page": 1,
      "page_size": 10,
      "total_pages": 2
    }
  }
}

---

BrandSafe Incidents

Retrieve brand threat incidents from BrandSafe — phishing sites, typosquatting domains, fake social profiles, and counterfeit apps.

GET /api/v1/brandsafe/incidents

Query Parameters

Parameter	Type	Default	Description
brand_domain	string	—	Filter by monitored brand domain
status	string[]	—	Filter by status: Open, In Progress, Closed
severity	string	—	Filter by severity label
created_date	string	—	Filter by date (YYYY-MM-DD)
created_time	string	—	Filter by time (HH:MM:SS)
page	integer	1	Page number (min: 1)
size	integer	10	Results per page (min: 1, max: 100)

Example Requests

# All open BrandSafe incidents
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/brandsafe/incidents?status=Open"

# Filter by brand domain
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/brandsafe/incidents?brand_domain=example.com&severity=Critical"

Example Response

{
  "success": true,
  "data": [
    {
      "id": 34567,
      "title": "Phishing site impersonating example.com login page",
      "taskKey": "BSINC-789",
      "status_description": "Open",
      "status_statusCd": "Open",
      "severity_label": "Critical",
      "category_name": "Phishing",
      "taskType_name": "Phishing Site",
      "product_name": "BrandSafe",
      "description": "A phishing site mimicking the example.com login portal was detected, designed to harvest user credentials.",
      "createdDt": 1743494400,
      "updatedDt": 1743494400,
      "impact": "Users may submit credentials to the attacker-controlled site.",
      "recommendation": "Submit abuse reports to the registrar and hosting provider. Report to Google Safe Browsing and Microsoft SmartScreen.",
      "brand_name": "Example Corp",
      "brand_domain": "example.com",
      "platform": "Web",
      "registrar": "Namecheap",
      "ip_address": "203.0.113.99",
      "url": "https://example-secure-login.com/login",
      "webhost_authority": "Cloudflare",
      "webhost_country": "United States",
      "phone_numbers": null
    }
  ],
  "meta": {
    "pagination": {
      "total": 7,
      "page": 1,
      "page_size": 10,
      "total_pages": 1
    }
  }
}

---

Pagination

All list endpoints use page-based pagination. Navigate pages using page and size:

# Page 1, 25 results per page
curl \
  -H "XTRON-ORG-KEY: your_org_key" \
  -H "XTRON-ORG-SECRET: your_org_secret" \
  "https://incidents.cyberxtron.com/api/v1/darkflash/incidents?page=1&size=25"

The meta.pagination object in every response tells you how to fetch the next page:

"meta": {
  "pagination": {
    "total": 42,
    "page": 1,
    "page_size": 25,
    "total_pages": 2
  }
}

Field	Description
total	Total number of matching records
page	Current page number
page_size	Number of results on this page
total_pages	Total number of pages

---

Response Schemas

Common Fields (all products)

These fields appear on every incident/finding:

Field	Type	Description
id	integer	Unique numeric ID
title	string	Short title describing the detection
taskKey	string	Ticket key (e.g., DFINC-123, SSINC-456, BSINC-789)
status_description	string	Human-readable status
status_statusCd	string	Status code: Open, In Progress, Closed
severity_label	string	Severity: Critical, High, Medium, Low
category_name	string	Detection category
taskType_name	string	Specific incident type
product_name	string	Source product name
description	string	Full description of the detection
createdDt	integer	Creation Unix timestamp (milliseconds)
updatedDt	integer	Last update Unix timestamp (milliseconds)
impact	string	Impact description
recommendation	string	Suggested remediation action

DarkFlash-Specific Fields

Field	Type	Description
keyword	string	The monitored keyword that triggered this detection
publisher_source	string	Where the data was found (e.g., dark web forum, Telegram)
retrieved_data	string	Raw retrieved data excerpt

Shadowspot-Specific Fields

Field	Type	Description
assets	string	Affected asset (host, IP, or port)
url	string	Affected URL
domain	string	Affected domain
cvss	string	CVSS score (for CVE findings)
epss	string	EPSS probability score (for CVE findings)
ransomware_exploited_cve	string	Whether this CVE is known to be exploited by ransomware
in_the_wild	string	Whether the vulnerability is being actively exploited
priorty	string	Priority level
remediation	string	Specific remediation steps
verification_details	string	Evidence and confirmation details

BrandSafe-Specific Fields

Field	Type	Description
brand_name	string	Monitored brand name
brand_domain	string	Monitored brand domain
platform	string	Platform where the threat was found
url	string	URL of the infringing asset
ip_address	string	IP address of the infringing host
registrar	string	Domain registrar
webhost_authority	string	Hosting provider
webhost_country	string	Country where the site is hosted
phone_numbers	string	Phone numbers found on the infringing site

---

Error Handling

Error Response Format

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "details": [
      {
        "loc": ["query", "status"],
        "msg": "value is not a valid enum member",
        "type": "type_error.enum"
      }
    ]
  }
}

HTTP Status Codes

Status	Description
200	Successful response
401	Invalid or missing XTRON-ORG-KEY / XTRON-ORG-SECRET
403	Subscription suspended or expired
404	Resource not found
422	Validation error — check your query parameter values

---

Health Check

Verify API availability without authentication:

curl "https://incidents.cyberxtron.com/health"

Returns 200 OK when the service is operational.