Self-hosted HTTP API
Run the FastAPI engine on a private network, upload batches with multipart forms and consume server-sent release or refusal events.
Use the self-hosted API when your application server needs to send files to a separate Open Books process and receive progress and decisions as they arrive. The FastAPI service wraps the Python engine. Run it on loopback or a private network and apply authentication and rate limiting at your application boundary.
1. Start the service
From the repository checkout, create and activate a Python 3.11+ virtual environment using the installation guide. Run these commands from the checkout root and leave the server running.
python -m pip install -e packages/py/openbooks -e server
python -m uvicorn openbooks_server.app:app --host 127.0.0.1 --port 8765If OCR is needed, use -e "server[scan]" in the installation command and check its OCR and model dependencies. For an MCP client, use the separate Open Books MCP server.
2. Check health and capabilities
In a second terminal, request engine health. On Windows PowerShell, use curl.exe in place of curl if your shell treats curl as an alias.
curl http://127.0.0.1:8765/v1/healthCheck that the service responds and reports openbooks.v1. Read the capability flags before sending scans, requesting model roles, or matching payouts. For example, check link_available before calling the optional linking endpoint.
Endpoint reference
| Method and path | Request and response |
|---|---|
GET /v1/health | Engine and schema versions, OCR/model/link capabilities and limits. |
GET /v1/formats | Supported formats and layouts that are unverified on real exports. |
GET /v1/samples | Synthetic sample catalog, with file metadata and sample parameters. |
GET /v1/samples/{id} | Bytes of a bundled synthetic example. |
POST /v1/runs | Multipart files and optional JSON string fields params and file_params. Streams SSE. |
POST /v1/roles | Multipart file and optional params. Returns openbooks.roles.v1. Requires model availability. |
POST /v1/link | JSON {"docs": [...]} containing released documents. Optional linker returns openbooks.links.v1. |
One run takes up to 20 files. The shared params field accepts currency, opening as a decimal string, account, date_order (dmy or mdy), and the boolean flags allow_derived_opening, ocr, and model. To override a field for a file, use its zero-based index in file_params. For example, {"1":{"opening":"1590.12"}} sets the opening balance for the second upload while retaining the other shared settings.
3. Upload a file and read the stream
Download the example CSV into your current directory. Run the following command in a POSIX shell, such as Bash. The -F options build the multipart form and -N displays events as curl receives them.
curl -N http://127.0.0.1:8765/v1/runs \
-F '[email protected]' \
-F 'params={"currency":"INR","opening":"1000.00","date_order":"dmy"}'The response uses server-sent events (SSE). Each SSE frame has an event name and JSON data. The sample produces a file.done event at index 0 with doc.status: "ok", followed by run.done with released: 1 and refused: 0.
| Event | Interpret it as |
|---|---|
file.started | The file entered processing. Track it by index. |
file.stage | Stage progress. It carries no release decision. |
file.done | doc contains that file's full release or refusal. |
run.done | The run finished with aggregate counts. |
run.error | A run-level error interrupted processing. Inspect the reported cause. |
Override settings for one file
The example sends the same sample twice to demonstrate how shared and per-file settings interact. The first file inherits the verified opening. The second clears it with null and needs review.
curl -N http://127.0.0.1:8765/v1/runs \
-F '[email protected]' \
-F '[email protected]' \
-F 'params={"currency":"INR","opening":"1000.00","date_order":"dmy"}' \
-F 'file_params={"1":{"opening":null}}'Expect a file.done release at index 0, a file.done refusal with PARSE_ERROR at index 1, and run.done with released: 1 and refused: 1. Use the index to associate each decision with its upload settings, even if the filenames are identical.
4. Handle failures and interrupted runs
- Check the HTTP status before parsing SSE frames. A
422can indicate invalid request parameters. A503on roles or link can indicate an unavailable capability. - Use an SSE parser that can assemble a frame split across network chunks. Track file decisions by index and store each full
file.donedocument. - Use
run.doneas the batch completion signal. Onrun.erroror a closed connection before completion, keep completed file decisions and mark files withoutfile.doneas interrupted. - Retry interrupted files and handle
doc.status: "refused"using the refusal guide. Send only released documents to downstream accounting.
Node.js and TypeScript
Run the local Python engine from Node.js, integrate typed results and handle refusals separately from execution errors.
MCP for AI agents
Download and install the Open Books Model Context Protocol server to verify financial files with an AI agent and inspect the evidence in one batched call.