📊 Exposure Management API Documentation

🎯 Overview

The Exposure Management API provides comprehensive access to security exposure data, allowing developers to retrieve, filter, and analyze credential exposures across monitored domains. This API requires authentication via API keys and supports advanced filtering, pagination, and sorting capabilities.

🔑 Authentication

All Exposure Management API endpoints require authentication using an API key passed in the request header:

Important Notes:

API keys are organization-specific and provide access only to exposures within your organization's scope

Each API call increments the usage count for the associated API key

Ensure your API key is kept secure and not exposed in client-side code

🌐 Base URL

https://api.foxhat.org/api

📋 Content Type

All API responses return JSON data with the following content type:

Content-Type: application/json

📚 API Endpoints

1. 📋 Get All Exposures

Retrieve all exposures for your organization with optional filtering and pagination.

Endpoint

Headers

Query Parameters

Parameter	Type	Required	Default	Description
`page`	integer	No	`0`	Page number for pagination (0-based)
`size`	integer	No	`20`	Number of items per page (max: 100)
`domain`	string	No	-	Filter by specific domain name
`exposureType`	enum	No	-	Filter by exposure type
`severity`	enum	No	-	Filter by severity level (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`status`	enum	No	-	Filter by exposure status (`ACTIVE`, `RESOLVED`, `INVESTIGATING`)
`source`	string	No	-	Filter by data source
`subdomain`	string	No	-	Filter by specific subdomain
`startDate`	string	No	-	Filter exposures from this date (ISO 8601 format)
`endDate`	string	No	-	Filter exposures until this date (ISO 8601 format)
`sortBy`	string	No	`detectedAt`	Sort field (`detectedAt`, `severity`, `domain`, `email`)
`sortDir`	string	No	`desc`	Sort direction (`asc`, `desc`)

Example Request

Example Response

{
  "exposures": [
    {
      "id": "exposure_123",
      "email": "user@example.com",
      "password": "password123",
      "domain": "example.com",
      "source": "data_breach",
      "severity": "HIGH",
      "status": "ACTIVE",
      "detectedAt": "2024-01-15T10:30:00Z",
      "exposureType": "CREDENTIAL_LEAK",
      "subdomain": "mail.example.com",
      "breachName": "Example Corp Breach 2024",
      "lastUpdated": "2024-01-15T10:30:00Z"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "currentPage": 0,
  "domainName": "example.com",
  "user_id": "user123",
  "api_key_usage_count": "incremented"
}

Response Fields

Field	Type	Description
`exposures`	array	Array of exposure objects
`totalElements`	integer	Total number of exposures matching the criteria
`totalPages`	integer	Total number of pages available
`currentPage`	integer	Current page number (0-based)
`domainName`	string	Domain name associated with the API key
`user_id`	string	User ID associated with the API key
`api_key_usage_count`	string	Indicates that API key usage was incremented

Exposure Object Fields

Field	Type	Description
`id`	string	Unique exposure identifier
`email`	string	Exposed email address
`password`	string	Exposed password (may be hashed)
`domain`	string	Associated domain
`source`	string	Source of the exposure (e.g., "data_breach")
`severity`	enum	Severity level (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`)
`status`	enum	Current status (`ACTIVE`, `RESOLVED`, `INVESTIGATING`)
`detectedAt`	string	ISO 8601 timestamp when exposure was detected
`exposureType`	enum	Type of exposure
`subdomain`	string	Specific subdomain if applicable
`breachName`	string	Name of the breach or source
`lastUpdated`	string	ISO 8601 timestamp of last update

2. 🔍 Get Specific Exposure

Retrieve detailed information about a specific exposure by its ID.

Endpoint

Headers

Path Parameters

Parameter	Type	Required	Description
`exposureId`	string	Yes	Unique identifier of the exposure

Example Request

Example Response

{
  "id": "exposure_123",
  "email": "user@example.com",
  "password": "password123",
  "domain": "example.com",
  "source": "data_breach",
  "severity": "HIGH",
  "status": "ACTIVE",
  "detectedAt": "2024-01-15T10:30:00Z",
  "exposureType": "CREDENTIAL_LEAK",
  "subdomain": "mail.example.com",
  "breachName": "Example Corp Breach 2024",
  "lastUpdated": "2024-01-15T10:30:00Z",
  "additionalData": {
    "ipAddress": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "location": "United States"
  },
  "relatedExposures": [
    {
      "id": "exposure_124",
      "email": "user@example.com",
      "domain": "example.com",
      "severity": "MEDIUM"
    }
  ],
  "domainName": "example.com",
  "user_id": "user123",
  "api_key_usage_count": "incremented"
}

Additional Response Fields for Single Exposure

Field	Type	Description
`additionalData`	object	Additional metadata about the exposure
`relatedExposures`	array	Array of related exposures for the same email/domain

3. 📊 Get Exposure Statistics

Retrieve statistical information about exposures for your organization.

Endpoint

Headers

Query Parameters

Parameter	Type	Required	Default	Description
`domain`	string	No	-	Filter statistics by specific domain
`startDate`	string	No	-	Start date for statistics (ISO 8601 format)
`endDate`	string	No	-	End date for statistics (ISO 8601 format)

Example Request

Example Response

{
  "totalExposures": 1247,
  "activeExposures": 892,
  "resolvedExposures": 355,
  "severityBreakdown": {
    "CRITICAL": 45,
    "HIGH": 234,
    "MEDIUM": 567,
    "LOW": 401
  },
  "statusBreakdown": {
    "ACTIVE": 892,
    "RESOLVED": 355,
    "INVESTIGATING": 0
  },
  "domainBreakdown": [
    {
      "domain": "example.com",
      "count": 1000,
      "percentage": 80.2
    },
    {
      "domain": "subdomain.example.com",
      "count": 247,
      "percentage": 19.8
    }
  ],
  "trendsData": {
    "last30Days": 156,
    "last7Days": 23,
    "last24Hours": 5
  },
  "topSources": [
    {
      "source": "data_breach_2024",
      "count": 456,
      "percentage": 36.6
    },
    {
      "source": "credential_dump",
      "count": 234,
      "percentage": 18.8
    }
  ],
  "domainName": "example.com",
  "user_id": "user123",
  "api_key_usage_count": "incremented"
}

Statistics Response Fields

Field	Type	Description
`totalExposures`	integer	Total number of exposures
`activeExposures`	integer	Number of active exposures
`resolvedExposures`	integer	Number of resolved exposures
`severityBreakdown`	object	Count of exposures by severity level
`statusBreakdown`	object	Count of exposures by status
`domainBreakdown`	array	Breakdown of exposures by domain
`trendsData`	object	Exposure trends over different time periods
`topSources`	array	Most common sources of exposures

4. 🔧 Advanced Filtering Examples

The Get All Exposures endpoint supports complex filtering combinations. Here are practical examples:

Filter by Domain and Severity

Filter by Date Range

Filter by Multiple Criteria

Filter by Subdomain

📝 Enumeration Values

Severity Levels

LOW - Low risk exposures

MEDIUM - Medium risk exposures

HIGH - High risk exposures requiring attention

CRITICAL - Critical exposures requiring immediate action

Exposure Status

ACTIVE - Exposure is currently active and unresolved

RESOLVED - Exposure has been addressed and resolved

INVESTIGATING - Exposure is under investigation

Exposure Types

CREDENTIAL_LEAK - Username/password combinations

EMAIL_EXPOSURE - Email addresses in data breaches

PERSONAL_INFO - Personal information exposure

FINANCIAL_DATA - Financial information exposure

CORPORATE_DATA - Corporate data exposure

Sort Fields

detectedAt - Sort by detection timestamp

severity - Sort by severity level

domain - Sort by domain name

email - Sort by email address

lastUpdated - Sort by last update timestamp

Sort Directions

asc - Ascending order

desc - Descending order

⚠️ Error Handling

Common HTTP Status Codes

Status Code	Description	Example Response
`200`	Success	Data returned successfully
`400`	Bad Request	Invalid parameters or malformed request
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	API key doesn't have access to requested resource
`404`	Not Found	Exposure ID not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Server error occurred

Error Response Format

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired",
    "timestamp": "2024-01-15T10:30:00Z",
    "requestId": "req_123456789"
  }
}

Common Error Codes

Error Code	Description	Resolution
`INVALID_API_KEY`	API key is invalid or expired	Check your API key and ensure it's active
`INSUFFICIENT_PERMISSIONS`	API key lacks required permissions	Contact support to upgrade permissions
`RATE_LIMIT_EXCEEDED`	Too many requests in time window	Implement rate limiting in your application
`INVALID_PARAMETERS`	Request parameters are invalid	Check parameter format and values
`EXPOSURE_NOT_FOUND`	Specified exposure ID doesn't exist	Verify the exposure ID is correct

🚀 Rate Limiting

Rate Limits

Standard Plan: 1,000 requests per hour

Professional Plan: 5,000 requests per hour

Enterprise Plan: 25,000 requests per hour

Rate Limit Headers

Best Practices

Implement exponential backoff for rate limit errors

Cache responses when appropriate to reduce API calls

Use pagination efficiently to avoid large data transfers

Monitor your usage through the API key dashboard

Exposure Management

📊 Exposure Management API Documentation#

🎯 Overview#

🔑 Authentication#

🌐 Base URL#

📋 Content Type#

📚 API Endpoints#

1. 📋 Get All Exposures#

Endpoint#

Headers#

Query Parameters#

Example Request#

Example Response#

Response Fields#

Exposure Object Fields#

2. 🔍 Get Specific Exposure#

Endpoint#

Headers#

Path Parameters#

Example Request#

Example Response#

Additional Response Fields for Single Exposure#

3. 📊 Get Exposure Statistics#

Endpoint#

Headers#

Query Parameters#

Example Request#

Example Response#

Statistics Response Fields#

4. 🔧 Advanced Filtering Examples#

Filter by Domain and Severity#

Filter by Date Range#

Filter by Multiple Criteria#

Filter by Subdomain#

📝 Enumeration Values#

Severity Levels#

Exposure Status#

Exposure Types#

Sort Fields#

Sort Directions#

⚠️ Error Handling#

Common HTTP Status Codes#

Error Response Format#

Common Error Codes#

🚀 Rate Limiting#

Rate Limits#

Rate Limit Headers#

Best Practices#

💻 SDK Examples#

JavaScript/Node.js Example#

Python Example#

📊 Exposure Management API Documentation

🎯 Overview

🔑 Authentication

🌐 Base URL

📋 Content Type

📚 API Endpoints

1. 📋 Get All Exposures

Endpoint

Headers

Query Parameters

Example Request

Example Response

Response Fields

Exposure Object Fields

2. 🔍 Get Specific Exposure

Endpoint

Headers

Path Parameters

Example Request

Example Response

Additional Response Fields for Single Exposure

3. 📊 Get Exposure Statistics

Endpoint

Headers

Query Parameters

Example Request

Example Response

Statistics Response Fields

4. 🔧 Advanced Filtering Examples

Filter by Domain and Severity

Filter by Date Range

Filter by Multiple Criteria

Filter by Subdomain

📝 Enumeration Values

Severity Levels

Exposure Status

Exposure Types

Sort Fields

Sort Directions

⚠️ Error Handling

Common HTTP Status Codes

Error Response Format

Common Error Codes

🚀 Rate Limiting

Rate Limits

Rate Limit Headers

Best Practices

💻 SDK Examples

JavaScript/Node.js Example

Python Example