API Reference

Overview

The ThreatAware API provides REST-based, read-only access to your portal data over HTTPS. Query devices, users, alerts, Vitals status, and integration-specific data programmatically.

API Endpoints

Browse available endpoints by category.

Devices

Query device inventory and detailed information from all connected integrations

Users

Retrieve user account information aggregated across identity providers

Inventory

Access aggregated inventory data from all connected integrations

Alerts

Query security issues and Vitals health problems detected across your environment

Vitals

Retrieve security control health status for devices and integrations

Settings

Access portal configuration, tags, teams, roles, and integration settings

Base URL

All API requests should be made to your portal-specific base URL:

https://{cloudId}.threataware.com/public-api/v1

Replace {cloudId} with your organization’s Cloud ID. You can find your Cloud ID in your portal URL or in Settings → API Access.

Example: If your portal URL is https://acme-corp.threataware.com, your base URL would be https://acme-corp.threataware.com/public-api/v1

Authentication

ThreatAware uses API key authentication. Include your API key in the X-ThreatAware-ApiKey header with every request.

cURL
Python
JavaScript
PowerShell

curl -X GET "https://{cloudId}.threataware.com/public-api/v1/devices" \
  -H "X-ThreatAware-ApiKey: your-api-key-here"

import requests

API_KEY = "your-api-key-here"
CLOUD_ID = "your-cloud-id"
BASE_URL = f"https://{CLOUD_ID}.threataware.com/public-api/v1"

headers = {
    "X-ThreatAware-ApiKey": API_KEY
}

response = requests.get(f"{BASE_URL}/devices", headers=headers)
devices = response.json()

const axios = require('axios');

const API_KEY = 'your-api-key-here';
const CLOUD_ID = 'your-cloud-id';
const BASE_URL = `https://${CLOUD_ID}.threataware.com/public-api/v1`;

const headers = {
  'X-ThreatAware-ApiKey': API_KEY
};

axios.get(`${BASE_URL}/devices`, { headers })
  .then(response => console.log(response.data));

$ApiKey = "your-api-key-here"
$CloudId = "your-cloud-id"
$BaseUrl = "https://$CloudId.threataware.com/public-api/v1"

$Headers = @{
    "X-ThreatAware-ApiKey" = $ApiKey
}

$Devices = Invoke-RestMethod -Uri "$BaseUrl/devices" -Headers $Headers -Method Get

Response Codes

The ThreatAware API uses standard HTTP response codes to indicate success or failure.

Status	Description
200	Request successful
400	Bad request - verify parameters
401	Unauthorized - invalid or missing API key
403	Forbidden - insufficient permissions
404	Resource not found
429	Rate limit exceeded - implement exponential backoff
500	Internal server error
502	Bad gateway - temporary issue
503	Service unavailable - try again later

Rate Limits

Current Rate Limit: 10 requests per 60 secondsRate limits are applied portal-wide regardless of IP addresses. They may vary based on your ThreatAware plan.

If you exceed the rate limit, the API returns a 429 status code. Implement exponential backoff in your integration to handle this gracefully.

Quick Start

Generate API Key

Navigate to Settings → API Access → Generate Key

Save your API key immediately - it’s only shown once during generation.

Test Connection

Make a test request to verify your API key works. See the Authentication section above for examples in multiple languages.

Explore Endpoints

Browse the API Endpoints section above or visit apidocs.threataware.com for the complete reference.

Create separate API keys for different integrations or team members for better security and audit tracking.

Available Endpoints

The ThreatAware API provides access to the following resources:

Devices

Query device inventory with detailed information from all connected integrations.Common Use Cases:

Export device list to CMDB
Power BI dashboards
Custom reporting
Integration with ticketing systems

Example:

GET /public-api/v1/devices
GET /public-api/v1/devices/{deviceId}

Users

Retrieve user account information aggregated across directory services and identity providers.Common Use Cases:

User access auditing
Multi-Factor Authentication (MFA) coverage reporting
Offboarding validation

Example:

GET /public-api/v1/users
GET /public-api/v1/users/{userId}

Inventory

Access aggregated inventory data from all connected integrations.Common Use Cases:

Asset management exports
Compliance reporting
Hardware tracking

Example:

GET /public-api/v1/inventory/devices
GET /public-api/v1/inventory/software

Alerts & Issues

Query security issues and Vitals health problems detected across your environment.Common Use Cases:

SIEM integration
SOC dashboards
Automated ticket creation

Example:

GET /public-api/v1/alerts
GET /public-api/v1/issues

Vitals

Retrieve security control health status for devices and integrations.Common Use Cases:

Security posture dashboards
Compliance evidence collection
Executive reporting

Example:

GET /public-api/v1/vitals/devices
GET /public-api/v1/vitals/integrations

Settings

Access portal configuration, tags, and integration settings.Common Use Cases:

Automation configuration
Tag-based reporting
Integration status monitoring

Example:

GET /public-api/v1/settings/tags
GET /public-api/v1/settings/integrations

Pagination

ThreatAware’s API uses offset and limit parameters for pagination:

GET /public-api/v1/devices?offset=0&limit=100

offset: Number of records to skip (default: 0)
limit: Number of records to return (default: all if 0 or omitted)

For large datasets (10,000+ devices), use pagination with a limit of 100-500 records per request for optimal performance.

Common Use Cases

Power BI Integration

Goal: Real-time security dashboards

Use Power BI’s “Web” data source
Configure API key in Advanced settings
Set refresh schedule (hourly recommended)
Build visuals from Vitals and device data

SIEM Integration

Goal: Forward security issues to SIEM

Poll /public-api/v1/alerts endpoint every 5-15 minutes
Filter by severity or integration
Send to Splunk, Sentinel, or QRadar
Correlate with other security events

ServiceNow CMDB Sync

Goal: Keep CMDB up-to-date with ThreatAware data

Query /public-api/v1/devices daily
Map ThreatAware fields to CI attributes
Update or create CI records
Track discrepancies

Custom Reporting

Goal: Automated compliance reports

Export Vitals status via API
Generate PDF/Excel reports
Email to stakeholders
Archive for audit evidence

Best Practices

Security

Protect Your API Keys

✅ Store keys in environment variables or secrets managers
✅ Use separate keys per integration/team
✅ Rotate keys annually or when team members leave
✅ Monitor API access in Settings → Audit Log
❌ Never commit API keys to source control
❌ Don’t share keys via email or chat
❌ Avoid hardcoding keys in scripts

Performance

Optimize API Usage

Use pagination for large datasets
Cache responses when data doesn’t change frequently
Implement exponential backoff for rate limit handling
Query only the fields you need (if filtering supported)
Schedule heavy queries during off-peak hours

Error Handling

Handle Failures Gracefully

Example: Python Error Handling

import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

session = requests.Session()
retry = Retry(
    total=3,
    backoff_factor=1,
    status_forcelist=[429, 500, 502, 503, 504]
)
adapter = HTTPAdapter(max_retries=retry)
session.mount('https://', adapter)

response = session.get(url, headers=headers)

Common status codes:

200: Success
401: Invalid API key
429: Rate limit exceeded
500: Server error

Integration Testing

Test Before Production

Create a test API key
Query a small dataset first
Validate response structure
Test error scenarios (invalid key, rate limits)
Monitor initial production usage closely
Set up alerting for API failures

Complete API Documentation

For the complete API reference with all endpoints, parameters, and response schemas, visit:

ThreatAware API Documentation

Full API reference with interactive examples and detailed schemas

Support

Need help with the API?

Documentation: apidocs.threataware.com
Email Support: help@threataware.com
Portal: Settings → API Access (for key management)

Include your Cloud ID and API request/response examples when contacting support for faster resolution.

Next Steps

Integrations

Learn about data sources feeding the API

Automation

Combine API with Actions for workflows

Security Monitoring

Understand Vitals data available via API

API documentation

Core Endpoints

Settings & Management

Overview

API Endpoints

Devices

Users

Inventory

Alerts

Vitals

Settings

Base URL

Authentication

Response Codes

Rate Limits

Quick Start

Available Endpoints

Common Use Cases

Power BI Integration

SIEM Integration

ServiceNow CMDB Sync

Custom Reporting

Best Practices

Complete API Documentation

ThreatAware API Documentation

Support

Next Steps

Integrations

Automation

Security Monitoring

​Overview

​API Endpoints

Devices

Users

Inventory

Alerts

Vitals

Settings

​Base URL

​Authentication

​Response Codes

​Rate Limits

​Quick Start

​Available Endpoints

​Pagination

​Common Use Cases

Power BI Integration

SIEM Integration

ServiceNow CMDB Sync

Custom Reporting

​Best Practices

​Complete API Documentation

ThreatAware API Documentation

​Support

​Next Steps

Integrations

Automation

Security Monitoring

Overview

API Endpoints

Base URL

Authentication

Response Codes

Rate Limits

Quick Start

Available Endpoints

Pagination

Common Use Cases

Best Practices

Complete API Documentation

Support

Next Steps