The Report Object

A Report represents a generated analysis document. Reports are created asynchronously and include PDF and DOCX outputs when completed.

Object Structure

Full Report (from GET /api/reports/:id)

{
  "id": "rpt_xyz789",
  "case_id": "case_abc123",
  "type": "technical_report",
  "status": "completed",
  "progress": {
    "current_step": "report_generation",
    "steps_completed": ["delta_v_calculation", "biomechanics_analysis", "report_generation"],
    "message": "Report generation complete"
  },
  "output": {
    "pdf_url": "https://storage.silentwitness.ai/reports/rpt_xyz789.pdf",
    "docx_url": "https://storage.silentwitness.ai/reports/rpt_xyz789.docx"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:45:00Z"
}

Report Summary (nested in Case)

{
  "id": "rpt_xyz789",
  "status": "completed",
  "type": "technical_report",
  "pdf_url": "https://storage.silentwitness.ai/reports/rpt_xyz789.pdf",
  "docx_url": "https://storage.silentwitness.ai/reports/rpt_xyz789.docx",
  "created_at": "2024-01-15T10:30:00Z"
}

Attributes

Core Fields

Attribute	Type	Description
id	string	Unique identifier with rpt_ prefix
case_id	string	ID of the associated case
type	string	Report type (see below)
status	string	Current processing status (see below)
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last update timestamp

Progress Object

Attribute	Type	Description
current_step	string	Step currently being processed
steps_completed	array	Array of completed step names
message	string	Human-readable status message

Output Object

Available when status is completed:

Attribute	Type	Description
pdf_url	string	Signed URL to download PDF (expires in 1 hour)
docx_url	string	Signed URL to download DOCX (expires in 1 hour)

Report Types

Value	Description
technical_report	Full technical analysis report with crash parameters and biomechanics

Status Values

Status	Description
pending	Report creation accepted, processing not started
processing	Report is actively being generated
completed	Report is ready for download
failed	Report generation failed
cancelled	Report was cancelled

Processing Steps

A technical report typically goes through these steps:

Step	Description
delta_v_calculation	Computing delta-v from vehicle damage photos
biomechanics_analysis	Running biomechanics calculations for occupants
report_generation	Generating final PDF and DOCX documents

Polling for Completion

Reports are generated asynchronously. Poll GET /api/reports/:id until status is terminal:

// Recommended polling strategy
const poll = async (reportId) => {
  const maxAttempts = 180; // 15 minutes

  for (let i = 0; i < maxAttempts; i++) {
    const { data } = await fetch(`/api/reports/${reportId}`).then(r => r.json());

    if (data.status === 'completed') return data;
    if (data.status === 'failed') throw new Error(data.progress?.message);

    await new Promise(r => setTimeout(r, 5000)); // 5 second intervals
  }

  throw new Error('Timeout');
};

Related Endpoints

• Create Report - Start report generation
• Get Report - Check status and get outputs
• List Reports - List reports for a case
• Delete Report - Delete a report