Runtime API

In one line. Drive a delivered solution from your own systems over REST: authenticate with an API key, submit document packages, read structured results, findings, audit trails and metrics — everything under api/runtime/v1. You’ll be able to. Create and manage keys, submit a package or trigger a job, poll it to completion, and consume its output without a human touching the UI.

What it is for

The consumer surface is for people; the Runtime API is for machines. Loan origination systems submitting document packages, ERPs pulling settled invoice fields, portals embedding decision status — anything that treats a Botminds solution as a service calls this API.

It is deliberately a runtime API: it operates a solution that already exists. Building and changing solutions stays in Studio, where governance can see it.

Keys and authentication

Keys are managed per project by an admin, and every key is scoped to that project’s data — a key cannot read across projects.

• Create, rotate and revoke keys via the admin surface (or api/projects/{finonId}/api-keys if you automate key management itself).
• The full secret is shown once at creation; store it in your secret manager. What remains visible afterwards is the key’s prefix, for identification.
• Send the key on every call in the X-API-Key header.

curl -H "X-API-Key: <your key>" https://<your-host>/api/runtime/v1/docsets/<docSetId>/status

Rotate keys on your normal credential schedule; rotation issues a new secret while the old one stops working, so plan a cutover window.

The surface, by resource

Resource	You can	Typical call
Jobs & runs	Trigger a one-off run of a configured job (async: 202 + runId); poll the run to a terminal state	POST /jobs/{jobId}/runs, GET /runs/{runId}
Doc sets — api/runtime/v1/docsets	Submit N documents as one package (inline base64, URLs, or a pre-uploaded folderPath for high volume); append documents; track status; reprocess	POST /docsets, GET /docsets/{id}/status, POST /docsets/{id}/reprocess
Trailing documents	Submit a late-arriving document — matched to its package by loanNumber, else held UNMATCHED for manual association	POST /documents/trailing
Output — under docsets	Pull the assembled decision package	GET /docsets/{id}/output, GET /docsets/{id}/output/status
Documents — api/runtime/v1/documents	Read classification, extracted fields, per-field history, validation findings, split/merge lineage, and the full actor-attributed audit timeline	GET /documents/{docId}/fields, GET /documents/{docId}/audit
Sign-off — under docsets	Read a package’s attestation state and history — including a stale flag when output changed after sign-off	GET /docsets/{id}/sign-off
Stacking — under docsets	Read the effective document order; apply a stacking template	GET /docsets/{id}/stacking, POST /docsets/{id}/stacking/apply
Findings — under docsets	Generate and read the findings summary for audit and delivery	POST /docsets/{id}/findings/generate, GET /docsets/{id}/findings
Snapshots — under docsets	Capture a package’s state now; list generations; retrieve a stored snapshot verbatim	POST /docsets/{id}/snapshots, GET /docsets/{id}/snapshots/{gen}
Reviews — api/runtime/v1/reviews	See the human-review queue and its event log; read who’s assigned to a package	GET /reviews/queue?status=open, GET /docsets/{id}/assignment
Metrics — api/runtime/v1/metrics	Cost per day/model, straight-through-processing rate, QC fail rate, extraction quality, error distribution, drift	GET /metrics/cost?from=&to=
Compliance	The tenant’s AI/OCR/LLM subprocessor register; the LLM invocation log (model, tokens, prompt shape — never prompt text)	GET /providers, GET /prompt-log

The canonical integration loop

1. Submit — your system posts a document package (POST /docsets) or triggers a job.
2. Poll — watch the doc set’s status (or the run) until it reaches a terminal state.
3. Read — pull extracted fields, classification, findings, or the assembled output.
4. Attest — when a human signs off in the platform, read the attestation back (GET /docsets/{id}/sign-off) so your system of record stays aligned; its stale flag tells you if the output changed after the sign-off.

The surface is deliberately read-heavy: its writes are submit, append, trailing, reprocess, stacking-apply, findings-generate and snapshot-capture. Correcting a field and signing off a decision stay role-gated actions inside the platform, where the same lifecycle, confidence gates and audit trail govern them — every API write is audited and attributed to the key that made it.

Practical notes

• Idempotency — job triggers honor an Idempotency-Key header (same key + job within 24h returns the original run). Pass a loanId on submit and a re-submit while that package is in progress is rejected with 409 DUPLICATE_SUBMISSION. Poll status rather than re-queueing; reprocess is an explicit, separate call.
• Errors — standard HTTP semantics with a machine-readable body (an error code plus message): 401 for a missing/invalid key, 404 for objects outside the key’s project scope.
• Least exposure — treat the key like a production database credential. One key per consuming system makes revocation surgical.

Where to go next

• The human side of the same queue: G2 · Human-in-the-loop.
• Driving the platform from AI tools instead of code: V2 · MCP integration.
• What the packages contain: D1 · Collections & schema.