API — drive OpenRemap from code

openremap.api is the programmatic face of OpenRemap: the library that other programs use to do everything the terminal commands do — identify a file, scan a folder, cook a recipe, apply a tune — without ever touching a terminal.

Everything in this section is for developers. If you are here to tune a car with the terminal, the getting-started guide is the better place to start.

Where the API sits

OpenRemap is built in layers, and the API is the seam in the middle:

The point of the middle layer: the CLI and a GUI never re-implement rules. Defaults and validation live once, in each method's schema, and every consumer reads them from the registry.

What a method is

A method is one action the engine knows how to do — identify, cook, tune, scan, … You call a method by name with a dict of parameters; it returns a plain, JSON-safe dict (never a Python object you have to serialise yourself).

Each method is registered in the registry together with metadata:

• its kind — command (atomic), composite (orchestrated), or workflow (a declarative pipeline),
• a description,
• an input_schema — every parameter: its type, whether it is required, its default, and numeric bounds.

Schema rules, kinds and errors are explained on the concepts page; the complete list of methods is the reference.

Three ways in, one path out

The API deliberately offers three ways to call the same methods, all backed by one dispatch path — so results are identical no matter how you call:

import openremap.api as api

api.call("identify", {"path": "stock.bin"})   # 1. in-process dispatch
api.ping()                                     # 2. ergonomic direct function
#                                              # 3. JSON-RPC over stdio:
#  python -m openremap.api.transport.stdio     #    {"method": "identify", ...}

Every result returned by call is JSON-serialisable, so the in-process result and the RPC result are equivalent. In short:

Three ways in, one path out.

The same call on each surface

ping — the liveness check — on all three:

import openremap.api as api
print(api.call("ping", {}))   # → {"ok": True}
print(api.ping())             # → {"ok": True}

# JSON-RPC: pipe one request line, read one response line
echo '{"id": 1, "method": "ping", "params": {}}' \
  | python -m openremap.api.transport.stdio
# → {"id": 1, "result": {"ok": true}}

And a real method, identify, is worked through end-to-end on its own page: identify — API (in-process + JSON-RPC + error codes).

Pages in this section

Not the terminal guide

Careful with the word workflow: the API-side workflow is a declarative .toml pipeline (documented here) — it is not the CLI command openremap workflow, which just prints a step-by-step guide in your terminal (getting-started/workflow). The two share only a name.

Where to go next