# VisionMax VisionMax is a total solution developed by MiTAC Digital Inc. \ It consists : - Master portal:\ An AWS cloud server for resellers to manage their fleets and devices under the fleets. - Fleet portal:\ An AWS cloud server for fleet managers managing the fleet’s devices and drivers, including broad features like: live view, real-time and historical route data, enroll and remove devices, binding devices with certain driver, view event video, request video OTA, watch device health status and diagnostics. --- This API document is for master and fleet portals, API documents for other components are provided in other place of service site. --- ## Access ## ***You must place the API key in the HTTP header to access endpoints.***\ All API endpoints of the VisionMax, except login/logout and forgot password requires an ```access_token```\ Any registered account can obtain an access token from ```/auth``` endpoint. --- ## Camera ID ## | Camera ID | From camera | |------------------------|----------------------------------------------------------------| | C_F | Front camera | | C_I | In-cabin camera | | C_R | Rear camera | | C_E | The extended cameras. Extended cameras generally refer to TVI cameras. | ## Camera capture mode ## VisionMax defines several camera image capture modes and applies them to the filename. \ Additionally, VisionMax treats the capture mode as a camera ID in some cases. | Capture mode/Camera ID | From camera | |------------------------|----------------------------------------------------------------| | C_F | Front camera | | C_I | In-cabin camera | | C_R | Rear camera | | C_E | The extended cameras | | GRID | The combined video from 4TVI cameras with GRID are considered `legacy` | | S_F_I | The combined video from the front and in-cabin
`2TVI cameras with S_F_I are considered legacy` | --- ## Connectivity state ## Due to implementation constraints, VisionMax determines device connectivity status based on camera-initiated messages rather than persistent connections. The server does not maintain an always-on connection to each device and cannot proactively detect status transitions. Instead, the device status is inferred from incoming messages sent by the camera. **In standby mode, the camera sends heartbeat messages every 20 minutes.** The connectivity states are evaluated as follows: | state | desc | |-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | online | The server has received a GPS update from the device within the last 30 seconds. | | offline | No heartbeat has been received for more than 20 minutes. | | standby | No GPS update has been received for more than 30 seconds, but at least one heartbeat has been received within the last 20 minutes.
**The device usually can accept a wakeup message at standby mode.** | | waking_up | The server sends a wake-up signal to the device. The device should be back online in a very short time.
**If the device can not go back online in the next 5 seconds, its state will change to offline immediately.**| --- ## Event types ## - `key` is an internal constant value and is not included in the API response. Please do not rely on this field for application logic or integrations. - `display_name` is provided for **readability only**, to help humans understand the event type. It is **not guaranteed to be stable or unique** and must not be used for value mapping or conditional logic. - For all integrations, always use **`event_type ID`** as the authoritative identifier. | **event_type ID** | **key** | **display_name** | **hook_able** | **Default upload type** | **Available upload type** | |-----------------|----------------------|--------------------------------|---------------|---------------------------------------------------------------------- |--- | 1 | collision | Impact | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 2 | parking | Parking_deprecated | | `video` | | | 3 | speeding | Speeding_deprecated | | | | | 4 | assistance | Manual Event | ✅ | `video` | | | 5 | startup | Start Up | ✅ | | | | 6 | RapidAcceleration | Harsh Acceleration | ✅ | minor: `video`
moderate: `video`
Severe: `video` | Enums: `video`, `snapshot`, `none` | | 7 | SuddenDeceleration | Harsh Braking | ✅ | minor: `video`
moderate: `video`
Severe: `video` | Enums: `video`, `snapshot`, `none` | | 8 | AbruptSteering | Harsh Cornering | ✅ | minor: `video`
moderate: `video`
Severe: `video` | Enums: `video`, `snapshot`, `none` | | 9 | idling | Idling | | | | | 10 | geofence | Geofence | ✅ | | | | 11 | geofence in | Geofence in | ✅ | | | | 12 | parking collision | Parking Impact | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 13 | Engine Off | Engine Off | ✅ | `snapshot` | | | 14 | Battery low | Battery Low | ✅ | | | | 15 | Battery cut | Power Outage | ✅ | | | | 19 | Harsh cornering | Harsh cornering_deprecated | ✅ | | | | 20 | Harsh accelerating | Harsh accelerating_deprecated | ✅ | | | | 21 | Nodding off | Sleepy (eye closed)/Fatigue | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 22 | Distraction | Distracted | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 27 | Manual:video | Manual:video | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 28 | Manual:snapshot | Manual:snapshot | | | | | 29 | Manual:burst | Manual:burst | | | | | 30 | FCWS | Frontal Collision | ✅ | `snapshot` | Enums: `video`, `snapshot`, `none` | | 31 | Tailgating | Tailgating | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 32 | LaneDrift | Lane Departure | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 33 | StopAndGo | Stop and Go | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 34 | CellPhoneUse | Phone Texting | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 35 | Yawn | Yawning | | | | | 36 | FaceID | FaceID | | `snapshot` | | | 37 | NFC clock in | NFC clock in | ✅ | `snapshot` | | | 39 | Unfastened seatbelt | Seat Belt Unfastened | ✅ | `snapshot` | Enums: `video`, `snapshot`, `none` | | 40 | Camera tampered | Camera tampered_deprecated | ✅ | `video` | | | 41 | Motion Detect | Motion detect__deprecated | | | | | 47 | Speed Camera | Speed Camera Violation | ✅ | minor: `snapshot`
moderate: `snapshot`
Severe: `video` | Enums: `video`, `snapshot`, `none` | | 48 | Rolling Stop | Rolling Stop | ✅ | `video` | Enums: `video`, `snapshot`, `none` | | 49 | Railroad Crossing | Railroad Crossing Violation | | | | | 50 | School Zone Speed | School Zone Speed Violation | | | | | 51 | Speed Sign | Speed Sign_deprecated | | | | | 52 | BSIS | BSIS | | | | | 53 | ADAS failure | ADAS failure | ✅ | | | | 54 | DMS failure | DMS Off | ✅ | `snapshot` | | | 55 | ADAS recovery | ADAS recovery | ✅ | | | | 56 | DMS recovery | DMS recovery | ✅ | | | | 60 | end idling | end idling | | | | | 61 | cover removed | I/O Cover Removed | ✅ | `video` | | | 62 | cover recovered | I/O cover recovered | | | | | 63 | PCWS | Pedestrian Collision Warning | | | | | 69 | custom-ext | custom extended | | | | | 71 | lens covered | Lens covered | ✅ | | Enums: `video`, `snapshot`, `none` | | 73 | Smoking | Smoking | ✅ | `video` | Enums: `video`, `snapshot`, `none` | Version: 2025-Q4 ## Servers Production server ``` https://api.visionmaxfleet.com ``` Staging server ``` https://staging-api.visionmaxfleet.com ``` ## Security ### api key API key Type: apiKey In: header Name: x-api-key ### Authorization Bearer token. Any registered account can obtain an Bearer token from /auth endpoint Type: http Scheme: bearer Bearer Format: JWT ## Download OpenAPI description [VisionMax](https://visionmax.redocly.app/_bundle/index.yaml) ## Auth - Activation ### Resend Activation Email - [POST /portal/V1/auth/resend-activation-mail](https://visionmax.redocly.app/auth-activation/authresendactivationmail.md): This API resends the activation email to the specified customer email address. It is often used when a user registers but did not receive the activation link. Usage Notes: - The system will check the customer’s registration record before resending. - The resend count will be recorded (resend_mail_count). - The API may enforce resend limits to prevent abuse (e.g., max 5 times per day). - If the email is not found or already activated, an error message will be returned. ### Resend Activation Email - [POST /V2/auth/resend-activation-mail](https://visionmax.redocly.app/auth-activation/authresendactivationmail.md): This API resends the activation email to the specified customer email address. It is often used when a user registers but did not receive the activation link. Usage Notes: - The system will check the customer’s registration record before resending. - The resend count will be recorded (resend_mail_count). - The API may enforce resend limits to prevent abuse (e.g., max 5 times per day). - If the email is not found or already activated, an error message will be returned. ## Fleet - Auth ### Login - [POST /V2/auth](https://visionmax.redocly.app/fleet-auth/fleetauth.md): ### Below APIs are used to generate token and get authentication with fleet portal Use API to log in VisionMax fleet portal, email address and password are required. Please be noticed, The access token of fleet and master account are separated Therefor you can't access Master endpoints with Fleet access token, and vice versa. When the user's email has access to two or more fleets, a list of available fleets will be returned. ### Log out - [GET /logout](https://visionmax.redocly.app/fleet-auth/fleetlogout.md) ### Token verify - [GET /V2/auth/token-verify](https://visionmax.redocly.app/fleet-auth/fleettokenverify.md) ### Token switch - [POST /V2/auth/token-switch](https://visionmax.redocly.app/fleet-auth/fleettokenswitch.md): This API uses the token from your login to exchange for the token of the specific fleet you want to obtain and gives you the ability to roam in fleets The token used to exchange will revoked since it was used to obtain a new one. If the fleet_id is empty or does not exist, the token will not be exchanged, and only the list of available fleets will be returned. ## Fleet - Configuration ### Configuration list - [GET /V2/configuration](https://visionmax.redocly.app/fleet-configuration/getconfiguration.md): VisionMax events have various types and configurable pre-recorded and post-recorded event video length. This API can retrieve the current configuration list --- ### Configuration Hierarchy Override System The system uses a 4-level hierarchy where lower levels override upper levels. | Level | Configuration Type | Description | Priority | |-------|-------------------|-------------|----------| | 1 | System Configuration Defaults | Base system defaults | Lowest | | 2 | Fleet Configuration Defaults | Set by master account | ↓ Overrides Level 1 | | 3 | Vehicle Type Configuration | Passenger, Medium, Heavy vehicles | ↓ Overrides Level 1-2 | | 4 | Device Custom Configuration | Device-specific settings | Highest | --- Priority Rule: Lower levels override upper levels Example: If a setting exists in all 4 levels, the Device Custom Configuration (Level 4) value will be used, ignoring all upper level values. --- ### Configure device recording behavior for ignition off and wake-up period Remote Command Processing During both ignition off period and wake-up period: - Device processes pending remote commands for system_acc_off_keep_record_second duration(Default: 10 min) - Once the timer expires, the device enters suspend mode, regardless of whether all pending remote commands have been completed Ignition OFF to Suspend Flow 1. Ignition OFF → Check system_keep_record_during_suspend_debounce - true : Keep recording for system_acc_off_keep_record_second duration(Default: 10 min) - false: Skip recording, go directly to Prepare to Suspend 2. Prepare to Suspend (Fixed 3 minutes) - Finalize ongoing operations 3. Enter Suspend mode Wake-up Period Behavior 1. Stay Awake (Duration: system_acc_off_keep_record_second, Default: 10 min) - Device wakes up from suspend mode 2. Check system_record_on_wake_up_enable - true : Recording during wake-up period - false: No recording during wake-up period 3. Return to Suspend mode after duration expires --- ### Event video duration | Category | Event | range of pre event (second) | range of post event (second) | |--------------|------------------------|---------------------------------|----------------------------------| | Sensor | Harsh Acceleration | 6~15 | 2~30 | | | Harsh Braking | 6~15 | 2~30 | | | Harsh Cornering | 6~15 | 2~30 | | | Impact Driving | 6~15 | 2~30 | | | Impact Parking | n/a | 2~30 | | AI_ADAS | FCW | 4~15 | 0-30 | | | Tailgating | 4~15 | 0-30 | | | LDW | 4~15 | 0-30 | | | Stop and Go | 4~15 | 0-30 | | AI_DMS | Distraction | 4~15 | 0-30 | | | Phoning | 4~15 | 0-30 | | | Speed Camera Violation | 4~15 | 0-30 | | | Rolling Stop | 4~15 | 0-30 | --- ### Video format and resolution | Model | Camera | Default format | Options | |-------------|------------------------------|----------------|-------------------------------------------------| | K145 series | embedded(front and incabin) | Side-By-Side | Side-Bye-Side(2560x720)/Separate(1280x720) | | | UVC | Single | Single(1280x720) | | K245 series | embedded(front and incabin) | Side-By-Side | Side-Bye-Side(2560x720)/Separate(1280x720) | | | UVC | Single | Single(1280x720) | | K220 series | embedded(front and incabin) | Side-By-Side | Side-Bye-Side(2560x720)/Separate(1280x720) | | | UVC | Single | Single(1280x720) | | K165 series | embedded(front and incabin) | Side-By-Side | Side-Bye-Side(2560x720)/Separate(1280x720) | | | UVC | Single | Single(1280x720) | | | 4TVI | Grid | Grid(2560x1440) | | | 2TVI | Side-By-Side | Single(2560x720) | | K265 series | embedded(front and incabin) | Side-By-Side | Side-Bye-Side(2560x720)/Separate(1280x720) | | | UVC | Single | Single(1280x720) | | | 4TVI | Grid | Grid(2560x1440) | | | 2TVI | Side-By-Side | Single(2560x720) | ### Update the configuration by vehicle types. - [POST /V2/configuration](https://visionmax.redocly.app/fleet-configuration/updateconfiguration.md): This API can be used to modify the configuration based on vehicle types. This configuration relies on dynamic JSON input, thus enabling partial updates and simultaneous updates for multiple VehicleType entries. ### Configuration list of a single device. - [GET /V2/configuration/{cid}](https://visionmax.redocly.app/fleet-configuration/getdeviceconfiguration.md) ### Update the configuration of a single device - [POST /V2/configuration/{cid}](https://visionmax.redocly.app/fleet-configuration/updatedeviceconfiguration.md): This API can be used to modify the configuration of a single device, ensuring that each modification will overwrite the previous settings This configuration relies on dynamic JSON input. ### Patch the configuration of a single device - [PATCH /V2/configuration/{cid}](https://visionmax.redocly.app/fleet-configuration/patchdeviceconfiguration.md): This API can be used to modify the configuration of a single device. This configuration relies on dynamic JSON input. ### Restore the configuration of a single device. - [POST /V2/configuration/{cid}/restore](https://visionmax.redocly.app/fleet-configuration/restoredeviceconfiguration.md): This endpoint will remove any custom setting of specific device, therefor it will aligment with the setting of its vehicle type ### Bulk update device configurations - [POST /V2/Configuration/V2/configuration/bulk/devices](https://visionmax.redocly.app/fleet-configuration/bulkupdatedeviceconfiguration.md): This API allows bulk updating of device configurations. Each update will overwrite the previous settings on the corresponding device. The configuration payload must be provided as a dynamic JSON object. A maximum of 100 devices can be updated per request. ### Bulk patch device configurations - [PATCH /V2/Configuration/V2/configuration/bulk/devices](https://visionmax.redocly.app/fleet-configuration/bulkpatchdeviceconfiguration.md): This API allows partial updates to the configurations of multiple devices. The configuration payload must be provided as a dynamic JSON object. A maximum of 100 devices can be patched per request. ### Bulk restore device configurations - [POST /V2/Configuration/V2/configuration/bulk/devices/restore](https://visionmax.redocly.app/fleet-configuration/bulkrestoredeviceconfiguration.md): This API removes all custom settings from the specified devices, restoring them to align with the configuration of their associated vehicle type. A maximum of 100 devices can be patched per request. ## Fleet - Dashboard ### Get general info of fleet - [GET /V2/dashboard](https://visionmax.redocly.app/fleet-dashboard/dashboard.md): This API is to get general information of the fleet, for example: time zone, count of impact events, summary of a trip ### Get highlight list - [GET /V2/dashboard/highlight-list](https://visionmax.redocly.app/fleet-dashboard/dashboard-hightlight.md): This API can get highlighted information, such as: driver ID, driver avatar, driver name, driver status (activated/inactivated), remaining days till expiration, highlighted event is expired or not, snapshot, timestamp of the event, type of the event, event video upload status ## Fleet - Fleet ### Retrieves timeline snapshots - [POST /V2/devices/GetTimeline](https://visionmax.redocly.app/fleet-fleet/devicegettimelinesnapshot.md): Retrieves timeline snapshots for a specified device based on the provided request parameters. Enable vr_videoSnapshots via Vehicle Type Configuration or Single Device Configuration to have the device upload one front-facing snapshot per minute. ### Add fleet user - [POST /V2/fleet/user/add](https://visionmax.redocly.app/fleet-fleet/useraddfleetuser.md): This API allows the fleet's admin to add a fleet user. ### Get user list - [GET /V2/fleet/user/list](https://visionmax.redocly.app/fleet-fleet/usergetfleetuserlist.md): This API can get the list of user. ### Deactivate fleet user - [POST /V2/fleet/user/{user_id}/deactivate](https://visionmax.redocly.app/fleet-fleet/userdeactivatefleetuser.md): This API allows the fleet's admin to deactivate any activated user except themselves. ### Reactivate fleet user - [POST /V2/fleet/user/{user_id}/reactivate](https://visionmax.redocly.app/fleet-fleet/userreactivatefleetuser.md): This API allows the fleet's admin to reactivate any deactivated user except themselves. ### Delete fleet user - [POST /V2/fleet/user/{user_id}/delete](https://visionmax.redocly.app/fleet-fleet/userdeletefleetuser.md): This API allows the fleet's admin to detele any deactivated user except themselves. ### Get user detail - [GET /V2/fleet/user/{user_id}](https://visionmax.redocly.app/fleet-fleet/usergetfleetuserdetail.md): This API can get the detail of user. ### Edit fleet user - [POST /V2/fleet/user/{user_id}/edit](https://visionmax.redocly.app/fleet-fleet/usereditfleetuser.md): This API allows the fleet's admin to edit any user except themselves. All user data must be uploaded, and each upload will completely overwrite the previous data. ### Get fleet user's email event notification settings - [GET /V2/fleet/user/{user_id}/event-notifications/email](https://visionmax.redocly.app/fleet-fleet/getfleetuseremaileventnotifications.md): This API can be used by a fleet administrator to get the email event notification settings, but only administrator accounts can be retrieved. ### Update fleet user's email event notification settings - [POST /V2/fleet/user/{user_id}/event-notifications/email](https://visionmax.redocly.app/fleet-fleet/updatefleetuseremaileventnotifications.md): This API can be used by a fleet administrator to update the email event notification settings, but only administrator accounts can be configured. ### Add contract fleet - [POST /V2/fleet/add](https://visionmax.redocly.app/fleet-fleet/fleetaddcontractfleet.md): This API allows admin to add a contract fleet. ### Get contract fleet list - [GET /V2/fleet/list](https://visionmax.redocly.app/fleet-fleet/fleetgetcontractfleetlist.md): This API can get the list of contract fleets. ### Get fleet detail - [GET /V2/fleet/{fleet_id}](https://visionmax.redocly.app/fleet-fleet/fleetgetfleetdetail.md): This API can get the detail of fleets. ### Edit fleet - [POST /V2/fleet/{fleet_id}/edit](https://visionmax.redocly.app/fleet-fleet/fleeteditfleet.md): This API allows admin to edit information of fleet. Only the parameters that are passed in will be updated. ### Delete contract fleet - [POST /V2/fleet/{fleet_id}/delete](https://visionmax.redocly.app/fleet-fleet/fleetdeletecontractfleet.md): This API allows admin to delete a contract fleet. ### Get fleet configuration - [GET /V2/fleet/{fleet_id}/configurations](https://visionmax.redocly.app/fleet-fleet/fleetgetfleetconfiguration.md): This API can get the configurations of the specified fleet. ### Update fleet configuration - [POST /V2/fleet/{fleet_id}/configurations](https://visionmax.redocly.app/fleet-fleet/fleetupdatefleetconfiguration.md): This API can be used to modify the configuration of fleet, All configuration data must be uploaded, and each upload will completely overwrite the previous data. This configuration relies on dynamic JSON input. ### Get device list - [GET /V2/fleet/device/list](https://visionmax.redocly.app/fleet-fleet/devicegetdevicelist.md): This API can get the list of devices for fleet and all the contract fleets under it. ### Edit device's fleet - [POST /V2/fleet/device/edit-fleet](https://visionmax.redocly.app/fleet-fleet/deviceeditdevicefleet.md): This API can edit the fleet assignment of one or more devices. ### Get available models - [GET /V2/fleet/device/available-models](https://visionmax.redocly.app/fleet-fleet/devicegetavailablemodels.md): This API can get available models of devices under the user's fleet, including the contract fleets. ## Fleet - Management ### Get vehicle list - [GET /V2/vehicle/list](https://visionmax.redocly.app/fleet-management/vehiclelist.md): This API can get all vehicle data within a fleet. ### Get vehicle detail by vehicle ID - [GET /V2/vehicle/{vehicle_id}](https://visionmax.redocly.app/fleet-management/vehicledetailbyvehicleid.md): This API can get detail about a vehicle by its ID. ### Get vehicle detail by device ID. - [GET /V2/vehicle/device/{device_id}](https://visionmax.redocly.app/fleet-management/vehicledetailbydeviceid.md): This API can get detail about a vehicle by paired device ID or serial number or cid(certificate id). ### Add a vehicle - [POST /V2/vehicle/add](https://visionmax.redocly.app/fleet-management/addvehicle.md): This API can add a new vehicle to the fleet. ### Edit a vehicle - [POST /V2/vehicle/{vehicle_id}/edit](https://visionmax.redocly.app/fleet-management/editvehicle.md): This API can edit setting of a vehicle. Please note that each time it will overwrite the previous data, and it cannot be restored. ### Deactivate a vehicle - [POST /V2/vehicle/{vehicle_id}/deactivate](https://visionmax.redocly.app/fleet-management/deactivatevehicle.md): This API can deactivate a vehicle. Vehicles that are deactivated cannot be paired with devices. Vehicles can only be deleted after it has been deactivated. ### Activate a vehicle - [POST /V2/vehicle/{vehicle_id}/activate](https://visionmax.redocly.app/fleet-management/activatevehicle.md): This API can activate a vehicle. ### Delete a vehicle - [POST /V2/vehicle/{vehicle_id}/delete](https://visionmax.redocly.app/fleet-management/deletevehicle.md): This API can delete a vehicle. Please note that this operation is irreversible. ### Get all available devices. - [GET /V2/vehicle/get-available-devices](https://visionmax.redocly.app/fleet-management/getavailabledevices.md): This API can get the ID and name of unassigned devices within the fleet. ### Set the vehicle for a device. - [POST /V2/vehicle/set-vehicle-of-device](https://visionmax.redocly.app/fleet-management/setvehicleofdevice.md): This API endpoint assigns a device to a vehicle in the fleet. ### Get data usage report - [GET /V2/ota/data-usage](https://visionmax.redocly.app/fleet-management/datausage.md): This API is used to get the data use report of a certain device, inputs: serial number of the device, start and end timestamp, frequency to update the report ### List device groups - [GET /V2/group/List](https://visionmax.redocly.app/fleet-management/grouplist.md): Because in VisionMax devices are managed in groups, therefor you can query and manage devices through groups. This API can fetch the general information of a group. ### List devices - [GET /V2/group/ListGroup](https://visionmax.redocly.app/fleet-management/allgroupdeviceslist.md): Because in VisionMax devices are managed in groups, therefor you can query and manage devices through groups. This API can fetch all devices ### List devices in group - [GET /V2/group/ListGroup/{group_id}](https://visionmax.redocly.app/fleet-management/listgroupdevices.md): With this API, you can get the devices information in a specific group, group ID is needed to use it ### Get geo fences - [GET /V2/geofence/list](https://visionmax.redocly.app/fleet-management/geofencelist.md): Used to get a geofence’s general information, like: ID, name, radius, latitude, longitude, trigger type, updated timestamp ### Get vehicle types - [GET /V2/event/vehicleTypes](https://visionmax.redocly.app/fleet-management/vehicletypes.md): This API can get vehicle types of a fleet. Including: name, ID, vehicle type code ### Get driver list of fleet - [GET /V2/driver/GetAllDrivers](https://visionmax.redocly.app/fleet-management/getalldriver.md): This API is to get total drivers list of a fleet, driver information: avatar, driver ID, email address, employee ID, driver name, driver’s phone number, RFID number ### Get general info of devices - [GET /V2/devices](https://visionmax.redocly.app/fleet-management/getdevice.md): This can be used to retrieve general information of a device: IMEI 1/IMEI 2, activated from, activated date/time, application version, front camera height, CID, device ID, device name, device installed location, firmware version, first connected timestamp, group ID, online status…etc. ### Get health report of device - [GET /V2/devices/health/{cid}](https://visionmax.redocly.app/fleet-management/devicehealthreport.md): Used to fetch the last time diagnostic report of a device. Including: assigning status, attention flag, CID, device ID, model, device name, repair flag, and report ### Get simple health report of device. - [GET /V2/devices/healthReport/{cid}](https://visionmax.redocly.app/fleet-management/devicesimplehealthreport.md): This API returns a simple health report of a device. It includes a summary of device status and possible solutions. Health Status Reference - Footage Storage (SD Card) | Status | Description | Solution | |-------------|---------------------------------------------------------------|--------------------------------------------------------------| | unknown | The device has not detected any SD card data. | | | not support | This device does not support this hardware feature. | | | healthy | The SD card is in good condition. | | | unhealthy | The SD card is in unhealthy condition. | If formatting fails, replace with a new SD card. | | not reported| Device has not reported. | | - Location Function | Status | Description | Solution | |--------------|---------------------------------------------------------------|--------------------------------------------------------------| | unknown | No health check report for this item. | | | healthy | The location function is working properly. | | | unhealthy | GPS failed since {{issue_began_at}}. This caused no location data for the trip/event. | Check satellites, move vehicle to clear sky, or contact support.| | not reported | Device has not reported. | | - Sensor Events Detection | Status | Description | Solution | |--------------|---------------------------------------------------------------|--------------------------------------------------------------| | unknown | No health check report for this item. | | | healthy | The sensor is working properly. | | | unhealthy | Sensor cannot detect events (e.g., harsh acceleration). | Contact support to resolve this issue. | | not reported | Device has not reported. | | - AI Component (Aux Camera) | Status | Description | Solution | |----------------|---------------------------------------------------------------|------------------------------| | unknown | No camera check report. | | | unhealthy | [{{type}}] cannot record video. Contact support. | | | healthy | {{type}} is healthy | | | not reported | Device has not reported. | | - Main Camera | Status | Description | Solution | |-------------|-------------------------------------------------------------|------------------------------| | unknown | No camera check report. | | | unhealthy | [{{type}}] cannot record video. Contact support. | Contact support to resolve. | | healthy | {{type}} is healthy | | | not support | This device does not support this hardware feature. | | | not reported| Device has not reported. | | | no equipped | UVC camera not detected. | Check the connection or reconnect the device.| | Note: The "no equipped" status is only applicable to UVC cameras.TVI and other device types do not support this status. | ### Get simple health report of fleet - [GET /V2/devices/healthReport/fleet](https://visionmax.redocly.app/fleet-management/fleetdevicesimplehealthreportfleet.md): Pleasea refer to simple health report of device for details ### Update device setting - [POST /V2/device/Update](https://visionmax.redocly.app/fleet-management/deviceupdate.md): If you are trying to update the vehicle type, we encourage you to manage the vehicle types with vehicle management endpoints This API can modify device settings, including: * Name of device * License plate of the device installed * VIN of the device installed * Vehicle type of the deivce installed * AI region of the device * The installed camera's height above ground level * Group of device ### Format sd card - [POST /V2/devices/FormatSdCardToDevice/{cid}](https://visionmax.redocly.app/fleet-management/formatsdcardtodevice.md): Send a remote command to formate SD card ### Delete sd file - [POST /V2/devices/DeleteSDFile/{cid}](https://visionmax.redocly.app/fleet-management/deletesdfile.md): Send a remote command to Delete files on the device's SD card. ### Cancel Task - [POST /V2/devices/CancelTask/{cid}](https://visionmax.redocly.app/fleet-management/canceltask.md): Remove the task from the devices. Requires Camera App version 1.2.21.37-REL_20240930_1847 or above. ### List Task - [POST /V2/devices/ListTasks/{cid}](https://visionmax.redocly.app/fleet-management/listtasks.md): Find device list tasks. ### Get Device Storage List - [GET /V2/devices/{device}/storage-list](https://visionmax.redocly.app/fleet-management/devicestoragelist.md): Used to get the storage list of the device. ### Trigger Dongle Log Upload - [POST /V2/devices/trigger-upload-dongle-log/{cid}](https://visionmax.redocly.app/fleet-management/triggeruploaddonglelog.md): Trigger a background dongle log upload task for the device. ### To wake up device - [GET /V2/devices/wakeup/{cid}](https://visionmax.redocly.app/fleet-management/devicewakeupdevice.md): This API allows you to wake up the device while it is in standby mode Since this is an asynchronous request, you can check the device status using Get general info of devices and look up the is_online or connectivity_state property. When the device is in a state where it can be awakened, its status will typically change to online within about one second. ## Fleet - Safety ### Safety report - [GET /V2/analytics/safety](https://visionmax.redocly.app/fleet-safety/safetyreport.md): A safety report is an overview of safety driving and events. This API can get event and trip summaries and the trend type of 4 types of events: - Sensor Event - AI(ADAS) Event - Traffic sign - AI(DMS) Event ### Event list - [GET /V2/events](https://visionmax.redocly.app/fleet-safety/eventlist.md): This API is used to get and query event list within time period. ### Event detail - [GET /V2/event/detailV2](https://visionmax.redocly.app/fleet-safety/eventdetail.md): This API is used to get the detail information of event ### Video asset details - [POST /V2/event/GetVideoDetail](https://visionmax.redocly.app/fleet-safety/eventassetdetail.md): This API is used to get the video asset details information of event ### List of manual upload - [GET /V2/event/StorageList](https://visionmax.redocly.app/fleet-safety/storagelist.md): This API is used to get event videos that upload manually. The list contains: device CID, event name, event expiration status, left days to expired, latitude and longitude of the event, device, event recording video ID, tag info, trip ID ## task state ## | value |state | description |------------|------------------ |------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 0 | Upcoming | The server sends a command to the device. | | 1 | Processing | After receiving the command, the device notifies the server. | | 2 | Success | Upload progress is tracked by the server. All files have been received successfully. | | 3 | Failed | The device reports an error message. | | 4 | Clipping file | The server receives the number of clips that can be processed and their status from the device. | | 5 | Uploading file | Once the device is ready to upload, it requests a ticket. After getting the ticket, it starts uploading the videos. The server counts the uploaded files. | | 6 | Partial Success | Task partially completed(e.g., only some clips uploaded) | | 7 | Remove | The task was removed due to prolonged processing time. | ## camera codes ## | code | description | |------------|------------------ | | D_E20001 | Video is not existing | | D_E20002 | Videos merges fail | | D_E20003 | Clip process is busy | | D_E20004 | Device is busy on uploading events (when command is made through P2P, legacy) | | D_E20005 | Failed to get ticket from server (when command is made through P2P, legac) | | D_E20006 | 2nd SDCard is unmounted (when command is made through P2P, legacy) | | D_E20007 | The task is finished but failed | | D_E20009 | Insufficient internal flash storage space | | D_E20010 | Upload time expired (The task is queued for over three days, and removed by the camera app) | ## last_ack_message (process_history) ## | field | type | description | | ----------------- | -------------------------- | -------------------------------------------------------- | | code | string or null | camera code, e.g., D_S00000 indicates success. | | desc | string or null | description. May be null. | | state | string or null | camera status, such as video processing. | | report_at | integer (Unix timestamp) or null| Timestamp of the server current task report. | | state_desc | string or null | Task progress status (e.g., (2/3) means stage 2 of 3). May be null. | | progress_status | array or [] (empty array) | A list of camera-specific task progress entries. | ## progress_status ## | field | type | description | | -------------- | --------- | ------------------------------------------------------------------------ | | camId | string or null | Camera identifier(e.g., C_E, S_F_I). | | state | string or null | Current status of this camera task (e.g., Uploading, Success). | | report_at | integer or null| Timestamp of this camera's progress update. | | state_number | integer or null| Numeric stage of the task (e.g., 6 = step 6). | ## state_number ## | value | state | description | |--------------|----------------------|------------------------------------------| | 0 | Preparing to clip | The camera is waiting to start clipping. | | 1 | Starting clipping | The camera has started clipping the video. | | 2 | Clipping successful | The camera finished clipping successfully. | | 3 | Clipping failed | The camera failed to clip the video. | | 4 | Video not found | The camera cannot find the video file. | | 5 | Preparing to upload | The camera is ready to upload the video. | | 6 | Uploading success | The camera uploaded the video successfully. | | 7 | Upload time expired | The camera took too long; upload expired. | Indicates whether to filter for timelapse videos. - true: includes timelapse videos - false: only normal videos Note: If type = 27,27 and timelapse = true, both normal and timelapse videos will be queried. ### Request video clip - [POST /V2/event/videoClip/{sn}](https://visionmax.redocly.app/fleet-safety/videoclipbytarget.md): This API can send a remote command to request the device to upload a video clip asynchronously, regardless of whether the device is online or not when the request is made. \ The response includes a task ID that allows you to check the result with V2/event/taskResult/{taskId} later. > This feature was introduced from region 43. \ > The device won't respond to the remote command before the version of region 43. ### Get task process history - [GET /V2/event/taskResult/{taskId}](https://visionmax.redocly.app/fleet-safety/gettaskprocessresult.md): This API allowing you to query the process result of a remote task like 1. request to upload a video clip ### To discard an event - [POST /V2/event/discard](https://visionmax.redocly.app/fleet-safety/discardevent.md): This API can discard an event. > Deleting the event will not update the score for that specific trip; instead, it will be reflected in the driver's overall driving score as a positive adjustment. > Please note that this action is irreversible. ### Trigger device take-snapshot - [POST /V2/devices/take-snapshot/{cid}](https://visionmax.redocly.app/fleet-safety/takesnapshot.md): Trigger device take-snapshot. Requires Camera App version 11.2.24.56 or above. ## Fleet - Trips ### Get trip statistics - [GET /V2/analytics/GetTripStatistics](https://visionmax.redocly.app/fleet-trips/tripstatistics.md): This API is used to get the trip statistics within the specified time range. 1. The number of trips within that time range 2. Total driving distance of the time range 3. The total idling time during trips within the time range 4. The total duration of trips within the time range ### Get fleet driving statistics - [GET /V2/analytics/GetFleetAvgPerDriverDay](https://visionmax.redocly.app/fleet-trips/fleetavgdrivingstatistics.md): This API can be used to get the fleet driving statistics within the specified time range. For example: - average driving distance per day - average accumulated idling time per day, average total driving time per day, and average number of trips per day ### Get fleet driving statistics - [GET /V2/analytics/GetDriverTripSummaryList](https://visionmax.redocly.app/fleet-trips/drivertripsummarylist.md): This API can be used to get the fleet driving statistics within the specified time range. For example: - average driving distance per day - average accumulated idling time per day - average total driving time per day - and average number of trips per day ### Get trip list - [GET /V2/trips](https://visionmax.redocly.app/fleet-trips/triplist.md): This API is to get the trip list with parameters, trip status, start/end time. Mileage ### Get trip detail - [GET /V2/trip](https://visionmax.redocly.app/fleet-trips/tripdetail.md): This API is to get the trip detail with trip ID, including: driver name, driver avatar, device name, driver ID, trip start and end timestamp, total events in the trip, mileage, last recorded GPS information ### Get trip recognize information - [GET /V2/trips/TripRecognizeInfo/{trip_id}](https://visionmax.redocly.app/fleet-trips/triprecognizeinfo.md): This API is used to get the driver information with trip ID. ## Master - Auth ### Login - [POST /portal/V1/auth](https://visionmax.redocly.app/master-auth/masterauth.md): To obtain the access token of the master portal, email address and password are required. > Please be noticed, The access token of fleet and master account are separated > Therefor you can't access Master endpoints with Fleet access token, and vice versa. ### Log out - [GET /portal/V1/logout](https://visionmax.redocly.app/master-auth/masterlogout.md) ### Token verify - [GET /portal/V1/auth/token-verify](https://visionmax.redocly.app/master-auth/mastertokenverify.md) ### Get fleet's access token - [POST /portal/V1/auth/fleet-delegate](https://visionmax.redocly.app/master-auth/mastercreatefleetdelegate.md): Get a short-term access token for specified fleet ## Master - Dashboard ### Get general info of Master account - [GET /portal/V1/dashboard](https://visionmax.redocly.app/master-dashboard/masterdashboard.md): This API is used to get general information of a master account. Including number of active devices, number of assigned devices, owned fleet list, plan types ## Master - Diagnostics ### Device diagnostics - [POST /portal/V1/diagnostics/list](https://visionmax.redocly.app/master-diagnostics/masterdiagnosticslist.md): This API is to get device diagnostics result to allow administrators to quickly understand the health status of devices in online services. Including when the issue was assigned to a technician, name of the customer, device ID, diagnostic ID, the reported issues, device model, device name, device serial number, and reported time. ### Get device issues by fleet - [GET /portal/V1/diagnostics/device-with-issues-by-fleet](https://visionmax.redocly.app/master-diagnostics/masterdiagnosticsissuesummarybyfleet.md): Returns the total device count, issue count, and issue rate for each fleet. Helps administrators identify which fleet has the most device issues. ### Get device issues by type - [GET /portal/V1/diagnostics/device-with-issues-by-type](https://visionmax.redocly.app/master-diagnostics/masterdiagnosticsissuesummarybytype.md): Returns the total device count and the count of each issue type. Helps administrators understand which type of issue is most common across all devices. ### Get models used by each active fleet in the organization - [GET /portal/V1/diagnostics/fleets](https://visionmax.redocly.app/master-diagnostics/masterdiagnosticsfleetmodelusage.md): Returns a list of active fleets in the organization and the distinct device models used under each fleet. This helps administrators understand which models are currently deployed and in use. ### Get all issue types - [GET /portal/V1/diagnostics/get-all-issue-type](https://visionmax.redocly.app/master-diagnostics/masterdiagnosticsgetallissuetypes.md): Returns a list of all possible issue types (ID and name). Useful for building dropdowns or filtering diagnostics by type. ### Get available fleet models - [GET /portal/V1/diagnostics/get-all-models](https://visionmax.redocly.app/master-diagnostics/masterdiagnosticsgetallmodels.md): Returns a list of available device models including ID, internal name, display name, and SKU. ### Get assigned device count by fleet - [GET /portal/V1/diagnostics/assigned-devices-by-fleet](https://visionmax.redocly.app/master-diagnostics/masterdiagnosticsgetassigneddevicesbyfleet.md): Returns the total number of devices assigned to each fleet, including fleet name and ID. ### Get device activity list - [GET /portal/V1/diagnostics/device-activity/list](https://visionmax.redocly.app/master-diagnostics/masterdeviceactivitylist.md): This API is used to list devices have been assigned to fleets. Only devices that have been initiated will appear in the list. ### Autocomplete device activity list - [GET /portal/V1/diagnostics/device-activity/auto-complete](https://visionmax.redocly.app/master-diagnostics/masterdeviceactivityautocomplete.md): This API is used to autocomplete search keywords for the device activity list. ### Export device activity list - [GET /portal/V1/diagnostics/device-activity/export](https://visionmax.redocly.app/master-diagnostics/masterdeviceactivityexport.md): This API is used to export excel for the device activity list. ### Get device diagnostic status summary - [GET /portal/V1/diagnostics/status](https://visionmax.redocly.app/master-diagnostics/masterdiagnosticsgetdevicestatussummary.md): Returns a summary of all device diagnostics, including total count, health status, and categorized issues. Useful for deployment monitoring and device condition analysis. ## Master - FleetAnalysis ### Usage analysis - [GET /portal/V1/get-plan-analysis](https://visionmax.redocly.app/master-fleetanalysis/devicplananalysis.md): Provide an overview of plan statistics to administrators ## Master - Management ### Get data usage report - [GET /portal/V1/ota/data-usage](https://visionmax.redocly.app/master-management/masterdatausage.md): This API is used to get the data use report of a certain device, inputs: serial number of the device, start and end timestamp, frequency to update the report ### Get user account of current Master - [GET /portal/V1/get-users](https://visionmax.redocly.app/master-management/masteruserlist.md): This API is used to get the accounts of current Master, query with account created time, email, ID, last log in time, organization ID, role, account status, username. ### Add new master account - [POST /portal/V1/add-user](https://visionmax.redocly.app/master-management/addmaseteruser.md): This API is to add a new master account, service will send an activation email to allow the user to activate its account. User’s email address, role of the user, user name, are required. ### Get user account of Fleet - [GET /portal/V1/get-fleet-accounts](https://visionmax.redocly.app/master-management/fleetuserlist.md): This API is used to get the accounts of Fleet, information of the account: created time, ID, user email address, last log in time, organization ID, user role, account status, and username. ### Add new fleet account - [POST /portal/V1/add-fleet-account](https://visionmax.redocly.app/master-management/addfleetuser.md): This API is to add a new fleet account, service will send an activation email to allow the user to activate its account. User’s email address, role of the user, user name, and fleet ID are required. This API is no longer being updated and will be removed in a future release. Please use NewAddFleetUser instead. ### Add fleet user (New) - [POST /portal/V1/fleet/user/add](https://visionmax.redocly.app/master-management/newaddfleetuser.md): This API allows the master's admin to add a fleet user. ### Edit fleet account - [POST /portal/V1/edit-fleet-account](https://visionmax.redocly.app/master-management/editfleetuser.md): This API is used to edit an existed fleet account with fleet ID, user role, and username. This API is no longer being updated and will be removed in a future release. Please use NewEditFleetUser instead. ### Edit fleet user (New) - [POST /portal/V1/fleet/user/{user_id}/edit](https://visionmax.redocly.app/master-management/neweditfleetuser.md): This API allows the master's admin to add a fleet user. ### Change status of fleet account - [POST /portal/V1/change-fleet-account-status](https://visionmax.redocly.app/master-management/changefleetuserstatus.md): This API is to change status of a fleet account, to active and deactivate or delete account ### Change status of Master account - [POST /portal/V1/change-user-status](https://visionmax.redocly.app/master-management/changemasteruserstatus.md): This API is to change status of a master account, to active and deactivate or delete account ### Get inventory list - [GET /portal/V1/inventory/list](https://visionmax.redocly.app/master-management/masterinventorylist.md): This API is used to list the device in Master's inventory (all devices associated with this master account). Devices’ information will be retrieved, for example: IMEI 1/2, software version, last recorded GPS information…etc. ### Assign device into fleet - [POST /portal/V1/assign-devices-fleet](https://visionmax.redocly.app/master-management/masterassigndevicefleet.md): To assign devices to fleet. Multiple device ids are accepted. The device will be moved from the master's inventory into the fleet. ### Get unassigned inventory list - [GET /portal/V1/inventory/unassigned/list](https://visionmax.redocly.app/master-management/masterinventoryunassignedlist.md): This API is used to list devices in the Master inventory that have not been assigned to any fleet. \ This endpoint provides pagination functionality and allows the use of additional query parameters to control the retrieval of subsequent data. ### Get assigned inventory list - [GET /portal/V1/inventory/assigned-to-fleets/list](https://visionmax.redocly.app/master-management/masterinventoryassignedtofleetslist.md): This API is used to list devices in the Master inventory that have been assigned to fleets.\ This endpoint provides pagination functionality and allows the use of additional query parameters to control the retrieval of subsequent data. ### Autocomplete unassigned inventory list - [GET /portal/V1/inventory/unassigned/auto-complete](https://visionmax.redocly.app/master-management/masterinventoryunassignedautocomplete.md): This API is used to autocomplete search keywords for the unassigned inventory list. ### Autocomplete assigned inventory list - [GET /portal/V1/inventory/assigned-to-fleets/auto-complete](https://visionmax.redocly.app/master-management/masterinventoryassignedtofleetsautocomplete.md): This API is used to autocomplete search keywords for the assigned inventory list. ### Get fleet list - [GET /portal/V1/get-fleets](https://visionmax.redocly.app/master-management/masterfleetlist.md): This API is used to get the fleets list under current account, including How many account created in the fleet, account address, ID, created time, fleet ID, fleet name, phone number registered for the fleet, preferred timezone setting when system sends notification email or messages. ### Get the information of fleet - [GET /portal/V1/get-fleet](https://visionmax.redocly.app/master-management/mastergetfleet.md): This API is to get the information of a fleet, including number of accounts created in the fleet, fleet name, fleet ID, fleet created time, email address of fleet owner, phone number of the fleet owner, preferred timezone setting when system sends notification email or messages. ### Add a new fleet - [POST /portal/V1/add-fleet](https://visionmax.redocly.app/master-management/masteraddfleet.md): This API is to add a new fleet ### Delete a fleet - [POST /portal/V1/delete-fleet](https://visionmax.redocly.app/master-management/masterdeletefleet.md): Delete the fleet with the fleet Id ### (deprecated) Edit fleet information - [POST /portal/V1/edit-fleet](https://visionmax.redocly.app/master-management/masterupdatefleet.md): This API has been deprecated; we recommend using the new one. ### Configuration list of fleet. - [GET /portal/V1/fleet/{fleet_id}/configurations](https://visionmax.redocly.app/master-management/getfleetconfiguration.md) ### Update the configuration of fleet. - [POST /portal/V1/fleet/{fleet_id}/configurations](https://visionmax.redocly.app/master-management/updatefleetconfiguration.md): This API can be used to modify the configuration of fleet, ensuring that each modification will overwrite the previous settings This configuration relies on dynamic JSON input. ### Add fleet and admin - [POST /portal/V1/fleet/add](https://visionmax.redocly.app/master-management/masteraddfleetadmin.md): This API can simultaneously add fleet and admin. ### Edit fleet - [POST /portal/V1/fleet/{fleet_id}/edit](https://visionmax.redocly.app/master-management/mastereditfleet.md): This API allows the admin to edit information of fleet. Only the parameters that are passed in will be updated. ### Get device list of fleet - [GET /portal/V1/get-group-device-list](https://visionmax.redocly.app/master-management/masterfleetdevicelist.md): This API is used to get the device list of fleet, query with device IMEI, activated time, app version, base image version, CID, device ID, device name, fleet ID, fleet name, fist connected timestamp, group ID, installation position…etc. ### To update device plan type and vehicle type - [POST /portal/V1/edit-devices-vehicle-plan](https://visionmax.redocly.app/master-management/mastereditfleetdevicvehicleplan.md): This API is to update device plan type and vehicle type. Update vehicle type will be deprecated in the future ### Recall a device from fleet - [POST /portal/V1/recall-devices-fleet](https://visionmax.redocly.app/master-management/masterrecallfleetdevice.md): This API is used to recall a device from fleet. The device will lists in Master's inventory after recall. Need the device id to recall, can insert multiple device IDs. ### Get device meta data - [GET /portal/V1/device/meta-data](https://visionmax.redocly.app/master-management/mastergetdevicemetadata.md): This API retrieves the device's metadata based on its single unit identifiers. At least one of the parameters must be provided. ### Format sd card - [POST /portal/V1/device/FormatSdCardToDevice/{cid}](https://visionmax.redocly.app/master-management/masterformatsdcardtodevice.md): Send a remote command to formate SD card ### Get general info of devices - [GET /portal/V1/get-device-detail](https://visionmax.redocly.app/master-management/mastergetdevice.md): This can be used to retrieve general information of a device: IMEI 1/IMEI 2, activated from, activated date/time, application version, front camera height, CID, device ID, device name, device installed location, firmware version, first connected timestamp, group ID, online status…etc. Emit the cid to retrieve the full list. ### Get health report of device - [GET /portal/V1/health/{cid}](https://visionmax.redocly.app/master-management/masterdevicehealthreport.md): Used to fetch the last time diagnostic report of a device. Including: assigning status, attention flag, CID, device ID, model, device name, repair flag, and report. ### Get the last parking snapshot photos - [GET /portal/V1/devices/GetLastParkingPhoto/{cid}](https://visionmax.redocly.app/master-management/getlastparkingsnapshot.md): Get the latest parking-related event snapshots by device CID. Supports multiple camera angles. ### Get installed snapshot info - [GET /portal/V1/devices/{serial_number}/installed-info](https://visionmax.redocly.app/master-management/getinstalledsnapshotinfo.md): Fetch installed snapshot images by serial_number. Includes capture timestamp and camera angles. ### Get AI snapshot info - [GET /portal/V1/get-device-ai](https://visionmax.redocly.app/master-management/getdeviceaiinfo.md): Fetch latest DMS and ADAS snapshots by device certificate ID (cid). ## Master - Ota ### Add new device group - [POST /ota/api/device/group/save](https://visionmax.redocly.app/master-ota/otaadddevicegroup.md) ### Query current device groups - [GET /ota/api/device/group/all](https://visionmax.redocly.app/master-ota/otaquerydevicegroup.md): Could get device group uuid ### Check if the device exists - [GET /ota/api/device/exists](https://visionmax.redocly.app/master-ota/otacheckdeviceexist.md) ### Add new devices - [POST /ota/api/device/save](https://visionmax.redocly.app/master-ota/otaadddevice.md): Please not call save device again, it will reset the device status. To avoid confusing, check device exist first. ### Delete devices - [POST /ota/api/device/delete](https://visionmax.redocly.app/master-ota/otadeletedevice.md) ### Change device group - [POST /ota/api/device/changeGroup](https://visionmax.redocly.app/master-ota/otachangedevicegroup.md) ### Query device information - [GET /ota/api/device/findBy](https://visionmax.redocly.app/master-ota/otaquerydeviceinformation.md) ### Query all apps installed in device - [GET /ota/api/device/app/installed](https://visionmax.redocly.app/master-ota/otaqueryinstalledapp.md) ### Check if the app is installed - [GET /ota/api/device/app/isInstalled](https://visionmax.redocly.app/master-ota/otacheckappisinstalled.md) ### Check if devices have applied the profile - [GET /ota/api/device/profile/devices](https://visionmax.redocly.app/master-ota/otacheckprofileapplied.md): Using filter to get devices. ### Query all apps - [GET /ota/api/apps/findAll](https://visionmax.redocly.app/master-ota/otaqueryallapp.md): ### App Management Any app must be uploaded before requesting to update/install. ### Pagenated app list - [GET /ota/api/apps/find](https://visionmax.redocly.app/master-ota/otaqueryapp.md) ### Query all system images - [GET /ota/api/otas/findAll](https://visionmax.redocly.app/master-ota/otaqueryallota.md): ### System Image(OTA image) Management Any system image must be uploaded before requesting to update. There're 2 kinds of image, one is base image and the other is region image. Whichever the image is, the format is different for AB or Non-AB partition. In addition, the image can be partial image.Multiple images can be listed in the request, but the MiDM will feed proper image depend on the device state. For example, the size of all partial images is bigger than full image, it will select full image to meet the final image. Any image is not for the device, the images will be rejected. ### Pagenated system image list - [GET /ota/api/otas/find](https://visionmax.redocly.app/master-ota/otaqueryota.md) ### New profile request - [POST /ota/api/device/profile/apply](https://visionmax.redocly.app/master-ota/otanewprofile.md): If isGlobal is true, any scope will be ignored. If no profile.name described, the profile name will be the time stamp as formatted "yyyyMMdd_hh:mm:ss". If the scoped devices not existing, it will be registered automatically. { "isGlobal": , "profile": { "name": "", "applyOrder": "none|apps|otas|settings", "removeIfNoScope": "true|false", "unscopeIfApplied": "true|false" }, "scope": { "group": [], "device": []}, "apps": {"install": [{"uuid": "", "silentInstall": }]}, "otas": [], "settings": {} } Example JSON: { "scope": { "group": [ "020a7dbf-ad72-474a-87a1-a9f90372e94b", "649205ee-3ce6-4b37-ae42-14a272e31201" ] }, "apps": { "install": [ { "uuid": "37088946-e6f4-49e3-b45a-05beda912df2", "starts_on_update": true, "silent_install": true, "grant_all": true }, { "uuid": "37088946-e6f4-49e3-b45a-05beda912df2" } ] }, "otas": [ "48231c37-1fb9-4876-b4b2-c817cc52ffa8", "94de7ae1-b750-4839-bf3f-39ec76a4c76d" ], "schedule_date": { "start_on": "2024-02-06" }, "settings": { "otas": { "silent_install": true, "partialFirst": true, "need_ac": false, "checkBuildDate": true } } } Must record the profileUuidIntroduce for params: apps.install: starts_on_update: After updating the app, need start it or notsilent_install: Before updating the app, it will not ask user to confirm to install the app if set truegrant_all: try to grant all permission from App neededsettings.otas: silent_install: Before updating the image, it will not ask user to confirm to update the image if set truepartialFirst: The size of all partial images is less than full image, it will select the sequence to do partial images update one by oneneed_ac: When doing image update, need plug ac power or notcheckBuildDate: If true, only allow region upgrade, will check Region build date ### Query current profiles - [GET /ota/api/device/profile/find](https://visionmax.redocly.app/master-ota/otaqueryprofile.md): List all profiles with paging or filter. ### Load existed profile - [GET /ota/api/device/profile/{profileUuid}](https://visionmax.redocly.app/master-ota/otaloadexistedprofile.md): List all profiles with paging or filter. ### Update profile - [POST /ota/api/device/profile/save](https://visionmax.redocly.app/master-ota/otaupdateprofile.md): Load existed profile first. Then, edit and save it. ## SetUp ### Set up re-calibrate - [POST /V2/device/{serial_number}/setup/re-calibrate](https://visionmax.redocly.app/setup/setuprecalibrate.md): Request camera recalibration between DMS and ADAS. ### Set up camera height - [POST /V2/device/{serial_number}/setup/camera-height](https://visionmax.redocly.app/setup/setupcameraheight.md): Used to set the camera height. ### Set up installation location - [POST /V2/device/{serial_number}/setup/install-location](https://visionmax.redocly.app/setup/setupinstalllocation.md): This API allows users to specify the installation position of a dashcam. The location can be set for left-hand drive vehicles, right-hand drive vehicles. • Left：The dashcam is installed on the left side of the vehicle, suitable for left-hand drive vehicles. • Right：The dashcam is installed on the right side of the vehicle, suitable for right-hand drive vehicles. ### Set up DMS Camera - [POST /V2/device/{serial_number}/setup/dms-camera](https://visionmax.redocly.app/setup/dms-camera.md): Specifies the type and installation location of the DMS camera. ### Set up Device and DMS Camera - [POST /V2/device/{device}/setup/device-and-dms-camera](https://visionmax.redocly.app/setup/setupdeviceanddmscamera.md): Set up both the device installation location and the DMS camera at the same time. This endpoint is only available for devices running Camera App version 11.2.24.30 or above. Devices with an older version will not be able to access this API. ## SmartGo (Beta) ### Get Device OBD2 data - [GET /V2/devices/obd2/{device}](https://visionmax.redocly.app/smartgo-(beta)/getdeviceobd2.md): This API is under active development. Its request and response formats may change without prior notice. Please consult the latest documentation for updates. Description table of vehicle data |#|Key|Name|Unit|Note| |:---:|:------|:-------|:-------|:-------| | 1 | timestamp | Timestamp | milliseconds | Default is milliseconds, and it respects the time_unit parameter if provided. | | 2 | vin | Vehicle VIN | | | | 3 | engin_status | Engin Status | Status value | 0: Off 1: On | | 4 | fuel_level | Fuel Level | % | | | 5 | fuel_rate | Fuel Rate | L/hr | | | 6 | speed | Speed | KM/hr | | | 7 | rpm | RPM | RPM | | | 8 | engine_hours | Engine Hours | Hour | | | 9 | trip_hours | Trip Hours | Hour | | | 10 | odometer | Odometer | KM | | | 11 | mil_status | MIL Status | Status value | 0 = MIL Off 1 = MIL On | | 12 | dtc | DTC | String | Raw parameters sent by the device | | 13 | battery_voltage | Battery Voltage | V | | | 14 | coolant_temperature | Coolant Temperature | °C | | | 15 | engine_load | Engine Load | % | | | 16 | intake_temperature | Intake Temperature | °C | | | 17 | intake_pressure | Intake Pressure | kPa | | | 18 | throttle_position | Throttle Position | % | | | 19 | engine_oil_level | Engine Oil Level | % | | | 20 | mass_air_flow | Mass Air Flow | Gallons / sec | | | 21 | decoded_dtc | Decoded DTC Data | Object | Parsed diagnostic information (See details below) | | 22 | dongle_mac_address | Dongle MAC Address | String | The unique hardware MAC address. Note: It can be derived by converting the decimal Serial Number back to Hexadecimal. | Details for decoded_dtc Object: * mil: Malfunction Indicator Lamp status. * dtcs: Map of error codes (e.g. P0100) to ECU source and detailed description. * vin: VIN associated with the DTCs. > Note: The vin and mil fields within this object are consistent with the top-level vin and mil_status fields. ## Webhook ### List webhooks - [GET /webhook](https://visionmax.redocly.app/webhook/listwebhook.md): The available webhooks currently provided by VisionMax are: \ Enum:[EVENT_TRIGGERED, TRIP_STARTED, TRIP_FINISHED, GPS_UPDATE, ASSET_UPLOADED, TASK_UPDATE, DEVICE_STATUS_UPDATE, DEVICE_PROVISIONED] \ \ Each notification delivery expects to receive a '200 HTTP status code' with a JSON response of {'status':'success'}. Otherwise, it will be considered a failed delivery. Notification can only be received by the specified roles. - EVENT_TRIGGERED { "type": "Notification", #string: type of notification "hookName": "EVENT_TRIGGERED", #string: the hook name "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "device_sn": "serial number here", #string: the serial number of device "device_cid": "certificate of device here", #string: the certificate id of device "gps": { #object: the gps object "lng": "121.374111", "lat": "25.047111", "alt": "0.0", "speed": "0.0", "direction": "N" }, "timestamp": 1706745916, #number: the timestamp of the reported event "event_type": 5, #number: the id of event type "event_name": "Start Up", #string: the name of event "ticket": "4b2afd89-8123-4842-b430-c95fc143b14a", #string: the ticket of event "severity_level": "Minor", #string: the severity level of the event, Enum:[Minor, Moderate, Severe] "task_id": "cc2afd89-8423-4942-b430-112c9a9e51b6", #string: remote task ID "detail": "URL", #string: follow the URL to retrieve details of the event "snapshots": { #object: the snapshot info "count": 2, #number: the count of the capture mode of snapshot "capture_mode": ["C_F", "C_I"] #list: the list of the capture mode of snapshot }, "video": { #object: the video info "count": 0, #number: the count of the capture mode of video "capture_mode": [] #list: the list of the capture mode of video }, "nfc": { #object: the nfc info "id": "ee565d" #string: the nfc id } }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } Speed information in the gps object is represented in meters per second(m/s). - TRIP_STARTED { "type": "Notification", #string: type of notification "hookName": "TRIP_STARTED", #string: the hook name "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "device_sn": "serial number here", #string: the serial number of device "device_cid": "certificate of device here", #string: the certificate id of device "gps": { #object: the gps object "lng": "121.374111", "lat": "25.047111", "alt": "0.0", "speed": "0.0", "direction": "N" }, "timestamp": 1706745916, #number: the timestamp of the trip's start time "detail": "URL" #string: follow the URL to retrieve details of trip }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } Speed information in the gps object is represented in meters per second(m/s). - TRIP_FINISHED { "type": "Notification", #string: type of notification "hookName": "TRIP_FINISHED", #string: the hook name "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "device_sn":"serial number here", #string: the serial number of device "device_cid":"certificate of device here", #string: the certificate id of device "gps":{ #object: the gps object "lng": "121.374111", "lat": "25.047111", "alt": "0.0", "speed": "0.0", "direction": "N" }, "timestamp": 1706745916, #number: the timestamp of the trip's start time "detail": "URL" #string: follow the URL to retrieve details of trip }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } Speed information in the gps object is represented in meters per second(m/s). - GPS_UPDATE { "type": "Notification", #string: type of notification "hookName": "GPS_UPDATE", #string: the hook name "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "device_sn": "serial number here", #string: the serial number of device "device_cid": "certificate of device here", #string: the certificate id of device "gps": { #object: the gps object "lng": "121.374111", "lat": "25.047111", "alt": "0.0", "speed": "0.0", "direction": "N" "satellites_in_use": 8, #number: the number of satellites in use "satellites_visible": 12, #number: the number of satellites visible }, "timestamp": 1706745916, #number: the timestamp of the reported GPS "speed_data": { #object: the speed data object. If the device has not enabled MMF, the value will be null. "speed_limit": 64, #number: the speed limit of the road segment where the device is located (unit: km/h). "over_speed": 0, #number: the excess speed over the limit (unit: km/h). This value is 0 when the device is not overspeeding. "speed": 60, #number: the device speed (unit: km/h). "is_over_speed": false #boolean: Indicates whether the device is currently exceeding the speed limit. }, }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } Speed information in the gps object is represented in meters per second(m/s). - ASSET_UPLOADED { "type": "Notification", #string: type of notification "hookName": "ASSET_UPLOADED", #string: the hook name "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "device_sn": "serial number here", #string: the serial number of device "device_cid": "certificate of device here", #string: the certificate id of device "timestamp": 1706745916 #number: the timestamp of file creation "event_type": 5, #number: the id of event type which the file belongs "event_name": "Start Up", #string: the name of event which the file belongs "ticket": "4b2afd89-8123-4842-b430-c95fc143b14a", #string: the ticket of event which the file belongs "task_id": "cc2afd89-8423-4942-b430-112c9a9e51b6", #string: the remote task ID of event which the file belongs "event_detail": "URL", #string: follow the URL to retrieve details of the event which the file belongs "file_type": "SNAPSHOT", #string: the type of file, Enum:[NMEA, SNAPSHOT, VIDEO] "capture_mode": "C_I", #string: the capture mode of file "file_detail": "URL" #string: follow the URL to retrieve details of the file "latest_upload_speed": 512000, #number: the latest upload speed (unit: bytes/second) }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } - TASK_UPDATE { "type": "Notification", #string: type of notification "hookName": "TASK_UPDATE", #string: the hook name "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "device_sn": "serial number here", #string: the serial number of device "device_cid": "certificate of device here", #string: the certificate id of device "task_id": "411b64be-4598-4fdc-a0c9-4099bc6417b5", #string: the task ID "state": "ack" #string: the state of task "code": "D_S00000", #string: the code for the execution result from the device "report_at": 1706745916, #number: the timestamp of the task update report "desc": "desc here" #string: the description for the execution result from the device }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } - DEVICE_STATUS_UPDATE Connectivity state is inferred from camera-initiated messages. Therefore, webhooks are triggered only when the camera sends GPS updates or heartbeats. - The system can detect offline → online when GPS updates resume. - The system cannot proactively detect transitions such as online → standby/offline or standby → offline. To better infer the device’s real connectivity state, it is recommended to track two separate timestamps: 1. last_connected_timestamp - Source: Connectivity API or GPS_UPDATE - Updated only when a GPS update is received - Represents when the device was last actively connected and transmitting GPS data and used to infer online status 2. last_heartbeat_timestamp - Source: DEVICE_STATUS_UPDATE - Extract the changed_at value when changed_by === "heartbeat" - Represents when the device last sent a heartbeat signal and use to infer standby/offline status Using both timestamps together allows more accurate differentiation between online, standby, and offline conditions. Notes and Important Considerations - The last_connected_timestamp is not updated when a heartbeat is received. - Connectivity states(online, standby, offline) are designed to represent the device’s connectivity capability, not its physical power state or real-time operational condition. { "type": "Notification", #string: type of notification "hookName": "DEVICE_STATUS_UPDATE", #string: the hook name "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "device_sn": "serial number here", #string: the serial number of device "device_cid": "certificate of device here", #string: the certificate id of device "previous_status": "offline", #string: the previous status of device, Enums: online, offline, standby, waking_up "new_status": "online" #string: the new status of device, Enums: online, offline, standby, waking_up "changed_at": 1706745916, #number: the timestamp when device status was changed "changed_by": "heartbeat", #string: the action that triggered the device status change "health": {} #object: the health report of device }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } - DEVICE_PROVISIONED Master only { "type": "Notification", #string: type of notification "hookName": "DEVICE_PROVISIONED", #string: the hook name "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "device_sn": "serial number here", #string: the serial number of device "device_cid": "certificate of device here", #string: the certificate id of device "device_meta_data": {}, #object: the meta data of device, it will have a value only when the action is provision; otherwise, it will be null. "from": "MiTAC" #string: the name of fleet or SI the device is from. "to": "name of SI" #string: the name of fleet or SI the device is going to. "action": "provision" #string: the action, Enums: provision, assign, recall. "action_at": 1706745916, #number: the timestamp when the action occurred. "action_by": "user's email", #string: the email of the user who executed this action. }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } > Each notification delivery expects to receive a '200 HTTP status code' with a JSON response of {'status':'success'}. Otherwise, it will be considered a failed delivery. \ > Failed notification delivery will be retried up to 12 times with an interval of one hour. \ > The notification service attaches a signature in the body of every delivered message. The signature is RSA with SHA1. #### Verify the message with the signature (optional) 1. Deserialize the JSON body. 2. Retrieve the signature from the field: signature. 3. Retrieve the key ID from the field: kid. 4. Obtain the public key from the webhook-signing endpoint using the key ID from the previous step. 5. Verify the signature with the message field. Note: Do not deserialize the message field because the signature is signed with the JSON string. ### Subscribe to webhook - [POST /webhook/subscribe](https://visionmax.redocly.app/webhook/webhook%20subscribe.md): Subscribe to the webhook to receive notifications. \ If necessary, you can resubscribe to the same webhook to update the target URL. In order to confirm that the target URL is valid and ready to receive notifications, \ the notification service will send a raw POST request to the target URL, and expects to receive a 200 HTTP status code to activate the subscription, regardless of whether the response body is present. \ Sample of the raw POST body: { "type": "Subscription", #string: type of notification "messageId": "msg id", #string: the message id "message": "{ #string: the json string of notification message "time": "1706745891545478712", "hook_name": "GPS_UPDATE", "url": "https://sample.com/gps_update" }", "signature": "signature of the message", #string: signature of the message "kid": "The key id of the signing key" #string: the key id } ### Unsubscribe a webhook - [POST /webhook/unsubscribe](https://visionmax.redocly.app/webhook/webhook%20unsubscribe.md) ### Retrieve the public key - [GET /webhook-signing/{kid}](https://visionmax.redocly.app/webhook/webhook%20publickeyverifysign.md): Retrieve the public key used for verifying the signatures. Plain text of the public key. \ ex: -----BEGIN PUBLIC KEY----- ....... -----END PUBLIC KEY-----