Skip to Content
Open Books for developers

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 8765

If 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/health

Check 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 pathRequest and response
GET /v1/healthEngine and schema versions, OCR/model/link capabilities and limits.
GET /v1/formatsSupported formats and layouts that are unverified on real exports.
GET /v1/samplesSynthetic sample catalog, with file metadata and sample parameters.
GET /v1/samples/{id}Bytes of a bundled synthetic example.
POST /v1/runsMultipart files and optional JSON string fields params and file_params. Streams SSE.
POST /v1/rolesMultipart file and optional params. Returns openbooks.roles.v1. Requires model availability.
POST /v1/linkJSON {"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.

EventInterpret it as
file.startedThe file entered processing. Track it by index.
file.stageStage progress. It carries no release decision.
file.donedoc contains that file's full release or refusal.
run.doneThe run finished with aggregate counts.
run.errorA 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

  1. Check the HTTP status before parsing SSE frames. A 422 can indicate invalid request parameters. A 503 on roles or link can indicate an unavailable capability.
  2. Use an SSE parser that can assemble a frame split across network chunks. Track file decisions by index and store each full file.done document.
  3. Use run.done as the batch completion signal. On run.error or a closed connection before completion, keep completed file decisions and mark files without file.done as interrupted.
  4. Retry interrupted files and handle doc.status: "refused" using the refusal guide. Send only released documents to downstream accounting.
View this page as Markdown