Get Case

Retrieves a single case by its ID, including vehicles with crash parameters, occupants, accident information, and report status. This endpoint follows Stripe-style API conventions with consistent snake_case naming and nested objects.

Endpoint

GET /api/cases/:id

Authentication

Requires API Key authentication.

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Case ID

Response

Returns the complete case object with all related data nested appropriately.

{
  "success": true,
  "data": {
    "case": {
      "id": "case_abc123def456",
      "name": "Smith v. Johnson",
      "plaintiff_name": "John Smith",
      "defendant_name": "Bob Johnson",
      "attorney_name": "Jane Doe, Esq.",
      "side": "plaintiff",
      "has_edr": false,
      "has_tcr": true,
      "tcr_file_id": "file_tcr001",
      "tcr": {
        "id": "file_tcr001",
        "name": "TCR_1.pdf",
        "size": 248312,
        "type": "application/pdf",
        "category": "tcr_document",
        "url": "https://storage.silentwitness.ai/...",
        "uploaded_at": "2024-01-15T11:00:00Z"
      },
      "account_id": "acc_xyz789",
      "organization_id": "org_abc123",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:45:00Z",

      "accident": {
        "description": "Rear-end collision at red light",
        "date": "2024-01-10",
        "time": "14:30",
        "location": "123 Main St, Los Angeles, CA"
      },

      "vehicles": [
        {
          "id": "veh_abc123",
          "role": "plaintiff",
          "make": "Toyota",
          "model": "Camry",
          "year": "2020",
          "vin": "4T1B11HK5LU123456",
          "type": "sedan",
          "airbag_deployed": "yes",
          "deployed_airbags": ["driver_frontal", "driver_knee"],
          "edr_file_id": null,
          "image_file_ids": ["file_img1", "file_img2"],
          "crash_parameters": {
            "delta_v_min": 8.5,
            "delta_v_max": 12.3,
            "delta_v_method": "ml",
            "pdof_degrees": 180,
            "crash_pulse_min_ms": 12,
            "crash_pulse_max_ms": 100,
            "calculated_at": "2024-01-15T12:00:00Z"
          }
        },
        {
          "id": "veh_def456",
          "role": "defendant",
          "make": "Ford",
          "model": "F-150",
          "year": "2019",
          "type": "truck",
          "airbag_deployed": "no",
          "deployed_airbags": [],
          "crash_parameters": null
        }
      ],

      "occupants": [
        {
          "id": "occ_abc123",
          "name": "John Smith",
          "age": 45,
          "gender": "male",
          "height_inches": 70,
          "weight_lbs": 180,
          "position": "driver",
          "alleged_injuries": ["cervical_spine", "lumbar_spine"],
          "seatbelt_worn": true,
          "airbag_deployed": "yes",
          "pre_existing_conditions": "None"
        }
      ],

      "report": {
        "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-15T14:00:00Z"
      }
    },

    "invoice": {
      "id": "inv_xyz789",
      "amount": 299.00,
      "status": "pending"
    }
  }
}

Response Fields

Case Object

Field	Type	Description
id	string	Unique case identifier
name	string	Case name
plaintiff_name	string	Plaintiff name (injured party)
defendant_name	string	Defendant name (at-fault party)
attorney_name	string	Attorney name handling the case
side	string	Which party the attorney represents: plaintiff or defense
has_edr	boolean	Whether any vehicle on the case has an EDR file linked. Computed live from the vehicles — not a cached value.
has_tcr	boolean	Whether the case has a Traffic Collision Report uploaded (file_category=tcr_document).
tcr_file_id	string | null	ID of the most-recently-uploaded TCR file on this case, or null if none. Virtual field derived from the files table.
tcr	object | null	Expanded TCR file object (id, name, size, type, category, url, uploaded_at). null if no TCR is uploaded.
account_id	string	Account ID
organization_id	string	Organization ID (if set)
status	string	Case status
created_at	string	Creation timestamp (ISO 8601)
updated_at	string	Last update timestamp (ISO 8601)
accident	object	Accident information (see below)
vehicles	array	Vehicles with crash parameters
occupants	array	Occupants for biomechanics analysis
report	object	Report status and download URLs (null if not generated)

Accident Object

Field	Type	Description
description	string	Detailed accident description
date	string	Date of accident (YYYY-MM-DD)
time	string	Time of accident (HH:MM)
location	string	Accident location

Vehicle Object

Field	Type	Description
id	string	Vehicle ID
role	string	plaintiff or defendant
make	string	Manufacturer (e.g., Toyota, Ford)
model	string	Model name
year	string	Model year
vin	string	Vehicle Identification Number
type	string	Vehicle type (sedan, suv, truck, etc.)
airbag_deployed	string	Vehicle-level summary status: yes, no, partial, or unknown
deployed_airbags	array	Specific deployed airbag detail codes. Empty array means no details were captured or the summary status is no/unknown.
edr_file_id	string	EDR file ID (null if not uploaded)
image_file_ids	array	Damage photo file IDs
crash_parameters	object	Computed crash analysis data (null if not calculated)

Crash Parameters Object

Contains computed crash analysis data for the vehicle. This is null until delta-v calculation completes.

Field	Type	Description
delta_v_min	number	Delta-V at peak acceleration (mph)
delta_v_max	number	Final maximum delta-V (mph)
delta_v_method	string	Calculation method: ml, edr, vector, or hybrid
pdof_degrees	number	Principal Direction of Force (degrees)
crash_pulse_min_ms	number	Time at peak acceleration (milliseconds)
crash_pulse_max_ms	number	Time at final maximum (milliseconds)
calculated_at	string	Timestamp when calculated (ISO 8601)

Occupant Object

Field	Type	Description
id	string	Occupant ID
name	string	Occupant name
age	integer	Age in years
gender	string	male, female, or other
height_inches	integer	Height in inches
weight_lbs	integer	Weight in pounds
position	string	Seating position (driver, front_passenger, etc.)
alleged_injuries	array	List of injury types
seatbelt_worn	boolean	Whether seatbelt was worn
airbag_deployed	string	Airbag status: yes, no, partial, unknown
pre_existing_conditions	string	Pre-existing medical conditions

Report Object

Field	Type	Description
id	string	Report ID
status	string	pending, in_progress, completed, failed
type	string	Report type (e.g., technical_report)
pdf_url	string	PDF download URL (when completed)
docx_url	string	DOCX download URL (when completed)
created_at	string	Report creation timestamp (ISO 8601)

Example

curl -X GET "https://api.silentwitness.ai/api/cases/case_abc123def456" \
  -H "X-API-Key: $API_KEY"

Checking Crash Parameters

After uploading vehicle photos and triggering analysis, the crash_parameters object will be populated:

# Check if delta-v has been calculated
curl -X GET "https://api.silentwitness.ai/api/cases/case_abc123" \
  -H "X-API-Key: $API_KEY" \
  | jq '.data.case.vehicles[0].crash_parameters'

Example response when calculated:

{
  "delta_v_min": 8.5,
  "delta_v_max": 12.3,
  "delta_v_method": "ml",
  "pdof_degrees": 180,
  "crash_pulse_min_ms": 12,
  "crash_pulse_max_ms": 100,
  "calculated_at": "2024-01-15T12:00:00Z"
}

Errors

Code	Description
401	Unauthorized - Invalid or missing API key
403	Forbidden - Access denied to this case
404	Case not found
500	Internal server error

Error Examples

Case not found:

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

Access denied (case belongs to another account):

{
  "success": false,
  "error": "Access denied",
  "error_code": "forbidden",
  "error_type": "permission_error",
  "request_id": "req_..."
}