Reports API¶

The Reports API allows you to programmatically generate, manage, and retrieve security reports.

Base URL¶

https://smailander.com/api/v1/reports

Authentication¶

All API endpoints require authentication. See Authentication for details.

Endpoints¶

List Reports¶

Retrieve a list of available reports.

GET /api/v1/reports

Query Parameters:

Parameter	Type	Required	Description
limit	integer	No	Number of results (default: 50)
offset	integer	No	Pagination offset
type	string	No	Filter by report type
status	string	No	Filter by status

Response:

{
  "total": 12,
  "reports": [
    {
      "id": "report_001",
      "name": "Daily Digest",
      "type": "daily_digest",
      "status": "active",
      "created_at": "2026-01-01T00:00:00Z",
      "last_run": "2026-03-12T09:00:00Z",
      "next_run": "2026-03-13T09:00:00Z"
    }
  ]
}

Get Report Details¶

Retrieve details of a specific report.

GET /api/v1/reports/{report_id}

Response:

{
  "id": "report_001",
  "name": "Daily Digest",
  "description": "Daily summary of email honeypot activity",
  "type": "daily_digest",
  "status": "active",
  "schedule": {
    "frequency": "daily",
    "time": "09:00",
    "timezone": "UTC"
  },
  "format": "pdf",
  "recipients": [
    "security@company.com"
  ],
  "created_at": "2026-01-01T00:00:00Z",
  "updated_at": "2026-02-01T00:00:00Z"
}

Generate Report¶

Generate a report on-demand.

POST /api/v1/reports/generate

Request Body:

{
  "type": "daily_digest",
  "period": {
    "start": "2026-03-01T00:00:00Z",
    "end": "2026-03-12T23:59:59Z"
  },
  "format": "pdf",
  "filters": {
    "honeypots": ["monitor@company.com"],
    "threat_score": {"min": 60}
  },
  "delivery": {
    "method": "download_link"
  }
}

Response:

{
  "report_id": "report_new_001",
  "status": "generating",
  "estimated_completion": "2026-03-12T14:35:00Z"
}

Create Report¶

Create a new scheduled report.

POST /api/v1/reports

Request Body:

{
  "name": "Weekly Security Summary",
  "type": "custom",
  "description": "Weekly analysis of security threats",
  "schedule": {
    "frequency": "weekly",
    "day": "monday",
    "time": "09:00",
    "timezone": "UTC"
  },
  "format": "pdf",
  "sections": [
    "executive_summary",
    "threat_analysis",
    "top_threats",
    "recommendations"
  ],
  "recipients": [
    {
      "email": "security@company.com",
      "name": "Security Team"
    }
  ]
}

Response:

{
  "id": "report_002",
  "name": "Weekly Security Summary",
  "status": "active",
  "next_run": "2026-03-18T09:00:00Z"
}

Update Report¶

Update an existing report.

PUT /api/v1/reports/{report_id}

Request Body:

{
  "name": "Updated Report Name",
  "recipients": [
    "security@company.com",
    "cto@company.com"
  ],
  "format": "pdf"
}

Response:

{
  "id": "report_001",
  "name": "Updated Report Name",
  "updated_at": "2026-03-12T14:30:00Z"
}

Delete Report¶

Delete a report.

DELETE /api/v1/reports/{report_id}

Response:

{
  "id": "report_001",
  "deleted": true
}

Get Report Instances¶

Retrieve instances of a generated report.

GET /api/v1/reports/{report_id}/instances

Query Parameters:

Parameter	Type	Required	Description
limit	integer	No	Number of results
status	string	No	Filter by status

Response:

{
  "report_id": "report_001",
  "instances": [
    {
      "instance_id": "instance_001",
      "generated_at": "2026-03-12T09:00:00Z",
      "status": "completed",
      "format": "pdf",
      "size": 2457600,
      "download_url": "https://smailander.com/download/instance_001.pdf"
    }
  ]
}

Download Report¶

Download a generated report.

GET /api/v1/reports/instances/{instance_id}/download

Response:

Returns the report file.

Pause Report Schedule¶

Pause a scheduled report.

PUT /api/v1/reports/{report_id}/pause

Response:

{
  "id": "report_001",
  "status": "paused"
}

Resume Report Schedule¶

Resume a paused report.

PUT /api/v1/reports/{report_id}/resume

Response:

{
  "id": "report_001",
  "status": "active",
  "next_run": "2026-03-13T09:00:00Z"
}

Get Report Templates¶

List available report templates.

GET /api/v1/reports/templates

Response:

{
  "templates": [
    {
      "id": "daily_digest",
      "name": "Daily Digest",
      "description": "Daily summary of activity",
      "type": "standard",
      "sections": ["summary", "threats", "top_senders"]
    },
    {
      "id": "monthly_analysis",
      "name": "Monthly Analysis",
      "description": "Comprehensive monthly report",
      "type": "standard",
      "sections": ["executive_summary", "detailed_analysis"]
    }
  ]
}

Create Custom Template¶

Create a custom report template.

POST /api/v1/reports/templates

Request Body:

{
  "name": "Vendor Security Assessment",
  "description": "Custom template for vendor security",
  "sections": [
    {
      "id": "executive_summary",
      "order": 1,
      "required": true
    },
    {
      "id": "vendor_overview",
      "order": 2,
      "required": true
    }
  ],
  "formatting": {
    "format": "pdf",
    "theme": "corporate"
  }
}

Response:

{
  "id": "template_001",
  "name": "Vendor Security Assessment",
  "created_at": "2026-03-12T14:30:00Z"
}

Report Types¶

Type	Description
`daily_digest`	Daily summary of activity
`weekly_summary`	Weekly analysis
`monthly_analysis`	Monthly comprehensive report
`executive_summary`	High-level overview
`compliance_report`	Regulatory compliance
`incident_report`	Incident documentation
`custom`	Custom report

Report Sections¶

Available sections for custom reports:

executive_summary - High-level overview
email_analysis - Detailed email data
threat_breakdown - Threat type analysis
top_threats - Top threats list
geographic_analysis - Geographic distribution
honeypot_performance - Honeypot metrics
sender_analysis - Sender information
malware_analysis - Malware breakdown
trend_analysis - Trend patterns
recommendations - Action items

Report Formats¶

Supported formats:

pdf - PDF document
csv - CSV spreadsheet
json - JSON data
xlsx - Excel workbook

Rate Limits¶

Standard: 50 requests per minute
Premium: 500 requests per minute

Errors¶

See Error Codes for details.

Next Steps¶

API Overview - General API information
Authentication - How to authenticate
Analytics API - Analytics data access