Documentation > API Reference > Reports API

Reports API

Generate and access comprehensive system reports, inventory data, and analytics through programmatic interfaces.

Overview

The Reports API provides access to various system reports including host inventories, package status, security summaries, and performance analytics. Reports can be generated in multiple formats and scheduled for regular delivery.

Base URL

/api/v1/reports

Authentication

All endpoints require valid JWT authentication with appropriate permissions.

Report Types

Infrastructure Reports

  • Host Inventory: Complete hardware and software inventory
  • Package Status: Installed packages and available updates
  • System Performance: Performance metrics and trends
  • Capacity Planning: Resource utilization and growth projections

Security Reports

  • Vulnerability Assessment: Security vulnerabilities and patches
  • Compliance Status: Security compliance and policy adherence
  • User Activity: User access patterns and administrative actions
  • Security Events: Security incidents and alerts

Operational Reports

  • System Health: Overall system status and uptime
  • Maintenance Summary: Maintenance activities and schedules
  • Backup Status: Backup completion and integrity reports
  • Change Log: System changes and modifications

API Endpoints

Get Available Reports

GET /api/v1/reports

Retrieve a list of all available report types and their descriptions.

Request

GET /api/v1/reports
Authorization: Bearer {jwt_token}
Content-Type: application/json

Response

{
  "reports": [
    {
      "id": "host_inventory",
      "name": "Host Inventory",
      "description": "Complete hardware and software inventory for all hosts",
      "category": "infrastructure",
      "formats": ["json", "csv", "pdf"],
      "parameters": ["host_ids", "include_software", "include_hardware"]
    },
    {
      "id": "package_status",
      "name": "Package Status",
      "description": "Package installation status and available updates",
      "category": "infrastructure",
      "formats": ["json", "csv", "excel"],
      "parameters": ["host_ids", "package_names", "show_updates"]
    }
  ]
}

Generate Report

POST /api/v1/reports/generate

Generate a new report with specified parameters and format.

Request

POST /api/v1/reports/generate
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "report_type": "host_inventory",
  "format": "pdf",
  "parameters": {
    "host_ids": ["host-uuid-1", "host-uuid-2"],
    "include_software": true,
    "include_hardware": true,
    "date_range": {
      "start": "2024-01-01",
      "end": "2024-01-31"
    }
  },
  "delivery": {
    "method": "download",
    "email": "admin@example.com"
  }
}

Response

{
  "report_id": "rpt_123456789",
  "status": "generating",
  "estimated_completion": "2024-01-15T10:35:00Z",
  "download_url": null,
  "created_at": "2024-01-15T10:30:00Z"
}

Get Report Status

GET /api/v1/reports/{report_id}/status

Check the generation status of a specific report.

Request

GET /api/v1/reports/rpt_123456789/status
Authorization: Bearer {jwt_token}

Response

{
  "report_id": "rpt_123456789",
  "status": "completed",
  "progress": 100,
  "download_url": "/api/v1/reports/rpt_123456789/download",
  "expires_at": "2024-01-22T10:30:00Z",
  "file_size": 2048576,
  "generated_at": "2024-01-15T10:35:22Z"
}

Download Report

GET /api/v1/reports/{report_id}/download

Download the generated report file.

Request

GET /api/v1/reports/rpt_123456789/download
Authorization: Bearer {jwt_token}

Response

Returns the report file with appropriate Content-Type header based on format.

Content-Type: application/pdf
Content-Disposition: attachment; filename="host_inventory_2024-01-15.pdf"
Content-Length: 2048576

[Binary file content]

Host Inventory Report

GET /api/v1/reports/hosts/inventory

Get real-time host inventory data in JSON format.

Query Parameters

  • host_ids - Comma-separated list of host UUIDs
  • include_software - Include software inventory (default: true)
  • include_hardware - Include hardware details (default: true)
  • format - Response format: json, csv (default: json)

Request

GET /api/v1/reports/hosts/inventory?include_software=true&include_hardware=true
Authorization: Bearer {jwt_token}

Response

{
  "report_meta": {
    "generated_at": "2024-01-15T10:30:00Z",
    "total_hosts": 25,
    "parameters": {
      "include_software": true,
      "include_hardware": true
    }
  },
  "hosts": [
    {
      "id": "host-uuid-1",
      "hostname": "web-server-01",
      "ip_address": "192.168.1.10",
      "os": {
        "name": "Ubuntu",
        "version": "22.04 LTS",
        "kernel": "5.15.0-91-generic"
      },
      "hardware": {
        "cpu": {
          "model": "Intel(R) Xeon(R) CPU E5-2686 v4 @ 2.30GHz",
          "cores": 4,
          "threads": 8
        },
        "memory": {
          "total": "16GB",
          "available": "12GB"
        },
        "storage": [
          {
            "device": "/dev/sda1",
            "size": "100GB",
            "used": "45GB",
            "filesystem": "ext4"
          }
        ]
      },
      "software": {
        "packages": [
          {
            "name": "nginx",
            "version": "1.18.0-6ubuntu14.4",
            "status": "installed"
          },
          {
            "name": "postgresql",
            "version": "14.9-0ubuntu0.22.04.1",
            "status": "installed"
          }
        ],
        "services": [
          {
            "name": "nginx",
            "status": "active",
            "enabled": true
          }
        ]
      },
      "last_seen": "2024-01-15T10:29:45Z",
      "agent_version": "1.0.0"
    }
  ]
}

Package Status Report

GET /api/v1/reports/packages/status

Get comprehensive package status across all hosts.

Query Parameters

  • host_ids - Filter by specific hosts
  • package_names - Filter by specific packages
  • show_updates - Include available updates (default: true)
  • security_only - Show only security updates (default: false)

Request

GET /api/v1/reports/packages/status?show_updates=true&security_only=false
Authorization: Bearer {jwt_token}

Response

{
  "report_meta": {
    "generated_at": "2024-01-15T10:30:00Z",
    "total_hosts": 25,
    "total_packages": 1250,
    "packages_with_updates": 89,
    "security_updates": 12
  },
  "summary": {
    "by_status": {
      "up_to_date": 1161,
      "updates_available": 89,
      "security_updates": 12,
      "unknown": 0
    },
    "by_package_manager": {
      "apt": 800,
      "yum": 300,
      "brew": 100,
      "chocolatey": 50
    }
  },
  "packages": [
    {
      "name": "nginx",
      "hosts_count": 15,
      "versions": [
        {
          "version": "1.18.0-6ubuntu14.4",
          "hosts": 12,
          "status": "up_to_date"
        },
        {
          "version": "1.18.0-6ubuntu14.3",
          "hosts": 3,
          "status": "update_available",
          "security_update": false
        }
      ]
    },
    {
      "name": "openssl",
      "hosts_count": 25,
      "versions": [
        {
          "version": "3.0.2-0ubuntu1.12",
          "hosts": 20,
          "status": "up_to_date"
        },
        {
          "version": "3.0.2-0ubuntu1.10",
          "hosts": 5,
          "status": "security_update_available",
          "security_update": true,
          "cve_references": ["CVE-2023-5678", "CVE-2023-5679"]
        }
      ]
    }
  ]
}

Security Report

GET /api/v1/reports/security/vulnerabilities

Get security vulnerability assessment across all hosts.

Query Parameters

  • severity - Filter by severity: critical, high, medium, low
  • host_ids - Filter by specific hosts
  • include_patched - Include patched vulnerabilities (default: false)

Request

GET /api/v1/reports/security/vulnerabilities?severity=critical,high
Authorization: Bearer {jwt_token}

Response

{
  "report_meta": {
    "generated_at": "2024-01-15T10:30:00Z",
    "total_vulnerabilities": 45,
    "by_severity": {
      "critical": 3,
      "high": 12,
      "medium": 20,
      "low": 10
    }
  },
  "vulnerabilities": [
    {
      "cve_id": "CVE-2023-5678",
      "severity": "critical",
      "score": 9.8,
      "description": "Remote code execution vulnerability in OpenSSL",
      "affected_packages": ["openssl", "libssl3"],
      "affected_hosts": [
        {
          "id": "host-uuid-1",
          "hostname": "web-server-01",
          "package": "openssl",
          "current_version": "3.0.2-0ubuntu1.10",
          "fixed_version": "3.0.2-0ubuntu1.12",
          "patch_available": true
        }
      ],
      "references": [
        "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2023-5678",
        "https://ubuntu.com/security/notices/USN-6234-1"
      ],
      "published_date": "2023-12-15T00:00:00Z",
      "discovered_date": "2024-01-10T08:00:00Z"
    }
  ]
}

Performance Report

GET /api/v1/reports/performance/summary

Get system performance summary and trends.

Query Parameters

  • time_range - Time range: 1h, 24h, 7d, 30d (default: 24h)
  • host_ids - Filter by specific hosts
  • metrics - Specific metrics: cpu, memory, disk, network

Request

GET /api/v1/reports/performance/summary?time_range=24h&metrics=cpu,memory
Authorization: Bearer {jwt_token}

Response

{
  "report_meta": {
    "generated_at": "2024-01-15T10:30:00Z",
    "time_range": "24h",
    "total_hosts": 25,
    "metrics_included": ["cpu", "memory"]
  },
  "summary": {
    "cpu": {
      "average_utilization": 35.2,
      "peak_utilization": 89.5,
      "hosts_over_threshold": 3,
      "threshold": 80.0
    },
    "memory": {
      "average_utilization": 62.8,
      "peak_utilization": 95.2,
      "hosts_over_threshold": 1,
      "threshold": 90.0
    }
  },
  "top_consumers": {
    "cpu": [
      {
        "host_id": "host-uuid-3",
        "hostname": "app-server-01",
        "average_cpu": 78.5,
        "peak_cpu": 89.5
      }
    ],
    "memory": [
      {
        "host_id": "host-uuid-5",
        "hostname": "db-server-01",
        "average_memory": 87.2,
        "peak_memory": 95.2
      }
    ]
  },
  "alerts_triggered": [
    {
      "host_id": "host-uuid-5",
      "hostname": "db-server-01",
      "metric": "memory",
      "threshold": 90.0,
      "value": 95.2,
      "timestamp": "2024-01-15T09:45:00Z"
    }
  ]
}

Scheduled Reports

GET /api/v1/reports/scheduled

Manage scheduled report generation and delivery.

Request

GET /api/v1/reports/scheduled
Authorization: Bearer {jwt_token}

Response

{
  "scheduled_reports": [
    {
      "id": "sched_001",
      "name": "Weekly Security Report",
      "report_type": "security_vulnerabilities",
      "schedule": "0 8 * * 1",
      "parameters": {
        "severity": "critical,high",
        "format": "pdf"
      },
      "delivery": {
        "method": "email",
        "recipients": ["security@example.com", "admin@example.com"]
      },
      "enabled": true,
      "last_run": "2024-01-08T08:00:00Z",
      "next_run": "2024-01-15T08:00:00Z"
    }
  ]
}

Create Scheduled Report

POST /api/v1/reports/scheduled

Create a new scheduled report.

Request

POST /api/v1/reports/scheduled
Authorization: Bearer {jwt_token}
Content-Type: application/json

{
  "name": "Monthly Host Inventory",
  "report_type": "host_inventory",
  "schedule": "0 9 1 * *",
  "parameters": {
    "include_software": true,
    "include_hardware": true,
    "format": "excel"
  },
  "delivery": {
    "method": "email",
    "recipients": ["operations@example.com"]
  },
  "enabled": true
}

Response

{
  "id": "sched_002",
  "name": "Monthly Host Inventory",
  "status": "created",
  "next_run": "2024-02-01T09:00:00Z",
  "created_at": "2024-01-15T10:30:00Z"
}

Report Formats

Supported Formats

  • JSON: Structured data for API consumption
  • CSV: Comma-separated values for spreadsheet import
  • Excel: Microsoft Excel format with multiple sheets
  • PDF: Formatted reports for presentation and printing
  • HTML: Web-viewable reports with interactive elements

Format-Specific Features

PDF Reports

  • Professional formatting with company branding
  • Charts, graphs, and visual elements
  • Executive summary and detailed sections
  • Automatic table of contents and page numbering

Excel Reports

  • Multiple worksheets for different data types
  • Pivot tables and charts
  • Conditional formatting for quick analysis
  • Data validation and filtering

CSV Reports

  • Raw data export for analysis tools
  • UTF-8 encoding for international characters
  • Configurable delimiters and quoting
  • Optimized for large datasets

Error Handling

Common Error Responses

400 Bad Request

{
  "error": "invalid_parameters",
  "message": "Invalid report type specified",
  "details": {
    "valid_types": ["host_inventory", "package_status", "security_vulnerabilities"]
  }
}

404 Not Found

{
  "error": "report_not_found",
  "message": "Report with ID 'rpt_invalid' not found",
  "report_id": "rpt_invalid"
}

422 Processing Error

{
  "error": "report_generation_failed",
  "message": "Failed to generate report due to data inconsistency",
  "details": {
    "failed_hosts": ["host-uuid-1", "host-uuid-2"],
    "reason": "Agent communication timeout"
  }
}

Code Examples

Python Example

import requests
import time

# Generate a security vulnerabilities report
def generate_security_report(api_base, token):
    headers = {
        'Authorization': f'Bearer {token}',
        'Content-Type': 'application/json'
    }

    # Request report generation
    report_request = {
        'report_type': 'security_vulnerabilities',
        'format': 'pdf',
        'parameters': {
            'severity': 'critical,high',
            'include_patched': False
        }
    }

    response = requests.post(
        f'{api_base}/reports/generate',
        headers=headers,
        json=report_request
    )

    if response.status_code == 200:
        report_data = response.json()
        report_id = report_data['report_id']

        # Poll for completion
        while True:
            status_response = requests.get(
                f'{api_base}/reports/{report_id}/status',
                headers=headers
            )

            status_data = status_response.json()

            if status_data['status'] == 'completed':
                # Download the report
                download_response = requests.get(
                    f'{api_base}/reports/{report_id}/download',
                    headers=headers
                )

                with open(f'security_report_{report_id}.pdf', 'wb') as f:
                    f.write(download_response.content)

                print(f"Report downloaded: security_report_{report_id}.pdf")
                break

            elif status_data['status'] == 'failed':
                print("Report generation failed")
                break

            time.sleep(5)  # Wait 5 seconds before checking again

    else:
        print(f"Failed to generate report: {response.status_code}")

# Usage
api_base = "https://your-server.example.com/api/v1"
token = "your_jwt_token_here"
generate_security_report(api_base, token)

JavaScript Example

// Generate and download host inventory report
async function generateHostInventoryReport(apiBase, token) {
    const headers = {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    };

    try {
        // Generate report
        const generateResponse = await fetch(`${apiBase}/reports/generate`, {
            method: 'POST',
            headers: headers,
            body: JSON.stringify({
                report_type: 'host_inventory',
                format: 'excel',
                parameters: {
                    include_software: true,
                    include_hardware: true
                }
            })
        });

        const reportData = await generateResponse.json();
        const reportId = reportData.report_id;

        // Poll for completion
        const pollInterval = setInterval(async () => {
            const statusResponse = await fetch(
                `${apiBase}/reports/${reportId}/status`,
                { headers }
            );

            const statusData = await statusResponse.json();

            if (statusData.status === 'completed') {
                clearInterval(pollInterval);

                // Create download link
                const downloadUrl = `${apiBase}/reports/${reportId}/download`;
                const link = document.createElement('a');
                link.href = downloadUrl;
                link.download = `host_inventory_${new Date().toISOString().split('T')[0]}.xlsx`;
                link.click();

                console.log('Report download initiated');
            } else if (statusData.status === 'failed') {
                clearInterval(pollInterval);
                console.error('Report generation failed');
            }
        }, 5000);

    } catch (error) {
        console.error('Error generating report:', error);
    }
}

// Usage
const apiBase = 'https://your-server.example.com/api/v1';
const token = 'your_jwt_token_here';
generateHostInventoryReport(apiBase, token);

Quick Navigation

← Monitoring API User Management API →