enterprise_ai.evidence

Source: sdks/python/src/enterprise_ai/evidence/__init__.py. Back to the Python SDK reference index.

note

This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.

Class EvidenceClient

/v1/evidence.

Resource

EvidenceClient.access_log

access_log(limit: int | None = None) -> Any

Read the audit access log. Returns the latest accesses to the audit trail, newest first: actor, roles, kind (read, search, verify, export, payload_decrypt, seal_read), query, number of results, reason and the audit event written. Needs auditor or security_officer. Reading the log is itself recorded.

Route: /v1/evidence/access-log (GET).

Name	Type	Default	Required	Description
limit	int | None	None	no	Maximum number of entries (default 200, maximum 1000).

Returns: Any. Decoded JSON answer of the operation "Read the audit access log".

Raises: the typed errors of the transport (Errors).

EvidenceClient.alerts

alerts(status: str | None = None) -> Any

List the integrity alerts. Lists the integrity alerts of the tenant opened by the monitor: chain_broken, sequence_gap, seal_invalid, outbox_missing or clock_skew, refreshed while the problem persists. Needs auditor, security_officer or tenant_admin.

Route: /v1/evidence/alerts (GET).

Name	Type	Default	Required	Description
status	str | None	None	no	Only open or acknowledged alerts.

Returns: Any. Decoded JSON answer of the operation "List the integrity alerts".

Raises: the typed errors of the transport (Errors).

EvidenceClient.bundle

bundle() -> Any

Export an offline evidence bundle. Returns bundle (events, seals and public keys of the tenant) and manifest (format, counts, SHA-256 of the canonical bundle, alg: Ed25519, key id, public key and signature by the seal key). An external auditor verifies it offline with python -m eai.domains.evidence.verify. Needs auditor or security_officer. Answers 503 audit_seal_key_unavailable without signing key. The export is recorded in the access log.

Route: /v1/evidence/bundle (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Export an offline evidence bundle".

Raises: the typed errors of the transport (Errors).

EvidenceClient.create_hold

create_hold(case_id: str, reason: str, time_from: str | None = None, time_to: str | None = None) -> Any

Place an evidence legal hold. Places a legal hold on the payloads of the tenant for a case and an optional period of event time: while it is active, the payload retention purge and erasures skip the events it covers. time_to must be after time_from (400 invalid_request). Needs auditor, security_officer or tenant_admin. Writes the audit event audit.legal_hold.create. Answers 201 with the hold.

Route: /v1/evidence/holds (POST).

Name	Type	Default	Required	Description
case_id	str		yes	Case reference, 1 to 200 characters.
reason	str		yes	Why the hold is placed, 3 to 1000 characters.
time_from	str | None	None	no	Start of the period of event time covered (ISO 8601). Null: no lower bound.
time_to	str | None	None	no	End of the period covered (ISO 8601), after time_from. Null: no upper bound.

Returns: Any. Decoded JSON answer of the operation "Place an evidence legal hold".

Raises: the typed errors of the transport (Errors).

EvidenceClient.create_seal

create_seal() -> Any

Seal the audit chain now. Writes a seal over the events written since the previous seal (up to the platform maximum per seal) and returns it (201). Needs security_officer or auditor. Answers 409 audit_nothing_to_seal when no event is waiting, 503 audit_seal_key_unavailable without signing key.

Route: /v1/evidence/seals (POST).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Seal the audit chain now".

Raises: the typed errors of the transport (Errors).

EvidenceClient.gateway

gateway() -> Any

Get the Audit Gateway status. Returns the delivery state of the audit events of the tenant to the SIEM: configured targets, pending and delivered counts, max_attempts of a pending event and oldest_pending. Needs auditor, security_officer or tenant_admin.

Route: /v1/evidence/gateway (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Get the Audit Gateway status".

Raises: the typed errors of the transport (Errors).

EvidenceClient.list_holds

list_holds() -> Any

List the evidence legal holds. Lists the legal holds of the tenant with their case, period, reason, status and release approvals. Needs auditor, security_officer or tenant_admin.

Route: /v1/evidence/holds (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "List the evidence legal holds".

Raises: the typed errors of the transport (Errors).

EvidenceClient.list_seals

list_seals() -> Any

List the audit seals. Lists the seals of the tenant chain: number, sequence range, Merkle root, first and last hashes, previous seal hash, key id, signature and date. Needs auditor, security_officer or tenant_admin. The read is recorded in the access log.

Route: /v1/evidence/seals (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "List the audit seals".

Raises: the typed errors of the transport (Errors).

EvidenceClient.payload

payload(event_id: str, reason: str) -> Any

Decrypt the payload of an audit event. Returns the decrypted sensitive fields of one event in payload, with access_event_id, the audit event that records this access. Only auditor or security_officer held explicitly: platform_admin is not enough (403 forbidden). A reason is required. Errors: 404 not_found (no payload), 410 audit_payload_purged (expired or erased), 409 audit_payload_tampered (ciphertext digest mismatch), 503 audit_payload_key_unavailable.

Route: /v1/evidence/events/{event_id}/payload (POST).

Name	Type	Default	Required	Description
event_id	str		yes	Identifier (UUID) of the audit event.
reason	str		yes	Why the payload is read, 5 to 500 characters. Written to the access log.

Returns: Any. Decoded JSON answer of the operation "Decrypt the payload of an audit event".

Raises: the typed errors of the transport (Errors).

EvidenceClient.record_components

record_components(run_id: str, components: list[dict[str, Any]], step_seq: int | None = None) -> Any

Record the components of a run. Records, append only, the versions of the components used by an agent run, or by one step of it with step_seq (tool call, model call). Each report is audited with the versions field of the Audit Event. Needs tenant_admin, agent_operator or developer. Answers 201 with the recorded items, or 404 not_found for an unknown run.

Route: /v1/evidence/runs/{run_id}/components (POST).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the agent run.
components	list[dict[str, Any]]		yes	Components used, 1 to 100.
step_seq	int | None	None	no	Sequence number of the step (1 or more); omit it for the run as a whole.

Returns: Any. Decoded JSON answer of the operation "Record the components of a run".

Raises: the typed errors of the transport (Errors).

EvidenceClient.release_hold

release_hold(hold_id: str, reason: str) -> Any

Approve the release of a legal hold. Records one release approval with its reason. The hold is released at the second approval by a distinct approver; the same person twice answers 409 audit_hold_same_approver, a hold no longer active 409 audit_hold_not_active, an unknown hold 404. Needs auditor, security_officer or tenant_admin. Writes audit.legal_hold.release_approve, then audit.legal_hold.release.

Route: /v1/evidence/holds/{hold_id}/release (POST).

Name	Type	Default	Required	Description
hold_id	str		yes	Identifier (UUID) of the legal hold.
reason	str		yes	Why the hold can be released, 3 to 1000 characters.

Returns: Any. Decoded JSON answer of the operation "Approve the release of a legal hold".

Raises: the typed errors of the transport (Errors).

EvidenceClient.retention

retention() -> Any

List the purge evidence. Lists the purge evidence records of the tenant: kind, cutoff, purged and held counts, purged sequences and the Merkle root of the purged ciphertext digests, never the contents. Needs auditor, security_officer or tenant_admin.

Route: /v1/evidence/retention/evidence (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "List the purge evidence".

Raises: the typed errors of the transport (Errors).

EvidenceClient.run_configuration

run_configuration(run_id: str) -> Any

Get the execution configuration of a run. Rebuilds the execution configuration of an agent run: agent version and manifest digest, components reported by kind (model, prompt, tool, skill, plugin) with their versions and digests, and the policy decisions recorded for the run. Needs auditor, security_officer or tenant_admin, agent_operator or developer. The read is recorded in the access log. Answers 404 not_found for an unknown run.

Route: /v1/evidence/runs/{run_id}/configuration (GET).

Name	Type	Default	Required	Description
run_id	str		yes	Identifier (UUID) of the agent run.

Returns: Any. Decoded JSON answer of the operation "Get the execution configuration of a run".

Raises: the typed errors of the transport (Errors).

EvidenceClient.run_retention

run_retention(kind: str | None = None, cutoff: str | None = None, event_ids: list[str] | None = None, dry_run: bool | None = None) -> Any

Purge expired audit payloads. Deletes encrypted audit payloads; the events, the chain and the seals stay and keep verifying.

Route: /v1/evidence/retention/run (POST).

Name	Type	Default	Required	Description
kind	str | None	None	no	retention (default, by age) or erasure (listed events).
cutoff	str | None	None	no	For retention: payloads of events older than this date are purged (ISO 8601). Default: now minus the payload retention period.
event_ids	list[str] | None	None	no	For erasure: events whose payloads are erased, at most 1000. Required for an erasure.
dry_run	bool | None	None	no	When true, reports what would be purged without deleting anything (default false).

Returns: Any. Decoded JSON answer of the operation "Purge expired audit payloads".

Raises: the typed errors of the transport (Errors).

EvidenceClient.verify

verify() -> Any

Verify the chain and every seal. Verifies the whole tenant chain and every seal and returns tenant_id, valid, chain (hash chain result), seals (count and failures), clock (timestamp failures) and events (number checked). Needs auditor, security_officer or tenant_admin. The verification is recorded in the access log.

Route: /v1/evidence/verify (GET).

This element takes no parameter.

Returns: Any. Decoded JSON answer of the operation "Verify the chain and every seal".

Raises: the typed errors of the transport (Errors).

EvidenceClient.verify_seal

verify_seal(seal_id: str) -> Any

Verify an audit seal. Recomputes the seal from the events it covers and the seals before it and checks its signature. Returns seal, valid and failures. Needs auditor, security_officer or tenant_admin. Answers 404 not_found for an unknown seal. The verification is recorded in the access log.

Route: /v1/evidence/seals/{seal_id}/verify (GET).

Name	Type	Default	Required	Description
seal_id	str		yes	Identifier (UUID) of the seal.

Returns: Any. Decoded JSON answer of the operation "Verify an audit seal".

Raises: the typed errors of the transport (Errors).