Reports API

Reports API

Generate and download penetration test reports via the API.

Endpoints

Method	Endpoint	Description
GET	/reports	List generated reports
GET	/reports/{id}	Get report metadata
GET	/reports/{id}/download	Download report file
POST	/reports/generate	Generate new report
DELETE	/reports/{id}	Delete report

Report Object

{
  "id": "report_abc123",
  "project_id": "proj_xyz789",
  "name": "Q1 2024 Pentest Report",
  "template_id": "template_default",
  "format": "docx",
  "status": "completed",
  "file_size": 2548000,
  "findings_count": 12,
  "generated_by": "user_123",
  "generated_at": "2024-01-30T15:00:00Z",
  "download_url": "/reports/report_abc123/download"
}

List Reports

GET /reports

Query Parameters

Parameter	Type	Description
project_id	string	Filter by project
page	integer	Page number
limit	integer	Items per page

Example Request

curl -X GET "https://{tenant}.nforged.com/api/v1/reports?project_id=proj_xyz789" \
  -H "Authorization: Bearer YOUR_TOKEN"

Get Report

GET /reports/{id}

Example Response

{
  "success": true,
  "data": {
    "id": "report_abc123",
    "project_id": "proj_xyz789",
    "name": "Q1 2024 Pentest Report",
    "status": "completed",
    "generated_at": "2024-01-30T15:00:00Z"
  }
}

Generate Report

POST /reports/generate

Request Body

Field	Type	Required	Description
project_id	string	Yes	Project to report on
template_id	string	No	Report template ID
name	string	No	Custom report name
include_findings	array	No	Specific finding IDs
severity_filter	string	No	Minimum severity
options	object	No	Report options

Options Object

{
  "include_executive_summary": true,
  "include_methodology": true,
  "include_appendices": true,
  "group_by": "severity",
  "include_evidence": true
}

Example Request

curl -X POST "https://{tenant}.nforged.com/api/v1/reports/generate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_xyz789",
    "template_id": "template_default",
    "name": "Final Report - Q1 2024",
    "severity_filter": "Medium",
    "options": {
      "include_executive_summary": true,
      "group_by": "severity"
    }
  }'

Example Response

{
  "success": true,
  "data": {
    "id": "report_def456",
    "status": "generating",
    "estimated_time": 30
  }
}

Check Generation Status

Reports generate asynchronously. Check status:

GET /reports/{id}

Status values:

• queued - In queue
• generating - Being created
• completed - Ready to download
• failed - Generation failed

Download Report

GET /reports/{id}/download

Example Request

curl -X GET "https://{tenant}.nforged.com/api/v1/reports/report_abc123/download" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output report.docx

Returns the file directly with appropriate headers:

Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="report.docx"

Delete Report

DELETE /reports/{id}

Example Request

curl -X DELETE "https://{tenant}.nforged.com/api/v1/reports/report_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

Report Templates

List Templates

GET /reports/templates

{
  "success": true,
  "data": [
    {
      "id": "template_default",
      "name": "Default Template",
      "description": "Standard pentest report"
    },
    {
      "id": "template_executive",
      "name": "Executive Summary",
      "description": "Brief executive report"
    }
  ]
}

Webhooks

Subscribe to report events:

• report.generation.started
• report.generation.completed
• report.generation.failed

Webhook payload:

{
  "event": "report.generation.completed",
  "data": {
    "report_id": "report_abc123",
    "project_id": "proj_xyz789",
    "download_url": "/reports/report_abc123/download"
  }
}

Best Practices

Async Generation

1. POST to /reports/generate
2. Poll status or use webhooks
3. Download when completed

Error Handling

If generation fails:

{
  "success": true,
  "data": {
    "id": "report_abc123",
    "status": "failed",
    "error": "No findings to include"
  }
}

---

Next: Explore Resources