Reports

The Reports API provides a unified, Stripe-style interface for creating and managing all types of reports in Silent Witness. This API follows RESTful conventions with consistent resource naming and response formats.

Endpoints

Method	Endpoint	Description
POST	/api/reports	Create a new report
GET	/api/reports/:id	Get a report by ID
GET	/api/reports?case_id=...	List reports for a case
DELETE	/api/reports/:id	Cancel a report

Report Types

Type	Description
technical_report	Full accident reconstruction analysis with biomechanics

Additional report types (demand_letter, cross_examination) will be added in future releases.

Report Object

{
  "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"
}

Status Values

Status	Description
pending	Report creation has been accepted but processing hasn't started
processing	Report is being generated
completed	Report is ready for download
failed	Report generation failed
cancelled	Report was cancelled

Typical Workflow

1. Create a case with vehicles, occupants, and accident information
2. Upload vehicle images for crash analysis
3. Create a report via POST /api/reports
4. Poll for status via GET /api/reports/:id until status is completed
5. Download the report using URLs in the output field

Example Flow

# 1. Create report
curl -X POST https://api.silentwitness.ai/api/reports \
  -H "X-API-Key: sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "case_id": "case_abc123",
    "type": "technical_report",
    "options": {
      "include_biomechanics": true
    }
  }'

# Response
{
  "success": true,
  "data": {
    "id": "rpt_xyz789",
    "case_id": "case_abc123",
    "type": "technical_report",
    "status": "pending",
    "progress": {
      "message": "Starting analysis..."
    },
    "output": null,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

# 2. Poll for completion
curl https://api.silentwitness.ai/api/reports/rpt_xyz789 \
  -H "X-API-Key: sk-your-api-key"

# Response when complete
{
  "success": true,
  "data": {
    "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"
  }
}

Output URLs

When a report's status is completed, the output object contains signed URLs for downloading the report:

Field	Description
pdf_url	Signed URL to download PDF version
docx_url	Signed URL to download DOCX version

Note: URLs are signed and expire after 1 hour. Request a fresh GET /api/reports/:id to get new URLs.