Reports API

Infracast generates compliance reports, evidence packages, and security documents in multiple formats. Reports can be generated on-demand or scheduled for automatic delivery. The Document Generation engine (Build 25) supports professional formats including signed PDFs, Word documents, and government-standard deliverables.

Endpoints

Method	Path	Description	Permission
POST	`/api/v1/tenants/{tenantID}/reports/generate`	Generate a report	`findings:read`
GET	`/api/v1/tenants/{tenantID}/reports`	List generated reports	`findings:read`
POST	`/api/v1/tenants/{tenantID}/reports/pdf`	Download PDF directly	`findings:read`
POST	`/api/v1/tenants/{tenantID}/documents/generate`	Generate formal documents	`findings:read`
GET	`/api/v1/tenants/{tenantID}/documents`	List generated documents	`findings:read`
GET	`/api/v1/tenants/{tenantID}/documents/{documentID}`	Get document metadata	`findings:read`
GET	`/api/v1/tenants/{tenantID}/documents/{documentID}/download`	Download document	`findings:read`
GET	`/api/v1/documents/types`	List available document types	`findings:read`
POST	`/api/v1/reports/verify`	Verify a signed report	None (public)

Generate a Report

POST /api/v1/tenants/{tenantID}/reports/generate

Request Body

{
  "type": "framework",
  "framework": "nist-800-53",
  "format": "pdf",
  "options": {
    "include_remediation": true,
    "include_evidence": false,
    "severity_filter": ["CRITICAL", "HIGH", "MEDIUM"],
    "title": "NIST 800-53 Compliance Report — Q1 2024"
  }
}

Report Types

Type	Description	Audience
`framework`	Full control-by-control status for a compliance framework	Auditors, compliance team
`executive`	High-level posture, trends, top risks, score over time	Leadership, board
`gap`	Controls failing or unattested, with prioritized remediation	Security engineering
`remediation`	Prioritized finding list grouped by owner/team	Engineering teams
`poam`	Plan of Action and Milestones (FedRAMP/federal format)	Federal compliance
`evidence`	Timestamped evidence bundle for a framework and time window	3PAOs, auditors

Export Formats

Format	Description	Use Case
`pdf`	Formatted PDF (signed, tamper-evident)	Sharing, archiving, auditors
`docx`	Microsoft Word document	Editing, SSP authoring
`xlsx`	Excel spreadsheet	Data analysis, POA&M tracking
`json`	Machine-readable JSON	API/automation integration
`md`	Markdown	Developer-friendly, Git storage

Example Request

# Generate a PDF compliance report for PCI DSS
curl -X POST https://api.infracast.io/api/v1/tenants/acme-corp/reports/generate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "framework",
    "framework": "pci-dss",
    "format": "pdf",
    "options": {
      "include_remediation": true,
      "title": "PCI DSS v4.0 Compliance Report — March 2024",
      "company_name": "Acme Corp",
      "logo_url": "https://acme.com/logo.png"
    }
  }'

Response

{
  "report_id": "rpt-abc123def456",
  "type": "framework",
  "framework": "pci-dss",
  "format": "pdf",
  "status": "generating",
  "created_at": "2024-03-16T10:00:00Z"
}

Reports are generated asynchronously. Poll the list endpoint or use webhooks to be notified when ready.

Download a PDF Report

For immediate, synchronous PDF generation (blocks until complete):

POST /api/v1/tenants/{tenantID}/reports/pdf
Content-Type: application/json

{
  "type": "executive",
  "format": "pdf"
}

Response is the raw PDF binary (Content-Type: application/pdf).

List Reports

GET /api/v1/tenants/{tenantID}/reports?per_page=20&sort=-created_at

{
  "items": [
    {
      "id": "rpt-abc123",
      "type": "framework",
      "framework": "pci-dss",
      "format": "pdf",
      "status": "completed",
      "size_bytes": 2847392,
      "download_url": "https://api.infracast.io/api/v1/tenants/acme-corp/reports/rpt-abc123/download",
      "download_expires": "2024-03-23T10:00:00Z",
      "created_at": "2024-03-16T10:00:00Z",
      "completed_at": "2024-03-16T10:00:45Z"
    }
  ],
  "total": 24
}

Document Generation (Build 46)

The Document Generation API produces professional-grade, government-standard documents such as System Security Plans (SSPs), POA&Ms, and architecture diagrams:

List Document Types

GET /api/v1/documents/types

{
  "types": [
    {
      "id": "ssp",
      "name": "System Security Plan",
      "description": "NIST/FedRAMP/FISMA System Security Plan with control implementation statements",
      "frameworks": ["nist-800-53", "fedramp-moderate", "fedramp-high"],
      "formats": ["docx", "pdf"]
    },
    {
      "id": "poam",
      "name": "Plan of Action & Milestones",
      "description": "FedRAMP-formatted POA&M export from open findings",
      "frameworks": ["fedramp-moderate", "fedramp-high", "nist-800-53"],
      "formats": ["xlsx", "pdf"]
    },
    {
      "id": "sar",
      "name": "Security Assessment Report",
      "description": "Full assessment report with findings, risk levels, and recommendations",
      "frameworks": ["nist-800-53", "fedramp-high"],
      "formats": ["docx", "pdf"]
    },
    {
      "id": "architecture-diagram",
      "name": "Architecture Diagram",
      "description": "Auto-generated network architecture diagram from infrastructure graph",
      "formats": ["pdf", "png", "svg"]
    }
  ]
}

Generate an SSP

POST /api/v1/tenants/{tenantID}/documents/generate
{
  "type": "ssp",
  "framework": "fedramp-high",
  "format": "docx",
  "options": {
    "include_architecture_diagram": true,
    "impact_level": "high",
    "csp_name": "Acme Cloud Services LLC",
    "system_name": "Acme Government Cloud Platform",
    "system_id": "AGC-2024-001",
    "cover_page": true,
    "organization_logo": "https://acme.com/logo.png"
  }
}

Generate a POA&M

POST /api/v1/tenants/{tenantID}/documents/generate
{
  "type": "poam",
  "framework": "fedramp-high",
  "format": "xlsx",
  "options": {
    "include_closed": false,
    "include_risk_accepted": true,
    "month": "2024-03"
  }
}

Download a Document

GET /api/v1/tenants/{tenantID}/documents/{documentID}/download

Returns the document binary with appropriate Content-Type header.

Signed PDF Reports (Build 46)

Infracast generates cryptographically signed PDFs to ensure report authenticity and tamper-evidence:

POST /api/v1/tenants/{tenantID}/reports/generate
{
  "type": "framework",
  "framework": "soc2",
  "format": "pdf",
  "options": {
    "signed": true,
    "signer": "compliance@acme.com"
  }
}

The signed PDF includes:

Digital signature embedded in the PDF
Certificate chain for signature verification
Timestamp authority (TSA) timestamp
Report hash for independent verification

Verify a Signed Report

Any party can verify a signed report without an Infracast account:

POST https://api.infracast.io/api/v1/reports/verify
Content-Type: multipart/form-data

file=@compliance-report-2024-03.pdf

{
  "valid": true,
  "signed_by": "compliance@acme.com",
  "signed_at": "2024-03-16T10:00:45Z",
  "tenant": "Acme Corp",
  "framework": "soc2",
  "generated_at": "2024-03-16T10:00:00Z",
  "tampered": false
}

Schedule Reports

Automate report delivery on a recurring schedule:

POST /api/v1/tenants/{tenantID}/reports/schedule
{
  "name": "Weekly Security Executive Summary",
  "type": "executive",
  "format": "pdf",
  "frequency": "weekly",
  "day": "monday",
  "time": "07:00",
  "timezone": "America/New_York",
  "recipients": [
    "ciso@company.com",
    "security-board@company.com"
  ],
  "options": {
    "signed": true,
    "include_trends": true
  }
}

List Schedules

GET /api/v1/tenants/{tenantID}/reports/schedules

Report History

GET /api/v1/tenants/{tenantID}/reports/history?per_page=30

Professional Format Options (Build 46)

The options field in report and document generation supports professional formatting:

Option	Type	Description
`title`	string	Custom report title
`company_name`	string	Organization name on cover page
`organization_logo`	string	URL to logo image (PNG/SVG)
`cover_page`	boolean	Include formatted cover page
`table_of_contents`	boolean	Auto-generated TOC
`include_architecture_diagram`	boolean	Include auto-generated network diagram
`include_remediation`	boolean	Include remediation steps per finding
`include_evidence`	boolean	Include evidence artifact summary
`severity_filter`	array	Only include findings of these severities
`signed`	boolean	Cryptographically sign the PDF
`watermark`	string	Add draft/confidential watermark text
`classification`	string	Document classification marking (e.g., `CUI`, `FOUO`)

Python Example

from infracast import InfracastClient
import time

client = InfracastClient(api_url="https://api.infracast.io", api_token="your-token")

# Generate a NIST report
report = client.reports.generate(
    tenant="acme-corp",
    type="framework",
    framework="nist-800-53",
    format="pdf",
    options={
        "title": "Q1 2024 NIST Compliance Report",
        "signed": True,
        "include_remediation": True
    }
)

# Wait for completion
while report.status == "generating":
    time.sleep(5)
    report = client.reports.get(tenant="acme-corp", report_id=report.id)

# Download
with open("nist-report-q1-2024.pdf", "wb") as f:
    f.write(client.reports.download(tenant="acme-corp", report_id=report.id))

print(f"Report downloaded: {report.size_bytes / 1024:.0f} KB")

FAR/DFARS Compliance Reports

Infracast includes dedicated document generators for federal contracting compliance reports. These are formal, signed documents suitable for submission to Contracting Officers, DCSA, and DoD systems.

FAR 52.204-21 — Basic Safeguarding of Covered Contractor Information Systems

FAR 52.204-21 applies to all federal contractors (not just DoD) that handle Federal Contract Information (FCI). The clause mandates 15 basic safeguarding requirements derived from NIST 800-171.

POST /api/v1/tenants/{tenantID}/documents/generate
Content-Type: application/json

{
  "type": "far-dfars-compliance",
  "report_subtype": "far-52204-21",
  "format": "pdf",
  "options": {
    "company_name": "Acme Contracting LLC",
    "cage_code": "1A2B3",
    "uei": "ABCD1234EFGH",
    "contract_numbers": ["W912DR-24-C-0001"],
    "assessment_date": "2026-04-24",
    "signed": true,
    "certifying_official": "Jane Smith, CISO"
  }
}

Report contents:

Executive summary with overall compliance posture
Control-by-control status for all 15 FAR 52.204-21 requirements
Automated findings detail with evidence references
Risk acceptance and exception documentation
Signed attestation page for certifying official

DFARS 252.204-7012 — Safeguarding CDI + SPRS Score

DFARS 252.204-7012 applies to DoD contractors handling Covered Defense Information (CDI). It requires full NIST 800-171 compliance and mandates self-reporting your SPRS score.

POST /api/v1/tenants/{tenantID}/documents/generate
Content-Type: application/json

{
  "type": "far-dfars-compliance",
  "report_subtype": "dfars-252204-7012",
  "format": "pdf",
  "options": {
    "company_name": "Acme Defense LLC",
    "cage_code": "1A2B3",
    "uei": "ABCD1234EFGH",
    "contract_numbers": ["W912DR-24-D-0042"],
    "assessment_date": "2026-04-24",
    "include_sprs_score": true,
    "include_poam": true,
    "signed": true,
    "certifying_official": "Jane Smith, CISO"
  }
}

Report contents:

SPRS Score Summary — Calculated score with practice-level breakdown
NIST 800-171 Assessment Results — All 110 practices: automated + attested
POA&M — Open deficiencies with milestones and responsible parties
CDI Data Flow Summary — Systems in scope for CDI handling
Incident Reporting Procedures — Attestation of 72-hour DC3 reporting capability
Cloud Provider Compliance — Verification that CSPs meet FedRAMP Moderate or equivalent
Signed Attestation Page — Suitable for contracting officer submission

SPRS Score in API Responses

The SPRS score is also available directly from the compliance summary endpoint:

GET /api/v1/tenants/{tenantID}/compliance/summary?framework=nist-800-171

# Response
{
  "framework": "nist-800-171",
  "sprs_score": 94,
  "sprs_max": 110,
  "sprs_min_possible": -203,
  "practices_passing": 104,
  "practices_failing": 6,
  "practices_attested": 12,
  "practices_not_assessed": 0,
  "failing_practices": [
    {
      "practice_id": "3.11.2",
      "family": "RA",
      "description": "Scan for vulnerabilities in systems periodically",
      "point_value": -5,
      "remediation": "Enable Amazon Inspector or equivalent vulnerability scanner"
    }
  ],
  "assessment_date": "2026-04-24T00:00:00Z"
}

Listing Available FAR/DFARS Report Types

GET /api/v1/documents/types?category=far-dfars

# Response
{
  "types": [
    {
      "id": "far-52204-21",
      "name": "FAR 52.204-21 Compliance Report",
      "description": "Basic safeguarding attestation for all federal contractors handling FCI",
      "applicable_to": "All federal contractors with FCI",
      "formats": ["pdf", "docx"]
    },
    {
      "id": "dfars-252204-7012",
      "name": "DFARS 252.204-7012 Compliance Report",
      "description": "CDI safeguarding report with NIST 800-171 assessment and SPRS score for DoD contractors",
      "applicable_to": "DoD contractors handling CDI",
      "formats": ["pdf", "docx"]
    }
  ]
}

When to Use Which Report

FAR 52.204-21 only: Contracts with civilian federal agencies (GSA, HHS, DHS) where you handle FCI but not CDI
DFARS 252.204-7012: All DoD contracts where CDI is handled — includes NIST 800-171 + SPRS score requirement
Both: Some DoD contracts incorporate both FAR and DFARS clauses; generate both reports

Next Steps

Findings API — The findings that populate reports
Webhooks API — Get notified when reports are ready
FedRAMP Guide — Monthly ConMon deliverable packages
NIST 800-171 Guide — SPRS score and DFARS compliance
Assessment & Questionnaire System — Attested controls that feed SPRS scoring

Endpoints​

Generate a Report​

Request Body​

Report Types​

Export Formats​

Example Request​

Response​

Download a PDF Report​

List Reports​

Document Generation (Build 46)​

List Document Types​

Generate an SSP​

Generate a POA&M​

Download a Document​

Signed PDF Reports (Build 46)​

Verify a Signed Report​

Schedule Reports​

List Schedules​

Report History​

Professional Format Options (Build 46)​

Python Example​

FAR/DFARS Compliance Reports​

FAR 52.204-21 — Basic Safeguarding of Covered Contractor Information Systems​

DFARS 252.204-7012 — Safeguarding CDI + SPRS Score​

SPRS Score in API Responses​

Listing Available FAR/DFARS Report Types​

Next Steps​