Reports API

Generate security reports programmatically. Executive summaries, technical analysis, compliance reports, and more via REST API.

Base URL

All API requests use the base URL: https://api.bloodhoundsecurity.ca/v1

Overview

The Reports API allows you to generate various security reports from scan data. Reports are generated asynchronously and can be downloaded in multiple formats.

6 Report Types

Comprehensive coverage

Multiple Formats

PDF, HTML, JSON, CSV

Scheduling

Automated delivery

Generate Report

Create a new report from scan data.

POST/reports

Bash

1# Generate executive summary report
2curl -X POST https://api.bloodhoundsecurity.ca/v1/reports \
3  -H "Authorization: Bearer bh_your_api_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "type": "executive",
7    "format": "pdf",
8    "scan_ids": ["scan_abc123xyz"],
9    "options": {
10      "period": "30d",
11      "compare_previous": true,
12      "include_charts": true
13    }
14  }'
15
16# Response
17{
18  "id": "report_xyz789abc",
19  "type": "executive",
20  "format": "pdf",
21  "status": "generating",
22  "created_at": "2024-01-15T14:30:00Z",
23  "estimated_completion": "2024-01-15T14:31:00Z",
24  "links": {
25    "self": "/v1/reports/report_xyz789abc",
26    "download": null  // Available when complete
27  }
28}
29
30# Generate technical report from multiple scans
31curl -X POST https://api.bloodhoundsecurity.ca/v1/reports \
32  -H "Authorization: Bearer bh_your_api_key" \
33  -H "Content-Type: application/json" \
34  -d '{
35    "type": "technical",
36    "format": "html",
37    "scan_ids": ["scan_abc123", "scan_def456", "scan_ghi789"],
38    "options": {
39      "include_code_context": true,
40      "include_data_flow": true,
41      "severity_filter": ["critical", "high"]
42    }
43  }'
44
45# Generate compliance report
46curl -X POST https://api.bloodhoundsecurity.ca/v1/reports \
47  -H "Authorization: Bearer bh_your_api_key" \
48  -H "Content-Type: application/json" \
49  -d '{
50    "type": "compliance",
51    "format": "pdf",
52    "scan_ids": ["scan_abc123xyz"],
53    "options": {
54      "framework": "soc2",
55      "include_evidence": true,
56      "auditor_name": "Big4 Auditing Firm"
57    }
58  }'

Report Types

executive

pdfhtml

High-level summary for leadership

technical

pdfhtmljson

Detailed technical analysis

catalog

jsoncsvhtml

Full vulnerability inventory

roadmap

pdfhtmljson

Prioritized remediation plan

compliance

pdfhtml

Compliance framework mapping

financial

pdfhtml

Risk quantification in dollars

Get Report

Check report status and download when ready.

GET/reports/:report_id

Bash

1# Check report status
2curl https://api.bloodhoundsecurity.ca/v1/reports/report_xyz789abc \
3  -H "Authorization: Bearer bh_your_api_key"
4
5# Response (generating)
6{
7  "id": "report_xyz789abc",
8  "type": "executive",
9  "format": "pdf",
10  "status": "generating",
11  "progress": 65,
12  "created_at": "2024-01-15T14:30:00Z"
13}
14
15# Response (ready)
16{
17  "id": "report_xyz789abc",
18  "type": "executive",
19  "format": "pdf",
20  "status": "ready",
21  "created_at": "2024-01-15T14:30:00Z",
22  "completed_at": "2024-01-15T14:31:15Z",
23  "file_size_bytes": 1245678,
24  "links": {
25    "self": "/v1/reports/report_xyz789abc",
26    "download": "/v1/reports/report_xyz789abc/download"
27  },
28  "expires_at": "2024-01-22T14:31:15Z"
29}
30
31# Download report
32curl https://api.bloodhoundsecurity.ca/v1/reports/report_xyz789abc/download \
33  -H "Authorization: Bearer bh_your_api_key" \
34  -o executive-report.pdf
35
36# Get signed URL (for sharing)
37curl -X POST https://api.bloodhoundsecurity.ca/v1/reports/report_xyz789abc/share \
38  -H "Authorization: Bearer bh_your_api_key" \
39  -H "Content-Type: application/json" \
40  -d '{
41    "expires_in": "7d",
42    "password": "optional_password"
43  }'
44
45# Response
46{
47  "url": "https://reports.bloodhoundsecurity.ca/shared/abc123xyz",
48  "expires_at": "2024-01-22T14:30:00Z",
49  "password_protected": true
50}

Scheduled Reports

Schedule recurring reports with automatic delivery via email or webhook.

POST/reports/schedules

Bash

1# Create weekly executive report schedule
2curl -X POST https://api.bloodhoundsecurity.ca/v1/reports/schedules \
3  -H "Authorization: Bearer bh_your_api_key" \
4  -H "Content-Type: application/json" \
5  -d '{
6    "name": "Weekly Executive Summary",
7    "type": "executive",
8    "format": "pdf",
9    "schedule": {
10      "frequency": "weekly",
11      "day": "monday",
12      "time": "08:00",
13      "timezone": "America/New_York"
14    },
15    "scope": {
16      "repositories": ["owner/repo1", "owner/repo2"],
17      "period": "7d"
18    },
19    "delivery": {
20      "email": {
21        "recipients": ["ciso@company.com", "security@company.com"],
22        "subject": "Weekly Security Report - {{date}}"
23      },
24      "webhook": {
25        "url": "https://your-app.com/webhooks/reports"
26      }
27    }
28  }'
29
30# Response
31{
32  "id": "schedule_abc123",
33  "name": "Weekly Executive Summary",
34  "status": "active",
35  "next_run": "2024-01-22T08:00:00-05:00",
36  "created_at": "2024-01-15T14:30:00Z"
37}
38
39# List scheduled reports
40curl https://api.bloodhoundsecurity.ca/v1/reports/schedules \
41  -H "Authorization: Bearer bh_your_api_key"
42
43# Update schedule
44curl -X PATCH https://api.bloodhoundsecurity.ca/v1/reports/schedules/schedule_abc123 \
45  -H "Authorization: Bearer bh_your_api_key" \
46  -H "Content-Type: application/json" \
47  -d '{
48    "schedule": {
49      "frequency": "daily"
50    }
51  }'
52
53# Pause/Resume schedule
54curl -X POST https://api.bloodhoundsecurity.ca/v1/reports/schedules/schedule_abc123/pause \
55  -H "Authorization: Bearer bh_your_api_key"
56
57curl -X POST https://api.bloodhoundsecurity.ca/v1/reports/schedules/schedule_abc123/resume \
58  -H "Authorization: Bearer bh_your_api_key"
59
60# Delete schedule
61curl -X DELETE https://api.bloodhoundsecurity.ca/v1/reports/schedules/schedule_abc123 \
62  -H "Authorization: Bearer bh_your_api_key"

Enterprise Feature

Scheduled reports with email delivery require Pro or Enterprise plans.

Custom Templates

Use custom templates for branded reports.

Bash

1# Upload custom template
2curl -X POST https://api.bloodhoundsecurity.ca/v1/reports/templates \
3  -H "Authorization: Bearer bh_your_api_key" \
4  -F "name=Corporate Template" \
5  -F "type=executive" \
6  -F "template=@./custom-template.hbs" \
7  -F "logo=@./company-logo.png" \
8  -F "stylesheet=@./custom-styles.css"
9
10# Response
11{
12  "id": "template_xyz123",
13  "name": "Corporate Template",
14  "type": "executive",
15  "created_at": "2024-01-15T14:30:00Z"
16}
17
18# Use custom template when generating report
19curl -X POST https://api.bloodhoundsecurity.ca/v1/reports \
20  -H "Authorization: Bearer bh_your_api_key" \
21  -H "Content-Type: application/json" \
22  -d '{
23    "type": "executive",
24    "format": "pdf",
25    "template_id": "template_xyz123",
26    "scan_ids": ["scan_abc123xyz"]
27  }'
28
29# Template variables available:
30# {{organization_name}} - Your organization name
31# {{report_date}} - Report generation date
32# {{period_start}} - Analysis period start
33# {{period_end}} - Analysis period end
34# {{total_findings}} - Total vulnerability count
35# {{critical_count}} - Critical severity count
36# {{high_count}} - High severity count
37# {{risk_score}} - Overall risk score
38# {{findings}} - Array of finding objects
39# {{charts}} - Generated chart images