> ## Documentation Index
> Fetch the complete documentation index at: https://docs.remapdb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ECU file observation

> Identify ECU files, inspect observations, compare changes, and read candidate maps with asynchronous jobs.

> [!NOTE]
>
> 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.

All ECU endpoints start with **`https://api.remapdb.com/v2/ecu/`**. These endpoints are part of API v2.

Open **API → [ECU observation](https://app.remapdb.com/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](https://app.remapdb.com/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

Send `Authorization: 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.

```bash theme={null}
curl --request POST 'https://api.remapdb.com/v2/ecu/files' \
  --header "Authorization: Bearer $REMAPDB_API_KEY" \
  --form 'file=@ecu.bin'
```

**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](#identify-an-ecu-only).

```bash theme={null}
curl --request POST 'https://api.remapdb.com/v2/ecu/analyses' \
  --header "Authorization: Bearer $REMAPDB_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: inspection-example-001' \
  --data '{"file_id":"YOUR_FILE_ID","operation":"inspect","limit":20}'
```

**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

| Endpoint | Purpose |
| - | - |
| `GET /v2/ecu/capabilities` | Supported operations, limits and retention periods. |
| `POST /v2/ecu/files` | Upload one raw binary. |
| `DELETE /v2/ecu/files/{file_id}` | Revoke the upload and schedule its removal. |
| `POST /v2/ecu/identifications` | Identify the ECU and supported hardware/software identifiers only. |
| `POST /v2/ecu/analyses` | Identify or inspect one uploaded file. |
| `POST /v2/ecu/comparisons` | Compare reference and comparison file IDs. |
| `POST /v2/ecu/map-scans` | Find candidate maps in one file. |
| `POST /v2/ecu/map-grids` | Read a candidate map from a completed scan or inspection. |
| `GET /v2/ecu/jobs/{job_id}` | Retrieve job status and its compact result when complete. |
| `GET /v2/ecu/jobs/{job_id}/result` | Retrieve the compact completed report. |
| `GET /v2/ecu/jobs/{job_id}/details` | Retrieve inspection evidence and flash layout, map pages (`offset`, `limit`), grid values or comparison details. |
| `GET /v2/ecu/jobs/{job_id}/artifacts/maps` | Authorize a short-lived download of every saved candidate map descriptor. |

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

Use `POST /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`:

```bash theme={null}
curl --request POST 'https://api.remapdb.com/v2/ecu/identifications' \
  --header "Authorization: Bearer $REMAPDB_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: identification-example-001' \
  --data '{"file_id":"YOUR_FILE_ID"}'
```

This endpoint accepts only `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**:

| Field | Meaning |
| - | - |
| `manufacturer` | ECU manufacturer, such as Bosch. |
| `family` | ECU family, such as EDC17. |
| `variant` | Specific ECU model/variant, such as EDC17C60; not the vehicle model. |
| `hardware` | Hardware identifier or number. |
| `software` | Software identifier or version. |
| `calibration_id` | Supported calibration identifier. |
| `part_number` | Supported OEM part number. |

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](https://docs.remapdb.com/api/ecu-results.md#identification).

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 includes `confidence.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](https://docs.remapdb.com/api/ecu-results.md) before displaying condition or comparison findings to a customer.

## Comparing files and viewing maps

For comparison, submit `reference_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:

```bash theme={null}
curl --request POST 'https://api.remapdb.com/v2/ecu/map-grids' \
  --header "Authorization: Bearer $REMAPDB_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: map-values-example-001' \
  --data '{"file_id":"YOUR_FILE_ID","scan_job_id":"YOUR_SCAN_JOB_ID","map_id":"YOUR_MAP_ID"}'
```

This creates a new job. Poll its `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 expose `maps.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.

1. Request `GET /v2/ecu/jobs/{job_id}/artifacts/maps?redirect=false` with your API key. In the Mintlify playground, set the **redirect** query parameter to **false**.
2. Read the HTTP `200` JSON response's `url` field. 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.
3. Decode the JSON, verify its `schema_version`, `job_id`, `maps.items.length` and SHA-256 against the manifest, then browse or search `maps.items` locally.

For example, Python's `requests` library can download and verify the complete JSON:

```python theme={null}
import hashlib
import json
import os
from pathlib import Path
import requests

job_id = "YOUR_JOB_ID"
link = requests.get(
    f"https://api.remapdb.com/v2/ecu/jobs/{job_id}/artifacts/maps?redirect=false",
    headers={"Authorization": f"Bearer {os.environ['REMAPDB_API_KEY']}"},
    allow_redirects=False,
    timeout=30,
)
if link.status_code != 200:
    raise RuntimeError(f"Download unavailable: {link.status_code} {link.text}")
manifest = link.json()["artifact"]
download = requests.get(link.json()["url"], allow_redirects=False, timeout=30)
if download.status_code != 200:
    raise RuntimeError(f"Storage download failed: {download.status_code}")
content = download.content  # requests decodes Content-Encoding: gzip
assert len(content) == manifest["size_bytes"]
assert hashlib.sha256(content).hexdigest() == manifest["sha256"]
report = json.loads(content)
assert report["schema_version"] == manifest["schema_version"]
assert report["job_id"] == job_id
assert len(report["maps"]["items"]) == manifest["map_count"]
Path("ecu-maps.json").write_bytes(content)
```

For a browser application, perform the authenticated link request on your backend and return only the short-lived storage URL and manifest to the browser. Keep your API key on the server. The browser can then download directly from storage with `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](https://docs.remapdb.com/api/ecu-results.md#browse-every-map-candidate); 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 the `expires_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 string `error.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`.

| HTTP status | Action |
| - | - |
| `400` | Correct the request body, options or idempotency key. |
| `401` / `403` | Check credentials, scopes and account access. |
| `404` | The file or job is unavailable to this account. |
| `409` | Check job readiness, scan binding or idempotency-key reuse. |
| `410` | The file or result has expired. |
| `413` / `415` | Check the upload size and raw binary format. |
| `429` | Slow down and follow retry guidance. |
| `503` | Retry later using the same idempotency key for the same submission. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.