Create Report

Creates a new report for a case.

Endpoint

POST /api/reports

Request Body

Field	Type	Required	Description
case_id	string	Yes	The ID of the case to generate the report for
type	string	Yes	The type of report to generate. Currently supported: technical_report
options	object	No	Optional configuration for report generation
options.use_demo_data	boolean	No	Use synthetic demo data instead of ML inference (default: false). See below.

Demo Data Option

When use_demo_data is set to true, the system uses pre-generated synthetic crash parameters instead of running the ML inference model. This is useful for:

• SDK testing: Validate your integration without waiting for ML processing
• Development environments: Test report generation without a configured ML model
• Quick demonstrations: Generate reports immediately with realistic sample data

Demo data provides representative delta-v values and crash parameters that produce a valid technical report, but does not reflect actual analysis of uploaded vehicle photos.

Biomechanics Analysis

Biomechanics analysis is controlled by the case's analysis_type, not by a report option. When creating the case:

• accident_injury or biomechanics_only → biomechanics runs automatically when occupants exist
• accident_only or delta_v_only → biomechanics is skipped

See Create Case for setting analysis_type and defining occupants.

Prerequisites

Before creating a report, ensure the case has the required crash data:

• At least one vehicle must be added to the case
• Vehicle damage photos or an EDR report (PDF) must be uploaded and linked to the plaintiff vehicle
• If the case analysis_type is accident_injury or biomechanics_only, occupants must be defined with required fields (name, age, gender, height, weight, position, seatbelt_worn)
• Accident date must be available on the case. It can be provided directly when creating or updating the case (accident_date field in YYYY-MM-DD format), or extracted automatically from an attached Traffic Collision Report (TCR). If neither is available, report creation is rejected.

If these prerequisites are not met, the API returns a 422 Unprocessable Entity error with a diagnostic message explaining what is missing.

Request Example

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

Response

Success (200 OK)

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

Error (400 Bad Request)

{
  "success": false,
  "error": "case_id is required"
}

{
  "success": false,
  "error": "Invalid report type: invalid_type. Supported types: technical_report"
}

Error (404 Not Found)

Returned when the case_id does not exist or is not accessible to your account:

{
  "success": false,
  "error": "Case not found",
  "error_code": "case_not_found",
  "error_type": "invalid_request_error",
  "error_param": "case_id",
  "request_id": "req_..."
}

Error (422 Unprocessable Entity)

Returned when the case is missing required crash data for report generation:

{
  "success": false,
  "error": "Unable to generate report: no crash analysis data available. Found 1 vehicle(s) but none have damage photos or EDR data attached. Please upload vehicle damage photos or an EDR report (PDF) to the plaintiff vehicle. No EDR files were detected. If you uploaded an EDR report, it may not have been recognized — ensure it is a valid PDF."
}

Notes

• The report generation is asynchronous. The response returns immediately with status: "pending".
• Poll GET /api/reports/:id to check the status and get the final output URLs.
• For technical_report type, the workflow automatically:
  • Triggers delta-v calculation if vehicle images are available
  • Runs biomechanics analysis if the case analysis_type includes biomechanics and occupants are defined
  • Generates the final PDF and DOCX reports