Automatic Diagnosis API Developer Guide

Service Overview

Automatic Diagnosis Service is a telematics-based diagnosis service where the vehicle automatically generates diagnosis data and transmits it to the server when an abnormal condition is detected, without driver intervention.

Service Features

Automatic detection and diagnosis of vehicle abnormal conditions
Automatic diagnosis process without driver intervention
Real-time fault code analysis and alerts
Prevention-focused vehicle management support
Various trigger-based automatic diagnosis

Legal Requirements

Compliance with personal information protection laws
Mandatory vehicle diagnosis data collection consent
Compliance with fault information retention period policies
Compliance with vehicle control-related regulations

Key Scenarios

Scenario 1: Automatic Diagnosis Monitoring

API Flow by Entity:

📱 App (User):

Latest Report: Check latest diagnosis results
Health Trend: Analyze health score over time
Delete DTC: Reset fault codes after maintenance

🚗 Vehicle (TCU):

Auto Detection: Automatically detect abnormal conditions
Data Transmission: Transmit diagnosis data to ECARUS server

🏢 Call Center:

History Query: Query vehicle diagnosis records
DTC Details: Get detailed fault code info
Event Monitoring: Real-time detection of diagnosis events

Key Features

App Features

Latest Report: Check detailed report of automatic diagnosis results
Real-time Status: Check current vehicle diagnosis status
Health Trend: Analyze vehicle health score trend
DTC Query: Check currently active diagnostic trouble codes
DTC Deletion: Delete and reset DTC codes after maintenance
History Query: Check past automatic diagnosis records
Real-time Monitoring: Automatic diagnosis real-time event stream

Call Center Features

DTC Management: Query DTC code list and Get detailed fault code info
Diagnosis History: Query vehicle diagnosis records
Event Monitoring: Real-time monitoring of diagnosis events
Diagnosis Data Analysis: Comprehensive analysis of received diagnosis data and pattern detection
Risk Status Determination: Determine vehicle drivability based on severity
Service Linkage: Repair shop recommendation and emergency situation Roadside Assistance linkage

Sequence Diagram

Automatic Diagnosis System Flow

Automatic Diagnosis

API Endpoints

Refer to the Common API Specifications for headers, response codes, and error formats.

Automatic Diagnosis

Current DTC Query

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/dtc" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

DTC Deletion

bash

curl -X DELETE "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/dtc" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     -H "Content-Type: application/json" \
     -d '{"codes": ["P0520", "P0301"], "reason": "After sensor replacement"}'

Latest Automatic Diagnosis Report Query

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/report/latest" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Automatic Diagnosis History Query

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/history?period=30d" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Real-time Diagnosis Status Query

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/status" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Health Score Trend Query

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/health/trend?period=90d" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

DTC Management

DTC Code Detailed Information Query

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/dtc/P0520" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

DTC Code List Query

bash

curl -X GET "https://api.ecarus.run/api/v1/diagnosis/dtc/list?limit=10" \
     -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d"

Automatic Diagnosis Real-time Event Reception (SSE)

Note: Recommend accessing via browser or using dedicated SSE client

bash

curl -N -H "Authorization: Bearer sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d" \
     "https://api.ecarus.run/api/v1/diagnosis/vehicles/KMHSH81C7LU123456/auto/events"

Data Models

DTC (Diagnostic Trouble Code) Response

Response model for currently active diagnostic trouble codes list

json

{
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "dtc": [
    {
      "code": "P0520",
      "ecu": "ECM",
      "status": "ACTIVE",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "severity": "MEDIUM",
      "firstOccurrence": "2026-01-13T14:25:00Z",
      "occurrenceCount": 3,
      "lastOccurrence": "2026-01-13T14:30:00Z"
    },
    {
      "code": "P0301",
      "ecu": "ECM", 
      "status": "ACTIVE",
      "description": "Cylinder 1 Misfire Detected",
      "severity": "HIGH",
      "firstOccurrence": "2026-01-13T14:20:00Z",
      "occurrenceCount": 1,
      "lastOccurrence": "2026-01-13T14:30:00Z"
    }
  ],
  "totalCount": 2
}

Automatic Diagnosis Report

Latest automatic diagnosis results detailed report

json

{
  "reportId": "report-12345",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "summary": {
    "overallStatus": "WARNING",
    "healthScore": 75,
    "dtcCount": 2,
    "criticalCount": 0,
    "highCount": 1,
    "mediumCount": 1,
    "lowCount": 0
  },
  "dtc": [
    {
      "code": "P0520",
      "ecu": "ECM",
      "status": "ACTIVE",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "severity": "MEDIUM",
      "occurrenceCount": 3,
      "freezeFrame": {
        "rpm": 2500,
        "speed": 65,
        "temperature": 85,
        "load": 45
      }
    }
  ],
  "ecuStatus": {
    "ECM": {
      "status": "NORMAL",
      "softwareVersion": "v2.1.5",
      "lastUpdate": "2026-01-10T10:00:00Z"
    },
    "BCM": {
      "status": "NORMAL",
      "softwareVersion": "v1.8.2"
    },
    "TCU": {
      "status": "NORMAL",
      "softwareVersion": "v3.0.1"
    }
  },
  "vehicleStatus": {
    "ignition": "ON",
    "mileage": 45230,
    "batteryVoltage": 14.2,
    "fuelLevel": 65.5,
    "engineTemperature": 85.0
  },
  "recommendations": [
    {
      "priority": "HIGH",
      "action": "SERVICE_CENTER_VISIT",
      "description": "Engine oil pressure sensor inspection needed",
      "estimatedCost": "150-300"
    }
  ]
}

Automatic Diagnosis History

Past automatic diagnosis records list

json

{
  "vin": "KMHSH81C7LU123456",
  "period": "30d",
  "history": [
    {
      "reportId": "report-12345",
      "timestamp": "2026-01-13T14:30:00Z",
      "overallStatus": "WARNING",
      "healthScore": 75,
      "dtcCount": 2,
      "criticalIssues": 0
    },
    {
      "reportId": "report-12344", 
      "timestamp": "2026-01-10T09:15:00Z",
      "overallStatus": "NORMAL",
      "healthScore": 92,
      "dtcCount": 0,
      "criticalIssues": 0
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Real-time Diagnosis Status

Current vehicle diagnosis status information

json

{
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "status": "ACTIVE",
  "healthScore": 75,
  "activeDtcCount": 2,
  "lastDiagnosis": "2026-01-13T14:30:00Z",
  "nextScheduledCheck": "2026-01-13T15:00:00Z",
  "systemStatus": {
    "obd": "ONLINE",
    "ecu": "ONLINE",
    "sensors": "NORMAL"
  }
}

Health Score Trend

Vehicle health score time series data

json

{
  "vin": "KMHSH81C7LU123456",
  "period": "90d",
  "trend": [
    {
      "date": "2026-01-13",
      "healthScore": 75,
      "dtcCount": 2,
      "criticalCount": 0
    },
    {
      "date": "2026-01-12",
      "healthScore": 78,
      "dtcCount": 1,
      "criticalCount": 0
    }
  ],
  "summary": {
    "averageScore": 82.5,
    "minScore": 75,
    "maxScore": 95,
    "trendDirection": "STABLE"
  }
}

DTC Code Detailed Information

Detailed description of specific DTC code

json

{
  "code": "P0520",
  "description": "Engine Oil Pressure Sensor/Switch Circuit",
  "category": "ENGINE",
  "severity": "MEDIUM",
  "symptoms": [
    "Engine warning light on",
    "Oil pressure warning",
    "Engine performance degradation"
  ],
  "causes": [
    "Oil pressure sensor failure",
    "Wiring issues",
    "Oil pump failure"
  ],
  "recommendations": [
    "Service center visit recommended",
    "Check oil level"
  ],
  "estimatedCost": "150-400"
}

DTC Code List

DTC code search results list

json

{
  "codes": [
    {
      "code": "P0520",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "category": "ENGINE",
      "severity": "MEDIUM"
    },
    {
      "code": "P0301", 
      "description": "Cylinder 1 Misfire Detected",
      "category": "IGNITION",
      "severity": "HIGH"
    }
  ],
  "pagination": {
    "total": 245,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Real-time Diagnosis Event (SSE)

Automatic diagnosis real-time event stream

json

{
  "eventType": "DIAGNOSIS_EVENT",
  "eventId": "event-67890",
  "vin": "KMHSH81C7LU123456",
  "timestamp": "2026-01-13T14:30:00Z",
  "data": {
    "type": "NEW_DTC_DETECTED",
    "dtc": {
      "code": "P0520",
      "description": "Engine Oil Pressure Sensor/Switch Circuit",
      "severity": "MEDIUM"
    },
    "healthScore": 75
  }
}

Security and Privacy

Authentication and Authorization

User authentication token required (JWT/OAuth2)
Vehicle access permission verification
Diagnosis data reception permission verification

Data Security

All API communication encrypted with HTTPS/TLS
Security measures when transmitting diagnosis data
Sensitive vehicle information stored only on server

Privacy Protection

Explicit consent for diagnosis data collection
Specify data collection purpose
Compliance with data retention period policies
Guarantee right to data deletion upon user request

Access Control

VIN-based vehicle access permission verification
Manage user-specific diagnosis data access permissions
Detect abnormal access patterns

Exception Handling

Connection Failure: Support offline mode, store data and retransmit
Slow Response: Loading indicator, timeout handling
Server Down: Display error message, suggest retry

Vehicle OFF: Display last stored diagnosis results
No ECU Response: Notify some ECUs not responding
Diagnosis Failure: Notify diagnosis failure and guide retry

Data Corruption: Notify diagnosis data corruption
Analysis Failure: Notify diagnosis analysis failure
DTC Error: Handle DTC code errors

Alert Failure: Retry when alert transmission fails
Alert Duplication: Prevent duplicate alerts
Alert Ignored: Reflect user alert ignore settings

Test Setup

Base URL: https://api.ecarus.run/api/v1/diagnosis
Authentication Token: sk_4f9c7b8e2d1a6c0f3e7a9b5d8c1e4f2a7c6d9e0b3f5a8c1d4e7f9b2c6a1e3d
Sample VIN: KMHSH81C7LU123456

Use Swagger UI for interactive API testing.

Deployment Considerations

App Store Registration

Request vehicle diagnosis data collection permissions
Request push notification permissions
Clear description of vehicle status monitoring

Legal Regulation Compliance

Compliance with personal information protection laws
Mandatory diagnosis data collection consent
Compliance with fault information retention period policies
Compliance with vehicle control-related regulations

Vehicle Compatibility

Support various vehicle models
Consider diagnosis method differences by ECU type
Reflect OEM-specific diagnosis protocol differences
Consider diagnosable item differences

Automatic Diagnosis API Developer Guide ​

Service Overview ​

Service Features ​

Legal Requirements ​

Key Scenarios ​

Scenario 1: Automatic Diagnosis Monitoring ​

Key Features ​

App Features ​

Call Center Features ​

Sequence Diagram ​

Automatic Diagnosis System Flow ​

API Endpoints ​

Automatic Diagnosis ​

Current DTC Query ​

DTC Deletion ​

Latest Automatic Diagnosis Report Query ​

Automatic Diagnosis History Query ​

Real-time Diagnosis Status Query ​

Health Score Trend Query ​

DTC Management ​

DTC Code Detailed Information Query ​

DTC Code List Query ​

Automatic Diagnosis Real-time Event Reception (SSE) ​

Data Models ​

DTC (Diagnostic Trouble Code) Response ​

Automatic Diagnosis Report ​

Automatic Diagnosis History ​

Real-time Diagnosis Status ​

Health Score Trend ​

DTC Code Detailed Information ​

DTC Code List ​

Real-time Diagnosis Event (SSE) ​

Security and Privacy ​

Authentication and Authorization ​

Data Security ​

Privacy Protection ​

Access Control ​

Exception Handling ​

Network Related ​

Vehicle Status Related ​

Data Related ​

Alert Related ​

Test Setup ​

Deployment Considerations ​

App Store Registration ​

Legal Regulation Compliance ​

Vehicle Compatibility ​

Automatic Diagnosis API Developer Guide

Service Overview

Service Features

Legal Requirements

Key Scenarios

Scenario 1: Automatic Diagnosis Monitoring

Key Features

App Features

Call Center Features

Sequence Diagram

Automatic Diagnosis System Flow

API Endpoints

Automatic Diagnosis

Current DTC Query

DTC Deletion

Latest Automatic Diagnosis Report Query

Automatic Diagnosis History Query

Real-time Diagnosis Status Query

Health Score Trend Query

DTC Management

DTC Code Detailed Information Query

DTC Code List Query

Automatic Diagnosis Real-time Event Reception (SSE)

Data Models

DTC (Diagnostic Trouble Code) Response

Automatic Diagnosis Report

Automatic Diagnosis History

Real-time Diagnosis Status

Health Score Trend

DTC Code Detailed Information

DTC Code List

Real-time Diagnosis Event (SSE)

Security and Privacy

Authentication and Authorization

Data Security

Privacy Protection

Access Control

Exception Handling

Network Related

Vehicle Status Related

Data Related

Alert Related

Test Setup

Deployment Considerations

App Store Registration

Legal Regulation Compliance

Vehicle Compatibility