CarSound Doctor REST API

CarSound Doctor provides developer APIs for automotive acoustic anomaly detection. Transmit a 5–10 second engine sound clip or engine bay photo, and receive structured failure classifications, severity ratings, actionable maintenance checklists, and inspection timelines in under 4 seconds.

API Base URLs

Production API:https://carsound-doctor.sensifai.com/api

2. Authentication

Every request to the third-party API must authenticate using a secret API key via the X-API-Key request header or as a Bearer token in the Authorization header.

Header Format

X-API-Key: csd_live_7a8f90b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7

Need an API key? You can generate and revoke secret tokens anytime from your dashboard.

3. Rate Limits & Metered Billing

API consumption is metered through the Sensifai Marketplace Gatekeeper at €0.05 per diagnostic scan (Pay-As-You-Go). The API operates on a rate budget of up to 800 requests/minute.

Unit Price

€0.05 / req

Rate Limit

800 req / min

Payload Limit

10 MB max

POST/api/carsound-doctor/analyze

Upload and evaluate an engine sound clip (WAV, MP3, WEBM) or engine photo (JPG, PNG) using multi-part form data.

Request Parameters (multipart/form-data)

Field	Type	Required	Description
file	Binary File	Yes	Audio (.wav, .mp3, .webm) or Photo (.jpg, .png). Maximum 10MB (REQ-001).
lang	String	Optional	Response language code (e.g., "en"). Defaults to "en".

curl -X POST "https://carsound-doctor.sensifai.com/api/carsound-doctor/analyze" \
  -H "X-API-Key: csd_live_your_api_key_here" \
  -F "file=@engine_sound.wav" \
  -F "lang=en"

POST/api/carsound-doctor/analyze-url

Submit an accessible media URL (direct audio link or image link) for analysis without uploading raw multipart bytes.

cURL JSON Body Example

curl -X POST "https://carsound-doctor.sensifai.com/api/carsound-doctor/analyze-url" \
  -H "X-API-Key: csd_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"audio_url": "https://example.com/sound.wav", "lang": "en"}'

POST/api/carsound-doctor/feedback

Submit mechanic-verified corrections or audio notes for continual model optimization.

curl -X POST "https://carsound-doctor.sensifai.com/api/carsound-doctor/feedback" \
  -H "X-API-Key: csd_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"id": "cs_9a4b82c10f3e", "corrected_label": "Serpentine Belt Slippage", "comment": "Confirmed by technician"}'

GET/api/health

Service liveness probe returning JSON 200 OK. No authentication required.

{
  "status": "ok",
  "app": "carsound-doctor",
  "version": "1.0.0",
  "service": "healthy",
  "timestamp": "2026-10-08T09:00:00.000Z"
}

8. JSON Response Schema & Models

All successful diagnostic calls return a structured JSON report adhering strictly to REQ-002:

{
  "id": "cs_9a4b82c10f3e",
  "app": "CarSound Doctor",
  "confidence": 91,
  "result": {
    "label": "Serpentine Belt Slippage & Tensioner Wear",
    "severity": "medium",
    "description": "High-frequency acoustic squeal detected under engine throttle transition. Indicates glazed serpentine belt or worn tensioner pulley bearing."
  },
  "actions": [
    "Inspect serpentine belt for glazing, edge fraying, or rib cracking.",
    "Check automatic belt tensioner arm oscillation and bearing smoothness.",
    "Replace accessory drive belt and tensioner assembly within 500 miles."
  ],
  "warnings": [
    "Belt failure causes immediate loss of alternator charging and engine water pump cooling.",
    "Non-diagnostic disclaimer: CarSound Doctor provides acoustic predictive maintenance guidance and is not a replacement for certified mechanical physical inspection."
  ],
  "next_check": "Inspect within 500 miles or immediately if squeal persists continuously.",
  "meta": {
    "latency_ms": 251
  }
}

Field	Type	Description
id	string	Unique diagnostic request tracking identifier (e.g., "cs_9a4b82c10f3e").
confidence	number	Confidence rating percentage (0–100). If <60%, a retry prompt is recommended (REQ-008).
result.label	string	Identified automotive mechanical condition or anomaly name.
result.severity	"low" \| "medium" \| "high"	Criticality rating of the mechanical failure.
result.description	string	Comprehensive acoustic telemetry explanation in plain English.
actions	string[]	Exactly 3 actionable triage and repair inspection steps.
warnings	string[]	Safety warnings and mandatory REQ-007 predictive maintenance disclaimer.
next_check	string	Recommended re-inspection timeframe (e.g., "Within 500 miles").
meta.latency_ms	number	Inference pipeline turnaround duration in milliseconds (<4,000ms target).

9. Mechanical Faults Reference Catalog

CarSound Doctor recognizes key automotive sound signatures including:

Serpentine Belt Slippagemedium

High-frequency friction squeal on acceleration.

Connecting Rod Knockhigh

Heavy rhythmic metallic percussion synchronized with crankshaft.

Hydraulic Lifter Tickmedium

Rapid valve train tapping at half engine speed.

Exhaust Manifold Leaklow

Puffing or ticking sound that subsides as manifold warms up.

Alternator Bearing Wearmedium

Linear whining or whirring noise increasing with engine RPM.

Normal Engine Rhythmlow

Healthy combustion baseline with no harmonic anomalies.