ECU observation is included with active API and MAX subscriptions. Use your standard API key with
vdb_read; no separate account activation is needed. Catalog-only trials are not eligible.https://api.remapdb.com/v2/ecu/. These endpoints are part of API v2.
Open API → ECU observation in the app for access requirements, the analysis workflow and documentation links. This page does not enable the service; use the capabilities endpoint below to confirm availability for your key. Manage credentials under API → API Keys & Usage → API Keys.
Use ECU observation to identify a binary, review its structure and supported checksums, inspect candidate maps, or compare two supplied files. It does not modify files, identify the reading tool, or certify that a file is original, tuned, compatible, or safe to flash.
Access and files
SendAuthorization: Bearer <API_KEY> with every API request. Do not send this header to the signed storage URL used for map downloads. Standard keys with vdb_read support all ECU operations. Restricted keys can instead use ecu_observe for uploads, job submission and deletion, and ecu_read for capabilities, job status and results. File and job IDs belong to the authenticated account; knowing an ID does not grant access.
Only raw binary files are accepted, up to 8 MiB (8,388,608 bytes) each. Archives, Intel HEX and S-record files are not automatically decoded. Uploads are immutable: upload a new file when its contents change. Client requests use file IDs, never local paths or storage URLs.
Upload, analyze, retrieve
1
Upload the binary
Send the file as the
file field of a multipart request. Save the returned file_id, checksum and expiry.2
Start an inspection
Submit the file ID with a unique
Idempotency-Key. The API returns HTTP 202 and a job ID. When you only need the ECU identity, use the dedicated identification endpoint.3
Poll the job
Request
GET /v2/ecu/jobs/{job_id} until it completes or reaches a terminal state. Poll conservatively, for example every two seconds with increasing delay. Polling retrieves saved state and does not restart analysis. A failed job is still a successfully retrieved job record; inspect its status and error.4
Read the report
GET /v2/ecu/jobs/{job_id}/result returns the compact report, including inspection health-check counts and layout totals. Request /details for flash-region offsets, identification-block locations, internal erased regions, candidate map descriptors, grid cells or comparison details.Available operations
The identification, analysis, comparison, map-scan and map-grid endpoints are asynchronous and require an
Idempotency-Key: 1–128 printable ASCII characters, without spaces. Uploads and result retrieval are synchronous. Use the same key and unchanged request when retrying a submission after a connection failure. Reusing a key for a different operation or parameters returns 409. JSON request bodies are limited to 64 KiB.
Identify an ECU only
UsePOST /v2/ecu/identifications when you need the ECU manufacturer, family, model/variant and hardware/software identifiers, without an inspection or map report. First upload the raw binary through /v2/ecu/files, then send its file_id:
file_id; do not send operation or limit. It returns HTTP 202 with a job ID and status_url. Poll that URL until status is completed, then read GET /v2/ecu/jobs/{job_id}/result. Identification remains asynchronous even though the report is small.
The result has operation: "identify", a short message, an identification object and notices. The identity includes status and confidence, plus these fields when established:
Missing identifiers are omitted. Some files cannot establish every field, and a completed identification can be
unknown or review_required. See the example identity and confidence explanation.
The existing /v2/ecu/analyses request with operation: "identify" remains supported and runs the same identification operation.
Confidence and unknown results
Every report containing identification includesconfidence.level and a short confidence.explanation. Levels are high, medium, low or unknown. They describe identification evidence, not a probability of correctness or confidence that flashing is safe.
Identification can be identified, review_required or unknown. Review-required and unknown analyses are completed jobs, not processing failures. Missing identity fields are omitted; your application should display “Unknown” rather than inventing a value. Read Understanding ECU results before displaying condition or comparison findings to a customer.
Comparing files and viewing maps
For comparison, submitreference_file_id and comparison_file_id. These are neutral roles: neither file is assumed to be an original or a tuned file. The report distinguishes changed overlapping bytes from an extra tail when lengths differ.
Read map values
A map scan finds candidate tables and returns descriptors in the completed job’s/details: their IDs, positions and dimensions. A grid request reads the actual numbers inside one of those tables, arranged in rows and columns. For example, a map with 16 rows and 12 columns has 192 cell values. Your application can display those values as a table, heatmap or 3D surface; the API returns the data, not a rendered chart.
Send the original file_id, the completed inspection or map-scan job’s scan_job_id, and one of that result’s map_id values:
status_url, then read /v2/ecu/jobs/{job_id}/details for grid.values (rows of raw numbers) and grid.axes (available axis values, or null). The compact /result contains dimensions and a numeric summary; it does not contain the cell array. An illustrative two-row, three-column grid.values array is [[100, 120, 140], [110, 130, 150]].
Do not reuse map IDs across files or scans. The service checks that the map still belongs to the same file and analysis configuration. Reading a grid does not change the binary.
Map names, units and physical scaling can be unknown. A candidate map is a structural observation, not a verified calibration definition. Grid values are raw unsigned integers unless the response explicitly establishes otherwise.
limit defaults to 20 and accepts 1–200 for descriptor pages. It does not limit the complete stored map download. A single grid is limited to 65,536 cells. Poll the compact job record and retrieve map descriptors once the job completes.
Download all map candidates
Completed inspections and map scans exposemaps.artifact in their report when a stored download is available. Its download_url is a stable, authenticated API path. The worker creates the artifact once; downloading it does not run another analysis or make the API load the map list.
- Request
GET /v2/ecu/jobs/{job_id}/artifacts/maps?redirect=falsewith your API key. In the Mintlify playground, set the redirect query parameter to false. - Read the HTTP
200JSON response’surlfield. Open it separately to download the file, or fetch it immediately with no API Authorization header or cookies. The storage URL expires within 60 seconds, or sooner if the job expires. Request a fresh link when needed. - Decode the JSON, verify its
schema_version,job_id,maps.items.lengthand SHA-256 against the manifest, then browse or searchmaps.itemslocally.
requests library can download and verify the complete JSON:
credentials: "omit" and referrerPolicy: "no-referrer".
Omitting redirect or setting it to true preserves the HTTP 302 response with a Location header. Use redirect=false for browser requests: following a redirect between the API and storage can change the browser’s Origin to null and fail storage CORS checks. The JSON mode avoids that redirect and still serves the large file directly from storage.
The versioned JSON (remapdb.ecu.maps.v1) contains all descriptors in maps.items, with returned equal to available and omitted: 0. A job with 701 candidates downloads all 701 in one artifact. Offsets, dimensions and IDs are included; raw grid cells are still retrieved separately. The original binary and private diagnostics are never included.
size_bytes and sha256 describe the decoded JSON bytes; compressed_size_bytes describes the stored gzip object. Browsers and many HTTP clients decode Content-Encoding: gzip automatically. Keep signed URLs out of logs and shared links: anyone holding one can use it until its short expiry, even if the API key is revoked in the meantime. A browser integration requires the storage endpoint’s CORS policy to allow its origin.
Older jobs without maps.artifact remain readable through map pagination; their download endpoint returns 404 artifact_unavailable. Submit a fresh inspection or scan with a new idempotency key to create a stored download.
Retention and deletion
Uploads are available for 24 hours and completed results for seven days by default. Use theexpires_at returned by the API to check when each file or result expires. Queued and running jobs have expires_at: null; the result expiry is assigned when processing reaches a terminal state.
A saved report, map download or already-generated grid can remain readable after its source upload expires. Stored map downloads expire with their job result. Starting another analysis or extracting another grid requires an unexpired binary. Re-upload the file and obtain a fresh scan when needed.
Expired jobs can briefly remain visible with status: "expired" before their records are removed. Idempotency protection ends when that job record is removed; do not rely on an old key as permanent deduplication history.
Deleting an upload immediately prevents new use. Physical removal can finish after an active job releases it. Retained result access follows the result’s own expiry. Store any customer records you need beyond the advertised retention in your own system.
Handling errors
Errors contain a stringerror.code and a short error.message, including authentication failures. Missing or invalid credentials return 401 with invalid_key; request-rate limits return 429 with rate_limited. ECU job quotas use quota_exceeded. Use the documented HTTP method for each endpoint; unsupported methods return 405 with method_not_allowed.
For a terminal failed job, read its short public error. A new job submission is a new attempt; do not repeatedly submit a file that fails validation. Keep credentials, binary contents and detailed customer results out of application logs.