/details for flash-region locations, identification blocks, map descriptors, grid cells or comparison details. See ECU file observation for the request workflow.
Identification
An identity contains the ECU information supported by the analysis. Missing manufacturer, family, variant, software or hardware information remains unknown. A plausible candidate is not automatically an accepted identity. For identity alone, usePOST /v2/ecu/identifications. It returns the same identification section as an inspection, without the inspection findings. The variant field is the ECU model/variant; hardware and software are separate identifiers, not inferred from the vehicle name.
Always display the identification status together with confidence.level and confidence.explanation:
Confidence levels are
high, medium, low and unknown. They summarize evidence strength. Do not convert them into percentages, a tuning-quality score, or a statement that a file can be flashed safely.
For example, an identity section can look like this:
File observations
Inspection can report unusual fill or erased-looking regions, map structure observations and supported checksum findings. A warning is a reason to investigate, not proof of a modification.- No issue detected means that the checks which ran did not find that particular issue.
- Review needed means an observation deserves attention.
- Unavailable or partial coverage means some checks could not establish a result.
- Complete coverage means every listed supported check was evaluated. It does not mean that every possible check for this ECU is supported.
- Unknown checksum validity does not mean the checksum passed or failed. A supported checksum passing also does not establish that the entire file is suitable for a vehicle.
Inspection evidence
condition.checks contains the measurements behind each assessment:
For example,
flagged_axis_count: 21 and table_count: 118 means the axis check flagged 21 axes across 118 high-score tables. It does not mean every detected axis was checked. Missing checked_axis_count is unknown, not zero. Reliable suspicious-axis locations are not available, so locations_available is false; use a candidate’s grid to review its raw axes.
checksums.reason: "no_supported_scheme_detected" distinguishes a completed check that found no supported scheme from coverage_unavailable. Both leave validity unknown. Passing or failing supported checks use supported_checks_passed or supported_checks_failed.
layout contains the file size, region count, bytes by classification, and identification-block count. Fetch the same job’s details to see all flash regions and up to 200 identification-block ranges:
kind, start, end, and size_bytes, with available fill-byte, fill-ratio and high-score candidate counts. Offsets are zero-based bytes, with an inclusive start and exclusive end. For example, an erased region from 1703936 (0x1A0000) to 1835008 (0x1C0000) occupies 131072 bytes. A trailing erased region contributes to the total erased bytes but is excluded from the internal-region warning. Identification blocks contain locations only; returned and omitted block counts make the 200-block display bound explicit.
Accepted identification can also include byte_order and cell_width_bytes. Each map descriptor still specifies its own cell width and byte order.
Older compact reports were saved without these additions. Updated /details responses expose evidence already retained for those jobs without rerunning analysis. Missing historical evidence stays omitted. New compact reports require a new inspection job.
File comparisons
Use the terms reference and comparison in your interface. Neither role establishes originality, tuning intent or ECU compatibility. Byte differences are exact observations. Map matches and map-level comparisons can be heuristic. Different-length files report overlapping-byte changes and the extra bytes separately; an extra tail is not silently counted as a shifted map.realigned_map_candidates counts matches where the map comparison shifted a cell window. Such a shift can skip changed cells at an edge: changed_map_candidates: 0 can coexist with a nonzero changed_bytes. Reports flag this with a map_realignment notice, and comparison items in /details include realigned. Use exact byte differences when deciding whether the supplied files differ. Older saved compact reports may omit the realignment count.
An identical result means the supplied file contents are byte-for-byte equal. It does not prove either file is original. A changed result means the contents differ; it does not prove the difference is a performance tune.
Candidate maps and grids
Map descriptors identify regions which resemble calibration tables. Names, physical units and scaling can be unknown. Preserve that uncertainty in your interface. The map counts describe different stages:detected_before_layout is the structural candidate count, excluded_by_layout counts candidates outside the selected layout regions, and available is the resulting browsable count. For example, 723 detected minus 22 excluded leaves 701 available. axes_count counts detected axes before layout filtering. The health check’s 118 high-score candidates can legitimately be a smaller number: that check uses a separate threshold and scope. None of these totals is a verified count of named calibration maps.
A grid is the actual table of numbers inside one candidate map. A scan tells you where a table is and how many rows and columns it has; a grid request retrieves those cell values and available axes. For a 16-by-12 table, that means 192 values. Use them to build a table, heatmap or 3D surface. See Read map values for the request and retrieval steps.
Grid values are bounded raw cell values, not automatically RPM, torque, pressure or another physical quantity. Axes can be available without established physical meaning. Never label unknown units based only on the shape of a graph.
Use the map ID returned by the same file’s completed inspection or scan. A grid request cannot define its own memory address, dimensions or stride. Returned and omitted counts explain how much detail is present; increasing limit does not improve identification confidence.
Job state versus analysis findings
completed means processing finished successfully. An unknown identity, unsupported checksum or review warning can all belong to a completed job.
failed means processing did not produce a valid result. Do not display a failed job’s partial information as a completed inspection. Continue to distinguish expired data from an unknown ECU: expiry is a storage lifecycle event, not an identification finding.
Browse every map candidate
For a complete list, usemaps.artifact.download_url to download every candidate once. The artifact includes all descriptors, independent of the 1–200 page limit. Keep it in your client to browse and search without repeated API calls. Inspection health evidence and flash layout remain in the report; grid values remain on demand.
The paginated API below remains available for clients that prefer individual pages and for older jobs without a stored download.
New inspections and map scans retain all detected candidates. The submission limit sets the default number of descriptors per page (20 by default, at most 200), not the total you can browse.
After the job completes, request:
maps.pagination.next_offset for the next request on the same job, stopping when it is null. This reads stored results; it does not rerun the scan or create another analysis job.
maps.items and the explanatory message. available is the total detected candidate count. returned counts descriptors on this page, and omitted means candidates outside this page, including earlier pages. Use next_offset, not omitted, to decide whether another page exists. Page size can be changed without submitting another scan.
Map IDs from any page can be used for a grid request with the original scan_job_id and file_id. Paging works until the result expires, even if the uploaded file has expired; new grid extraction still requires the file to be available.
Older scans may have discarded candidates. If rescan_required is true, only retained descriptors can be retrieved. Submit a fresh scan with a new Idempotency-Key to browse all candidates. Repeating the old submission key returns the old job.
Map pagination parameters apply to inspection and map-scan details only. Comparison details and grids keep their existing response limits.