Customer developer docs

Your first workflow run

Create a run, poll its state, inspect stage telemetry, resolve an exception, and retrieve signed receipts.

Your first workflow run

A run executes one workflow program — for example a reconciliation control or a regulatory report program — against the immutable source snapshots Definite already holds. A manual run does not accept source data in the request.

Create and poll

POST /v1/programs/{program_id}/runs requires an idempotency_key and returns 202 with a queued run. Poll GET /v1/runs/{run_id} until the run reaches a terminal state.

Run states: queued, running, waiting_for_input, waiting_for_review, completed, failed.

Run state and rule results are separate. A completed run can contain FAIL or CANNOT_VERIFY receipts — completion means the workflow finished, not that every check passed.

Inspect stage telemetry

GET /v1/runs/{run_id}/events returns an immutable sequence of stage events across ingest, map, check, investigate, and assemble. Each event records its stage, status, actor kind, actor role, and attempt. Agent events may carry provider, model, usage, and provenance details. Check-stage events use actor_kind: deterministic_engine and cannot carry a model identity; human events are generated only by authenticated review operations.

Resolve an exception

FAIL and CANNOT_VERIFY findings appear under /v1/exceptions with states open, investigating, awaiting_human, and resolved. Agents attach investigation drafts — a classified root cause, gathered evidence, and a drafted correction or explanation. A human reviews the exception (PATCH /v1/exceptions/{exception_id}, POST /v1/exceptions/{exception_id}/reviews) and triggers another run when the underlying data is fixed. Reviews never change the original verdict; a new run produces new receipts.

Retrieve receipts

GET /v1/receipts and GET /v1/receipts/{receipt_id} return, per check: rule ID, rule version, and citation; the exact verdict; typed input references (each a reference type, an opaque reference ID, and a sha256: content hash); the previous receipt hash; the receipt hash, hash scheme, and ledger epoch; the signed payload, signature, algorithm, and signer key ID; and the checkpoint reference. Raw sensitive source values are never present in a receipt.

Export artifacts

Run artifacts are listed under GET /v1/artifacts, each with lineage (GET /v1/artifacts/{artifact_id}/lineage). Exports come in two states: draft exports always carry a DRAFT - NOT FOR FILING watermark, and final exports are only authorized from the console by an admin or owner once the run is complete with zero open blocking exceptions, all checks passing, and finalized receipts covering every result. Definite never files anything: your team downloads final artifacts and submits through your own process.