> ## Documentation Index
> Fetch the complete documentation index at: https://docs.threataware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Programmatic access to ThreatAware platform

## 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.

<CardGroup cols={2}>
  <Card title="Devices" icon="desktop" href="/api-reference/devices">
    Query device inventory and detailed information from all connected integrations
  </Card>

  <Card title="Users" icon="users" href="/api-reference/users">
    Retrieve user account information aggregated across identity providers
  </Card>

  <Card title="Inventory" icon="box" href="/api-reference/inventory">
    Access aggregated inventory data from all connected integrations
  </Card>

  <Card title="Alerts" icon="bell" href="/api-reference/alerts">
    Query security issues and Vitals health problems detected across your environment
  </Card>

  <Card title="Vitals" icon="heart-pulse" href="/api-reference/vitals">
    Retrieve security control health status for devices and integrations
  </Card>

  <Card title="Settings" icon="gear" href="/api-reference/settings-users">
    Access portal configuration, tags, teams, roles, and integration settings
  </Card>
</CardGroup>

## 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.

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

## Authentication

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

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X GET "https://{cloudId}.threataware.com/public-api/v1/devices" \
      -H "X-ThreatAware-ApiKey: your-api-key-here"
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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()
    ```
  </Tab>

  <Tab title="JavaScript">
    ```javascript theme={null}
    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));
    ```
  </Tab>

  <Tab title="PowerShell">
    ```powershell theme={null}
    $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
    ```
  </Tab>
</Tabs>

## 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

<Info>
  **Current Rate Limit**: 10 requests per 60 seconds

  Rate limits are applied portal-wide regardless of IP addresses. They may vary based on your ThreatAware plan.
</Info>

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

<Steps>
  <Step title="Generate API Key">
    Navigate to Settings → API Access → Generate Key

    <Warning>
      **Save your API key immediately** - it's only shown once during generation.
    </Warning>
  </Step>

  <Step title="Test Connection">
    Make a test request to verify your API key works. See the [Authentication](#authentication) section above for examples in multiple languages.
  </Step>

  <Step title="Explore Endpoints">
    Browse the [API Endpoints](#api-endpoints) section above or visit [apidocs.threataware.com](https://apidocs.threataware.com) for the complete reference.
  </Step>
</Steps>

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

## Available Endpoints

The ThreatAware API provides access to the following resources:

<AccordionGroup>
  <Accordion title="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:**

    ```bash theme={null}
    GET /public-api/v1/devices
    GET /public-api/v1/devices/{deviceId}
    ```
  </Accordion>

  <Accordion title="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:**

    ```bash theme={null}
    GET /public-api/v1/users
    GET /public-api/v1/users/{userId}
    ```
  </Accordion>

  <Accordion title="Inventory">
    Access aggregated inventory data from all connected integrations.

    **Common Use Cases:**

    * Asset management exports
    * Compliance reporting
    * Hardware tracking

    **Example:**

    ```bash theme={null}
    GET /public-api/v1/inventory/devices
    GET /public-api/v1/inventory/software
    ```
  </Accordion>

  <Accordion title="Alerts & Issues">
    Query security issues and Vitals health problems detected across your environment.

    **Common Use Cases:**

    * SIEM integration
    * SOC dashboards
    * Automated ticket creation

    **Example:**

    ```bash theme={null}
    GET /public-api/v1/alerts
    GET /public-api/v1/issues
    ```
  </Accordion>

  <Accordion title="Vitals">
    Retrieve security control health status for devices and integrations.

    **Common Use Cases:**

    * Security posture dashboards
    * Compliance evidence collection
    * Executive reporting

    **Example:**

    ```bash theme={null}
    GET /public-api/v1/vitals/devices
    GET /public-api/v1/vitals/integrations
    ```
  </Accordion>

  <Accordion title="Settings">
    Access portal configuration, tags, and integration settings.

    **Common Use Cases:**

    * Automation configuration
    * Tag-based reporting
    * Integration status monitoring

    **Example:**

    ```bash theme={null}
    GET /public-api/v1/settings/tags
    GET /public-api/v1/settings/integrations
    ```
  </Accordion>
</AccordionGroup>

## Pagination

ThreatAware's API uses **offset** and **limit** parameters for pagination:

```bash theme={null}
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)

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

## Common Use Cases

<CardGroup cols={2}>
  <Card title="Power BI Integration" icon="chart-line">
    **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
  </Card>

  <Card title="SIEM Integration" icon="shield-halved">
    **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
  </Card>

  <Card title="ServiceNow CMDB Sync" icon="database">
    **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
  </Card>

  <Card title="Custom Reporting" icon="file-export">
    **Goal**: Automated compliance reports

    * Export Vitals status via API
    * Generate PDF/Excel reports
    * Email to stakeholders
    * Archive for audit evidence
  </Card>
</CardGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Error Handling">
    **Handle Failures Gracefully**

    ```python Example: Python Error Handling theme={null}
    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
  </Accordion>

  <Accordion title="Integration Testing">
    **Test Before Production**

    1. Create a test API key
    2. Query a small dataset first
    3. Validate response structure
    4. Test error scenarios (invalid key, rate limits)
    5. Monitor initial production usage closely
    6. Set up alerting for API failures
  </Accordion>
</AccordionGroup>

## Complete API Documentation

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

<Card title="ThreatAware API Documentation" icon="book-open" href="https://apidocs.threataware.com">
  Full API reference with interactive examples and detailed schemas
</Card>

## Support

Need help with the API?

* **Documentation**: [apidocs.threataware.com](https://apidocs.threataware.com)
* **Email Support**: [help@threataware.com](mailto:help@threataware.com)
* **Portal**: Settings → API Access (for key management)

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

## Next Steps

<CardGroup cols={3}>
  <Card title="Integrations" icon="plug" href="/integrations">
    Learn about data sources feeding the API
  </Card>

  <Card title="Automation" icon="bolt" href="/automation">
    Combine API with Actions for workflows
  </Card>

  <Card title="Security Monitoring" icon="shield-halved" href="/security-monitoring">
    Understand Vitals data available via API
  </Card>
</CardGroup>