Reports API

Generate and download security reports programmatically.

List Reports

GET /reports

Retrieve previously generated reports.

Query Parameters

Parameter	Type	Description
`application_id`	string	Filter by application
`type`	string	`technical`, `executive`, `soc2`, `compliance`
`page`	integer	Page number
`per_page`	integer	Items per page

Response

{
  "data": [
    {
      "id": "rpt_abc123",
      "type": "technical",
      "format": "pdf",
      "application_id": "app_abc123",
      "application_name": "Production App",
      "scan_id": "scan_xyz789",
      "status": "ready",
      "created_at": "2025-01-15T11:00:00Z",
      "expires_at": "2025-02-14T11:00:00Z",
      "size_bytes": 1245678
    }
  ],
  "meta": {
    "total": 10,
    "page": 1,
    "per_page": 20
  }
}

Get Report

GET /reports/{id}

Get metadata about a specific report.

Response

{
  "id": "rpt_abc123",
  "type": "technical",
  "format": "pdf",
  "application_id": "app_abc123",
  "application_name": "Production App",
  "scan_id": "scan_xyz789",
  "status": "ready",
  "created_at": "2025-01-15T11:00:00Z",
  "expires_at": "2025-02-14T11:00:00Z",
  "size_bytes": 1245678,
  "download_url": "https://api.modernpentest.com/v1/reports/rpt_abc123/download",
  "contents": {
    "findings_included": 30,
    "pages": 45,
    "sections": ["executive_summary", "findings", "remediation", "appendix"]
  }
}

Generate Report

POST /reports

Generate a new report for a scan.

Request Body

{
  "scan_id": "scan_xyz789",
  "type": "technical",
  "format": "pdf",
  "options": {
    "include_sections": ["summary", "findings", "remediation"],
    "severity_threshold": "medium",
    "include_fixed": false
  }
}

Parameters

Field	Type	Required	Description
`scan_id`	string	Yes	Source scan ID
`type`	string	Yes	Report type
`format`	string	No	`pdf`, `html`, `json` (default: `pdf`)
`options`	object	No	Report customization

Report Types

Type	Description
`technical`	Detailed findings for developers
`executive`	High-level summary for leadership
`soc2`	SOC 2 compliance documentation
`compliance`	General compliance mapping

Response

{
  "id": "rpt_new456",
  "type": "technical",
  "format": "pdf",
  "status": "generating",
  "created_at": "2025-01-15T12:00:00Z",
  "estimated_completion": "2025-01-15T12:02:00Z"
}

Report generation is asynchronous. Poll the report status or use webhooks.

Example

curl -X POST https://api.modernpentest.com/v1/reports \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scan_id": "scan_xyz789",
    "type": "soc2",
    "format": "pdf"
  }'

Download Report

GET /reports/{id}/download

Download the generated report file.

Response

Returns the binary file with appropriate Content-Type:

PDF: application/pdf
HTML: text/html
JSON: application/json

Example

curl -X GET https://api.modernpentest.com/v1/reports/rpt_abc123/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o security_report.pdf

Generate SOC 2 Report

POST /reports/soc2

Generate a SOC 2 compliance report for a date range.

Request Body

{
  "application_ids": ["app_abc123", "app_xyz789"],
  "date_from": "2024-10-01T00:00:00Z",
  "date_to": "2024-12-31T23:59:59Z",
  "format": "pdf",
  "options": {
    "include_remediation_evidence": true,
    "include_scan_timeline": true
  }
}

Parameters

Field	Type	Required	Description
`application_ids`	array	Yes	Applications to include
`date_from`	string	Yes	Audit period start (ISO 8601)
`date_to`	string	Yes	Audit period end (ISO 8601)
`format`	string	No	`pdf` or `html`
`options`	object	No	Report options

SOC 2 Report Contents

The generated report includes:

Section	Description
Executive Summary	Overall security posture
Testing Methodology	How testing was performed
Trust Services Mapping	CC4.1, CC7.1 criteria mapping
Vulnerability Findings	All findings with status
Remediation Evidence	Proof of fixes
Testing Timeline	Complete audit trail

Response

{
  "id": "rpt_soc2_123",
  "type": "soc2",
  "status": "generating",
  "audit_period": {
    "from": "2024-10-01T00:00:00Z",
    "to": "2024-12-31T23:59:59Z"
  },
  "applications_included": 2,
  "estimated_completion": "2025-01-15T12:05:00Z"
}

Report Status

GET /reports/{id}/status

Check the generation status of a report.

Response

{
  "id": "rpt_abc123",
  "status": "ready",
  "progress": 100,
  "created_at": "2025-01-15T12:00:00Z",
  "completed_at": "2025-01-15T12:02:00Z"
}

Status Values

Status	Description
`pending`	Queued for generation
`generating`	Currently being created
`ready`	Available for download
`failed`	Generation failed
`expired`	Download link expired

Webhook Events

Reports trigger the following webhook events:

Event	Description
`report.generating`	Report generation started
`report.ready`	Report available for download
`report.failed`	Report generation failed

See Webhooks for configuration.

Last updated: December 8, 2025

Reports

On this page