scan-vins — API

This page is for developers. If you just want to scan a file, the plain-English introduction is the better place to start.

scan_vins is one method registered with openremap.api. Everything the CLI can do, the API can do too — same scan, same input rules, same result.

Note

Spelling: the API method is scan_vins (underscore), the terminal command is scan-vins (dash).

The method is a command: one cohesive operation in one domain (atomic).

Input schema

{
    "path": {"type": "str", "required": True, "description": "Path to the binary."},
    "min_confidence": {"type": "float", "default": 0.4, "min": 0.0, "max": 1.0},
}

Defaults and validation live in the schema, in the registry — not in the CLI or any client. Every consumer reads the same contract via list_methods.

Calling it in-process (Python)

import openremap.api as api

result = api.call("scan_vins", {"path": "stock.bin"})
# result is a plain JSON-serialisable dict — the same report as `openremap scan-vins --json`

for c in result["candidates"]:
    print(hex(c["offset"]), c["vin"], c["confidence"], c["evidence"])

The result is JSON-safe, so an in-process call and an RPC call are interchangeable.

Calling it over JSON-RPC

echo '{"id": 1, "method": "scan_vins", "params": {"path": "stock.bin", "min_confidence": 0.6}}' \
  | python -m openremap.api.transport.stdio

Response (one JSON object per line):

{"id": 1, "result": {"file": "stock.bin", "file_size": 2097152, "candidates": [{"offset": 8192, "vin": "WVWZZZ1KZ7W059972", "confidence": 0.9, "...": "..."}]}}

Errors come back as JSON-RPC error objects — clients branch on code:

{"id": 1, "error": {"code": -32602, "message": "scan_vins: missing required param 'path'"}}

Out-of-range values are validated too:

{"id": 1, "error": {"code": -32602, "message": "scan_vins: min_confidence must be <= 1.0"}}

Error handling

Code	Meaning	Example message
`-32602`	Invalid params (schema validation)	`scan_vins: missing required param 'path'`
`-32601`	Method not registered	`Unknown method: 'scan_vinsx'`
`-32000`	Guard rejection (business rule, not a bug)	`Binary file 'stock.bin' is empty.`
`-32603`	Unexpected internal failure	—

A missing or empty file, or an image that fails to decode, raises a guard error (-32000) — a clean client-facing rejection, never a traceback.

Discovery — `list_methods`

import openremap.api as api

catalogue = api.call("list_methods", {})
meta = next(m for m in catalogue["methods"] if m["name"] == "scan_vins")
print(meta["kind"])          # "command"
print(meta["input_schema"])  # the schema above

Quick smoke test

echo '{"id": 1, "method": "ping", "params": {}}' | python -m openremap.api.transport.stdio
# → {"id": 1, "result": {"ok": true}}