Skip to main content

Reports API Reference

The Reports API enables programmatic generation, scheduling, and management of security reports. Generate custom PDF reports, manage automated schedules, and configure organization branding.

Authentication​

All Reports API endpoints require authentication via API token:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Report Generation​

Generate Report​

POST /api/v1/reports/generate

Request Body:

{
  "report_type": "executive_summary",
  "date_range": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  },
  "filters": {
    "site_ids": ["site_456", "site_457"],
    "device_types": ["plc", "hmi"],
    "risk_levels": ["high", "medium"]
  },
  "format": "pdf",
  "delivery": {
    "email": true,
    "recipients": ["manager@company.com", "security@company.com"],
    "include_summary": true
  }
}

Response:

{
  "report_id": "report_abc123",
  "status": "generating",
  "report_type": "executive_summary",
  "estimated_completion": "2024-01-21T11:15:00Z",
  "download_url": null,
  "created_at": "2024-01-21T11:00:00Z"
}

Preview Report​

POST /api/v1/reports/preview

Request Body:

{
  "report_type": "asset_inventory",
  "date_range": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  },
  "filters": {
    "site_ids": ["site_456"]
  },
  "format": "html"
}

Response:

{
  "preview_id": "preview_def456",
  "status": "ready",
  "preview_url": "https://reports.breakwater.techgonecoastal.com/preview/preview_def456",
  "expires_at": "2024-01-21T15:00:00Z",
  "page_count": 8,
  "data_points": 156
}

Report Types and Templates​

Get Available Report Types​

GET /api/v1/reports/types

Response:

{
  "report_types": [
    {
      "id": "executive_summary",
      "name": "Executive Summary",
      "description": "High-level security posture overview for executive audiences",
      "category": "executive",
      "typical_length": "2-4 pages",
      "supported_formats": ["pdf", "html"],
      "filters": ["site_ids", "date_range", "risk_levels"]
    },
    {
      "id": "asset_inventory",
      "name": "Asset Inventory",
      "description": "Comprehensive device and system documentation",
      "category": "operational",
      "typical_length": "10-50 pages",
      "supported_formats": ["pdf", "html", "excel"],
      "filters": ["site_ids", "device_types", "device_status"]
    },
    {
      "id": "certificate_health",
      "name": "Certificate Health",
      "description": "SSL/TLS certificate management and compliance status",
      "category": "security",
      "typical_length": "5-15 pages",
      "supported_formats": ["pdf", "html"],
      "filters": ["site_ids", "certificate_status", "expiring_within"]
    },
    {
      "id": "threat_intelligence",
      "name": "Threat Intelligence",
      "description": "Security threat landscape and vulnerability assessment",
      "category": "security",
      "typical_length": "8-20 pages",
      "supported_formats": ["pdf", "html"],
      "filters": ["site_ids", "threat_types", "severity_levels"]
    },
    {
      "id": "risk_quantification",
      "name": "Risk Quantification",
      "description": "Business risk assessment and financial impact analysis",
      "category": "risk",
      "typical_length": "6-12 pages",
      "supported_formats": ["pdf", "html"],
      "filters": ["site_ids", "risk_categories", "business_units"]
    }
  ]
}

Generate PDF Report​

GET /api/v1/reports/generate-pdf/{report_type}

Query Parameters:

  • start_date: Start date for report data (YYYY-MM-DD)
  • end_date: End date for report data (YYYY-MM-DD)
  • site_ids: Comma-separated list of site IDs (optional)
  • format: Output format (pdf, html, excel)
  • include_raw_data: Include raw data appendix (true/false, default: false)

Response:

Content-Type: application/pdf
Content-Disposition: attachment; filename="executive-summary-2024-01-21.pdf"

[Binary PDF content]

Organization Branding​

Get Organization Branding​

GET /api/v1/reports/branding

Response:

{
  "organization": {
    "name": "Manufacturing Corp",
    "industry": "Manufacturing",
    "logo_url": "https://cdn.breakwater.techgonecoastal.com/logos/org_123.png",
    "primary_color": "#1E3A8A",
    "secondary_color": "#3B82F6",
    "accent_color": "#EF4444"
  },
  "contact_info": {
    "address": "123 Industrial Blvd, Manufacturing City, ST 12345",
    "phone": "+1 (555) 123-4567",
    "email": "security@manufacturingcorp.com",
    "website": "https://manufacturingcorp.com"
  },
  "legal": {
    "confidentiality_statement": "This report contains confidential information...",
    "disclaimer": "The information contained in this report..."
  }
}

Update Organization Branding​

POST /api/v1/reports/branding

Request Body:

{
  "organization": {
    "name": "Manufacturing Corp",
    "industry": "Manufacturing",
    "primary_color": "#1E3A8A",
    "secondary_color": "#3B82F6",
    "accent_color": "#EF4444"
  },
  "contact_info": {
    "address": "123 Industrial Blvd, Manufacturing City, ST 12345",
    "phone": "+1 (555) 123-4567",
    "email": "security@manufacturingcorp.com",
    "website": "https://manufacturingcorp.com"
  },
  "logo_upload": {
    "image_data": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "filename": "company-logo.png"
  }
}

Response:

{
  "message": "Branding updated successfully",
  "logo_url": "https://cdn.breakwater.techgonecoastal.com/logos/org_123.png",
  "updated_at": "2024-01-21T11:30:00Z"
}

Scheduled Reports​

Get Scheduled Reports​

GET /api/v1/reports/schedules/{report_type}

Response:

{
  "schedule": {
    "report_type": "weekly_threat_briefing",
    "enabled": true,
    "cron_expression": "0 9 * * MON",
    "timezone": "America/New_York",
    "recipients": [
      {
        "email": "security@company.com",
        "role": "Security Team"
      },
      {
        "email": "manager@company.com", 
        "role": "IT Manager"
      }
    ],
    "filters": {
      "site_ids": ["site_456", "site_457"],
      "include_resolved": false
    },
    "delivery_options": {
      "format": "pdf",
      "include_summary": true,
      "attach_raw_data": false
    },
    "last_run": "2024-01-15T09:00:00Z",
    "next_run": "2024-01-22T09:00:00Z"
  }
}

Create or Update Schedule​

PUT /api/v1/reports/schedules/{report_type}

Request Body:

{
  "enabled": true,
  "cron_expression": "0 9 1 * *",
  "timezone": "America/New_York",
  "recipients": [
    {
      "email": "executive@company.com",
      "role": "Executive Team"
    }
  ],
  "filters": {
    "site_ids": ["site_456"],
    "risk_levels": ["high", "medium"]
  },
  "delivery_options": {
    "format": "pdf",
    "include_summary": true
  }
}

Response:

{
  "report_type": "monthly_asset_report",
  "enabled": true,
  "cron_expression": "0 9 1 * *",
  "next_run": "2024-02-01T09:00:00Z",
  "updated_at": "2024-01-21T11:45:00Z"
}

Delete Schedule​

DELETE /api/v1/reports/schedules/{report_type}

Response:

{
  "message": "Schedule deleted successfully",
  "report_type": "weekly_threat_briefing"
}

Report History​

Get Report History​

GET /api/v1/reports/history

Query Parameters:

  • report_type (optional): Filter by report type
  • status (optional): Filter by status (completed, generating, failed)
  • start_date (optional): Start date for history range
  • end_date (optional): End date for history range
  • limit (optional): Maximum number of results (default: 50)
  • offset (optional): Pagination offset (default: 0)

Response:

{
  "reports": [
    {
      "report_id": "report_abc123",
      "report_type": "executive_summary",
      "status": "completed",
      "generated_at": "2024-01-21T11:15:00Z",
      "generation_time": "00:02:30",
      "file_size": "2.4 MB",
      "page_count": 4,
      "download_url": "https://reports.breakwater.techgonecoastal.com/download/report_abc123.pdf",
      "expires_at": "2024-02-21T11:15:00Z",
      "delivery": {
        "email_sent": true,
        "recipients": 2,
        "delivery_time": "2024-01-21T11:16:30Z"
      }
    }
  ],
  "total": 1,
  "limit": 50,
  "offset": 0
}

Error Handling​

Standard Error Response​

{
  "error": {
    "code": "INVALID_REPORT_TYPE",
    "message": "Report type 'invalid_type' is not supported",
    "details": {
      "report_type": "invalid_type",
      "supported_types": ["executive_summary", "asset_inventory", "certificate_health", "threat_intelligence", "risk_quantification"]
    }
  }
}

Common Error Codes​

  • INVALID_REPORT_TYPE: Specified report type not supported
  • INVALID_DATE_RANGE: Start date must be before end date
  • INSUFFICIENT_DATA: Not enough data for specified filters
  • GENERATION_FAILED: Report generation encountered an error
  • DOWNLOAD_EXPIRED: Report download link has expired
  • SCHEDULE_CONFLICT: Conflicting schedule configuration
  • RECIPIENT_INVALID: Invalid email address format
  • BRANDING_UPLOAD_FAILED: Logo upload processing failed
  • INSUFFICIENT_PERMISSIONS: API token lacks required permissions

Webhooks​

Report Generation Events​

Configure webhooks to receive notifications when reports are generated:

{
  "event": "report.generated",
  "timestamp": "2024-01-21T11:15:00Z",
  "data": {
    "report_id": "report_abc123",
    "report_type": "executive_summary",
    "status": "completed",
    "download_url": "https://reports.breakwater.techgonecoastal.com/download/report_abc123.pdf",
    "organization_id": "org_123"
  }
}

Schedule Execution Events​

{
  "event": "schedule.executed",
  "timestamp": "2024-01-22T09:00:00Z",
  "data": {
    "schedule_type": "weekly_threat_briefing",
    "report_id": "report_def456",
    "status": "completed",
    "recipients": 2,
    "organization_id": "org_123"
  }
}

Rate Limiting​

The Reports API implements rate limiting:

  • Report Generation: Maximum 10 reports per hour per organization
  • API Requests: 1000 requests per hour per API token
  • Scheduled Reports: Maximum 20 active schedules per organization

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1642770000