> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiptx.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

> API endpoints for generating and managing security reports

# Reports API

The Reports API allows you to generate and retrieve penetration test reports in various formats.

## Generate Report

Generate a new report for a completed scan.

```bash theme={null}
POST /v1/reports
```

### Request Body

<ParamField body="scan_id" type="string" required>
  The ID of the completed scan
</ParamField>

<ParamField body="format" type="string" default="pdf">
  Report format: `pdf`, `html`, `json`, `docx`
</ParamField>

<ParamField body="template" type="string" default="technical">
  Report template: `executive`, `technical`, `compliance`, `developer`
</ParamField>

<ParamField body="compliance" type="array">
  Compliance frameworks to include: `soc2`, `iso27001`, `pci`, `hipaa`, `gdpr`
</ParamField>

<ParamField body="options" type="object">
  Additional report options
</ParamField>

### Request

```json theme={null}
{
  "scan_id": "scan_abc123",
  "format": "pdf",
  "template": "technical",
  "compliance": ["soc2", "pci"],
  "options": {
    "include_remediation": true,
    "include_poc": true,
    "executive_summary": true,
    "company_name": "Acme Corp",
    "logo_url": "https://example.com/logo.png"
  }
}
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "report_xyz789",
    "scan_id": "scan_abc123",
    "format": "pdf",
    "template": "technical",
    "status": "generating",
    "created_at": "2024-01-15T14:00:00Z",
    "estimated_completion": "2024-01-15T14:05:00Z"
  }
}
```

## List Reports

Retrieve a list of generated reports.

```bash theme={null}
GET /v1/reports
```

### Query Parameters

| Parameter  | Type    | Description        |
| ---------- | ------- | ------------------ |
| `scan_id`  | string  | Filter by scan ID  |
| `format`   | string  | Filter by format   |
| `template` | string  | Filter by template |
| `page`     | integer | Page number        |
| `limit`    | integer | Results per page   |

### Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "report_xyz789",
      "scan_id": "scan_abc123",
      "format": "pdf",
      "template": "technical",
      "status": "completed",
      "file_size": 2456789,
      "created_at": "2024-01-15T14:00:00Z",
      "expires_at": "2024-02-15T14:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 15
  }
}
```

## Get Report

Retrieve details about a specific report.

```bash theme={null}
GET /v1/reports/{report_id}
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "id": "report_xyz789",
    "scan_id": "scan_abc123",
    "format": "pdf",
    "template": "technical",
    "status": "completed",
    "compliance": ["soc2", "pci"],
    "file_size": 2456789,
    "download_url": "https://api.aiptx.io/v1/reports/report_xyz789/download",
    "summary": {
      "target": "https://app.example.com",
      "scan_date": "2024-01-15",
      "findings_total": 42,
      "findings_critical": 2,
      "findings_high": 5,
      "risk_score": 78
    },
    "created_at": "2024-01-15T14:00:00Z",
    "expires_at": "2024-02-15T14:00:00Z"
  }
}
```

## Download Report

Download the report file.

```bash theme={null}
GET /v1/reports/{report_id}/download
```

### Response

Returns the binary file with appropriate Content-Type header:

* PDF: `application/pdf`
* HTML: `text/html`
* JSON: `application/json`
* DOCX: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`

### Example

```bash theme={null}
curl -X GET "https://api.aiptx.io/v1/reports/report_xyz789/download" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o security_report.pdf
```

## Report Templates

### Executive Template

Designed for non-technical stakeholders:

* High-level risk summary
* Business impact assessment
* Key findings overview
* Trend analysis
* Strategic recommendations

### Technical Template

Comprehensive technical documentation:

* Detailed vulnerability descriptions
* Proof-of-concept code
* Request/response evidence
* CVSS scoring breakdown
* Step-by-step remediation

### Compliance Template

Focused on regulatory requirements:

* Control mapping
* Gap analysis
* Evidence collection
* Audit trail
* Compliance status dashboard

### Developer Template

Optimized for development teams:

* Code-level details
* File and line references
* Fix code examples
* Integration with issue trackers
* CI/CD pipeline recommendations

## Custom Branding

Enterprise customers can customize report branding:

```bash theme={null}
POST /v1/reports/branding
```

### Request

```json theme={null}
{
  "company_name": "Acme Corporation",
  "logo_url": "https://example.com/logo.png",
  "primary_color": "#1a73e8",
  "footer_text": "Confidential - For Internal Use Only",
  "contact_email": "security@acme.com"
}
```

## Scheduled Reports

Configure automated report generation:

```bash theme={null}
POST /v1/reports/schedules
```

### Request

```json theme={null}
{
  "scan_id": "scan_abc123",
  "format": "pdf",
  "template": "executive",
  "schedule": {
    "frequency": "weekly",
    "day": "monday",
    "time": "09:00",
    "timezone": "America/New_York"
  },
  "delivery": {
    "email": ["security@acme.com", "ciso@acme.com"],
    "slack_channel": "#security-reports"
  }
}
```

## Share Report

Generate a shareable link for a report.

```bash theme={null}
POST /v1/reports/{report_id}/share
```

### Request

```json theme={null}
{
  "expires_in": "7d",
  "password_protected": true,
  "allowed_domains": ["@acme.com"]
}
```

### Response

```json theme={null}
{
  "success": true,
  "data": {
    "share_url": "https://reports.aiptx.io/s/abc123xyz",
    "password": "SecurePass123",
    "expires_at": "2024-01-22T14:00:00Z"
  }
}
```