Documentation

PolicyCortex Reports API: Generate & Manage Compliance Reports

The Reports API provides comprehensive reporting capabilities for compliance documentation, executive summaries, and detailed audit trails. Generate custom reports, schedule automated delivery, and export data in multiple formats for regulatory requirements and stakeholder communication.

Reports API Documentation Overview: Quick Start & Setup

API Overview

📊 Compliance Reports

Generate framework-specific compliance reports for SOC2, HIPAA, ISO27001, and custom frameworks.

• Framework-specific templates

• Executive and technical views

• Audit trail documentation

📈 Analytics & Insights

Advanced analytics with trend analysis, risk scoring, and predictive compliance insights.

• Trend analysis & forecasting

• Risk correlation analysis

• Performance benchmarking

🔄 Automated Delivery

Schedule automated report generation and delivery to stakeholders via email, Slack, or webhooks.

• Flexible scheduling options

• Multi-channel delivery

• Custom report templates

Report Types and Formats

Report Types

• Compliance Summary - Executive overview

• Detailed Audit - Technical compliance details

• Risk Assessment - Security risk analysis

• Trend Analysis - Historical performance

• Remediation Plan - Action-oriented reports

Export Formats

• PDF - Professional formatted reports

• Excel - Spreadsheet with data tables

• CSV - Raw data export

• JSON - Structured data format

• HTML - Web-friendly format

List Reports

GET/v1/reports

Retrieve a list of generated reports with filtering by type, status, framework, and generation date. Includes metadata about report content and access permissions.

Request Examplebash

curl -X GET "https://api.policycortex.com/v1/reports?limit=20&type=compliance&framework=soc2&status=completed" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Query Parameters

limitNumber of reports to return (max 100, default 20)

offsetNumber of reports to skip for pagination

typeFilter by type (compliance, audit, risk, trend, remediation)

frameworkFilter by framework (soc2, hipaa, iso27001, pci)

statusFilter by status (pending, generating, completed, failed)

Response Example

Success Response (200 OK)json

{
  "reports": [
    {
      "id": "rpt_1234567890abcdef",
      "name": "Q1 2024 SOC 2 Compliance Report",
      "type": "compliance",
      "framework": "soc2",
      "status": "completed",
      "generated_at": "2024-04-01T10:00:00Z",
      "size": {
        "pages": 47,
        "file_size_mb": 8.3
      },
      "summary": {
        "compliance_score": 96.3,
        "total_violations": 18,
        "critical_findings": 2
      }
    }
  ],
  "pagination": {
    "total": 234,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Get Report Details

GET/v1/reports/:report_id

Retrieve detailed information about a specific report, including metadata, summary statistics, download links, and sharing permissions.

Request Examplebash

curl -X GET "https://api.policycortex.com/v1/reports/rpt_1234567890abcdef" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json"

Response Example

Success Response (200 OK)json

{
  "id": "rpt_1234567890abcdef",
  "name": "Q1 2024 SOC 2 Compliance Report",
  "type": "compliance",
  "framework": "soc2",
  "status": "completed",
  "generated_at": "2024-04-01T10:00:00Z",
  "content": {
    "pages": 47,
    "sections": [
      {"name": "Executive Summary", "pages": 3},
      {"name": "Control Assessment", "pages": 28},
      {"name": "Findings", "pages": 12}
    ]
  },
  "formats": [
    {
      "format": "pdf",
      "url": "https://api.policycortex.com/v1/reports/rpt_1234567890abcdef/download/pdf",
      "size_mb": 8.3
    }
  ],
  "summary": {
    "overall_compliance_score": 96.3,
    "total_violations": 18,
    "critical": 2,
    "high": 4
  }
}

Generate Report

POST/v1/reports

Generate a new compliance or audit report with customizable scope, formatting, and delivery options. Supports both immediate generation and scheduled delivery.

Request Examplebash

curl -X POST "https://api.policycortex.com/v1/reports" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Security Assessment",
    "type": "audit",
    "framework": "iso27001",
    "description": "Monthly security audit for ISO 27001 compliance",
    "scope": {
      "environments": ["production", "staging"],
      "cloud_providers": ["aws", "azure", "gcp"],
      "date_range": {
        "start": "2024-01-01T00:00:00Z",
        "end": "2024-01-31T23:59:59Z"
      }
    },
    "format_options": {
      "formats": ["pdf", "excel"],
      "include_executive_summary": true,
      "include_detailed_findings": true
    },
    "delivery": {
      "immediate": false,
      "scheduled_at": "2024-02-01T09:00:00Z",
      "notifications": {
        "email": ["compliance@company.com"]
      }
    }
  }'

Required Fields

name: Report name
type: Report type
scope: Report scope and filtering

Optional Fields

framework: Compliance framework
format_options: Formatting preferences
delivery: Delivery settings

Response Example

Success Response (201 Created)json

{
  "id": "rpt_abcdef1234567890",
  "name": "Monthly Security Assessment",
  "type": "audit",
  "framework": "iso27001",
  "status": "pending",
  "estimated_completion": "2024-02-01T09:15:00Z",
  "estimated_duration": "15m",
  "queue_position": 1,
  "monitoring": {
    "progress_url": "https://api.policycortex.com/v1/reports/rpt_abcdef1234567890"
  }
}

Download Report

GET/v1/reports/:report_id/download/:format

Download a generated report in the specified format. Supports PDF, Excel, CSV, JSON, and HTML formats with optional password protection and temporary access links.

Request Examplebash

# Download PDF format
curl -X GET "https://api.policycortex.com/v1/reports/rpt_1234567890abcdef/download/pdf" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -o "compliance_report.pdf"

# Get temporary download link
curl -X POST "https://api.policycortex.com/v1/reports/rpt_1234567890abcdef/download-link" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{"format": "pdf", "expires_in": 3600}'

📁 Format Options

PDF

Professional formatted report with charts

Excel

Multi-worksheet format with raw data

CSV

Raw data export for analysis

JSON

Structured data for integrations

🔒 Security Features

• Password protection for sensitive reports
• Temporary download links with expiration
• File integrity verification (SHA256)
• Access logging and audit trails
• Watermarked documents
• Digital signatures

Scheduled Reports

POST/v1/reports/schedules

Create automated report generation schedules with flexible timing, customizable templates, and multi-channel delivery options.

Request Examplebash

curl -X POST "https://api.policycortex.com/v1/reports/schedules" \
  -H "Authorization: Bearer sk_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly Executive Compliance Report",
    "description": "Automated monthly compliance summary for executive team",
    "schedule": {
      "cron": "0 9 1 * *",
      "timezone": "America/New_York"
    },
    "report_template": {
      "name": "Executive Summary Template",
      "type": "compliance",
      "framework": "soc2",
      "scope": {
        "environments": ["production"],
        "date_range_type": "last_month"
      }
    },
    "delivery": {
      "email": {
        "recipients": ["ceo@company.com", "cto@company.com"],
        "subject": "Monthly Compliance Report - {{date}}"
      },
      "slack": {
        "channel": "#executive-reports"
      }
    },
    "enabled": true
  }'

📅 Schedule Templates

Daily at 9 AM

0 9 * * *

Weekly on Monday

0 9 * * 1

Monthly on 1st

0 9 1 * *

Quarterly

0 9 1 */3 *

📧 Delivery Options

• Email - Automated email delivery
• Slack - Channel notifications
• Teams - Microsoft Teams integration
• Webhooks - Custom API endpoints
• SFTP - Secure file transfer
• Cloud Storage - S3, Azure Blob, GCS

Error Responses

400 Bad Request

Invalid report configuration

Error Responsejson

{
  "error": "invalid_report_config",
  "error_description": "Report configuration validation failed",
  "error_code": "RPT_001",
  "details": [
    {
      "field": "scope.date_range.start",
      "message": "Start date cannot be in the future"
    }
  ],
  "timestamp": "2024-01-21T16:00:00Z"
}

404 Not Found

Report not found or expired

Error Responsejson

{
  "error": "report_not_found",
  "error_description": "The requested report was not found or has expired",
  "error_code": "RPT_002",
  "report_id": "rpt_invalid123",
  "possible_causes": [
    "Report ID is invalid",
    "Report has been deleted",
    "Download link has expired"
  ],
  "timestamp": "2024-01-21T16:00:00Z"
}