Python SDK

The Python SDK is the definite-python package (Python 3.10+). It wraps the Vault REST API: readiness, report programs, runs, exceptions, and receipts.

pip install definite-python

Create a client

import os
 
from definite import DefiniteClient
 
with DefiniteClient(
    base_url="https://vault.example.com",
    api_key=os.environ["DEFINITE_API_KEY"],
) as client:
    readiness = client.get_readiness()

The client works synchronously and asynchronously from the same class, and supports context managers in both modes. Configuration can also come from the environment through DefiniteConfig (prefix DEFINITE_):

Field	Type	Required	Description
DEFINITE_BASE_URL	string	Yes	Vault base URL.
DEFINITE_API_KEY	string	Direct mode	Tenant API key, sent as X-Vault-API-Key.
DEFINITE_PROXY_API_KEY	string	Proxy mode	Proxy key, sent as X-Vault-Proxy-API-Key. Requires DEFINITE_CLIENT_ID; mutually exclusive with DEFINITE_API_KEY.
DEFINITE_CLIENT_ID	string	Proxy mode	Tenant identifier; proxy requests are rewritten to /proxy/client/{client_id}/v1/...
DEFINITE_TIMEOUT	float	No	Request timeout in seconds. Default 30.
DEFINITE_MAX_RETRIES	int	No	Retry budget for transient failures. Default 3.

Monitor runs and read receipts

from definite import DefiniteClient
 
# DefiniteClient() reads DEFINITE_BASE_URL and DEFINITE_API_KEY from the environment
with DefiniteClient() as client:
    readiness = client.get_readiness()
    print(readiness.verdict_counts)
 
    runs = client.list_runs(limit=10).items
    for run in runs:
        print(run.run_id, run.status)
 
    completed = client.wait_for_run(runs[0].run_id, timeout=300)
 
    for receipt in client.list_receipts().items:
        print(receipt.rule_id, receipt.verdict)

wait_for_run polls until the run reaches completed or failed, and raises RunTimeoutError if the timeout elapses first. A completed run can still contain FAIL or CANNOT_VERIFY receipts; run state and rule verdicts are separate.

Runs usually start from the console, a schedule, or a data refresh. To start one programmatically, call POST /v1/programs/{program_id}/runs over REST — the SDK's create_program_run and list_report_programs in 1.0.0 still target a retired endpoint path and will be repointed in the next release.

Method reference

Field	Type	Required	Description
get_readiness()	Readiness	—	Verdict counts, open exceptions, and program status. Metadata, never a verdict.
list_report_programs() / get_report_program(id)	Programs	—	Configured programs and their bound rule versions. In 1.0.0, targets a retired path — see the note above.
create_program_run(program_id, ...)	Runs	—	Start an asynchronous run. In 1.0.0, targets a retired path — use REST /v1/programs/{id}/runs until the next release.
list_runs() / get_run(id) / retry_run(id)	Runs	—	Inspect runs; retry creates a new child run and leaves the original immutable.
list_run_events(id) / list_run_inputs(id)	Runs	—	Immutable stage telemetry and the input snapshot references bound to the run.
wait_for_run(id, timeout=...)	Runs	—	Poll until completed or failed.
list_exceptions() / get_exception(id)	Exceptions	—	FAIL and CANNOT_VERIFY findings with their investigation state.
update_exception(id, ...) / review_exception(id, ...)	Exceptions	—	Assign, annotate, and record a human review. Reviews never change the original verdict.
list_receipts() / get_receipt(id)	Receipts	—	Signed, hash-chained rule receipts.

Async variants (aget_readiness, aget_run, await_for_run, aclose) mirror the synchronous API. Error types: DefiniteError, DefiniteAPIError, DefiniteConnectionError, RunTimeoutError, and TrustedProxyRequiredError.

Do not send raw source values in SDK requests. Runs bind to immutable source snapshots that Vault already holds; receipts and evidence responses carry references and hashes, not raw sensitive values.