Skip to main content

Quick Start

This guide walks you through the core REST API workflow: create a case, upload evidence, and generate a technical report.

Prerequisites​

  • An API key from the Silent Witness dashboard
  • Vehicle damage photos (JPEG or PNG)

The Flow​

1. POST /api/cases           → Create case with vehicles and accident info
2. POST /api/files/upload     → Upload damage photos (repeat per file)
3. POST /api/reports          → Create report (starts async processing)
4. GET  /api/reports/:id      → Poll until status is "completed"
5. Download PDF/DOCX          → Use signed URLs from response

1. Create a Case​

Create a case with vehicles, accident details, and optionally occupants:

curl -X POST "https://api.silentwitness.ai/api/cases" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plaintiff_name": "John Smith",
    "defendant_name": "Bob Johnson",
    "attorney_name": "Jane Attorney, Esq.",
    "analysis_type": "accident_injury",
    "accident": {
      "description": "Rear-end collision at red light",
      "date": "2024-01-10",
      "time": "14:30",
      "location": "123 Main St, Los Angeles, CA"
    },
    "vehicles": [
      {"role": "plaintiff", "vehicle_maker": "Toyota", "vehicle_model": "Camry", "vehicle_year": "2020"},
      {"role": "defendant", "vehicle_maker": "Ford", "vehicle_model": "F-150", "vehicle_year": "2019"}
    ],
    "occupants": [
      {
        "name": "John Smith",
        "age": 42,
        "gender": "male",
        "height_inches": 70,
        "weight_lbs": 180,
        "position": "driver",
        "seatbelt_worn": true,
        "alleged_injuries": ["cervical_spine", "lumbar_spine"]
      }
    ]
  }'

Save the case_id from the response (data.case.id).

Analysis types

Use accident_only for crash-only analysis (no occupants needed), or accident_injury for crash + biomechanics. See Analysis Types for all options.

2. Upload Damage Photos​

Upload each photo with file_category and vehicle_role. Files are automatically linked to the correct vehicle.

# Plaintiff photos
curl -X POST "https://api.silentwitness.ai/api/files/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@front_damage.jpg" \
  -F "case_id=$CASE_ID" \
  -F "file_category=vehicle_photo" \
  -F "vehicle_role=plaintiff"

# Defendant photos
curl -X POST "https://api.silentwitness.ai/api/files/upload" \
  -H "X-API-Key: $API_KEY" \
  -F "file=@defendant_damage.jpg" \
  -F "case_id=$CASE_ID" \
  -F "file_category=vehicle_photo" \
  -F "vehicle_role=defendant"

Upload 4-8 photos per vehicle for best results. Supported types: JPEG, PNG, GIF, WebP (max 50MB each).

3. Create a Report​

curl -X POST "https://api.silentwitness.ai/api/reports" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"case_id": "'$CASE_ID'", "type": "technical_report"}'

Save the report_id from the response (data.id). Report generation is asynchronous — you need to poll for completion.

4. Poll for Completion​

Poll every 5 seconds until status is completed:

curl "https://api.silentwitness.ai/api/reports/$REPORT_ID" \
  -H "X-API-Key: $API_KEY"

Possible statuses: pending → processing → completed (or failed).

5. Download the Report​

Once completed, the response includes signed download URLs:

{
  "output": {
    "pdf_url": "https://storage.silentwitness.ai/reports/...",
    "docx_url": "https://storage.silentwitness.ai/reports/..."
  }
}
curl -o report.pdf "$PDF_URL"
curl -o report.docx "$DOCX_URL"

Download URLs expire after 1 hour. Call GET /api/reports/:id again for fresh URLs.

Next Steps​