enterprise_ai.audit
Source: sdks/python/src/enterprise_ai/audit/__init__.py. Back to the Python SDK reference index.
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 AuditClient
/v1/audit.
Resource
AuditClient.correlations
correlations(trace_id: str | None = None, run_id: str | None = None) -> Any
Correlate events by trace, run or session. With trace_id, run_id or session_id (the first given wins), returns everything that shares that key: audit_events, LLM usage_events, runs, telemetry spans, multimodal_jobs (up to 1000 of each, 200 for runs and jobs), the trace_ids met and counts.
Route: /v1/audit/correlations (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
trace_id | str | None | None | no | W3C trace id (32 hexadecimal characters) to correlate. |
run_id | str | None | None | no | Agent run identifier to correlate. |
Returns: Any. Decoded JSON answer of the operation "Correlate events by trace, run or session".
Raises: the typed errors of the transport (Errors).
AuditClient.events
events(actor: str | None = None, action: str | None = None, resource: str | None = None, since: str | None = None, until: str | None = None, **page: Any) -> Any
Search the audit events. Searches the audit events of the tenant, newest first (highest sequence first), paginated. All filters combine. Needs auditor, security_officer or tenant_admin. The search itself is recorded in the evidence access log (who, which query, how many results).
Route: /v1/audit/events (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
actor | str | None | None | no | Only the events of this actor id, for example a user subject or apikey:<id>. |
action | str | None | None | no | Only this action, for example api_key.create. A final * matches a prefix: approval.*. |
resource | str | None | None | no | Only this resource: <type> or <type>:<id>, for example project:42. |
since | str | None | None | no | Only the events from this time on, ISO 8601 (sent as from). |
until | str | None | None | no | End of the period (ISO 8601), sent as the to filter. |
**page | Any | no | Pagination options passed to the listing: limit (maximum number of items per page) and cursor (the next_cursor of the previous page). Iterating the returned page follows every cursor. |
Returns: Any. Decoded JSON answer of the operation "Search the audit events".
Raises: the typed errors of the transport (Errors).
AuditClient.export
export(since: str | None = None, until: str | None = None, retention_days: int | None = None) -> Any
Export the audit trail. Writes the events of the period (bounds included) to write once storage, as NDJSON or CSV, with a manifest. Needs auditor, security_officer or tenant_admin.
Route: /v1/audit/export (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
since | str | None | None | no | Start of the exported period, ISO 8601 (sent as from). |
until | str | None | None | no | End of the exported period (ISO 8601), sent as to. |
retention_days | int | None | None | no | Retention of the WORM export in days. |
Returns: Any. Decoded JSON answer of the operation "Export the audit trail".
Raises: the typed errors of the transport (Errors).
AuditClient.get
get(event_id: str) -> Any
Get an audit event. Returns one audit event with its sequence, hashes, actor, resource, decision and evidence. Needs auditor, security_officer or tenant_admin. The read is recorded in the evidence access log. Answers 404 not_found.
Route: /v1/audit/events/{event_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
event_id | str | yes | Identifier (UUID) of the audit event. |
Returns: Any. Decoded JSON answer of the operation "Get an audit event".
Raises: the typed errors of the transport (Errors).
AuditClient.query
query(**filters: Any) -> Any
Search the audit events. Searches the audit events of the tenant, newest first (highest sequence first), paginated. All filters combine. Needs auditor, security_officer or tenant_admin. The search itself is recorded in the evidence access log (who, which query, how many results).
Route: /v1/audit/events (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
**filters | Any | no | Filters and pagination options of events: actor, action, resource, since, until, limit, cursor. |
Returns: Any. Decoded JSON answer of the operation "Search the audit events".
Raises: the typed errors of the transport (Errors).
AuditClient.record
record(action: str, resource_type: str, resource_id: str, outcome: str | None = None, details: dict[str, Any] | None = None, resource_name: str | None = None, classification: str | None = None, trace_id: str | None = None, event_time: str | None = None) -> Any
Record an application audit event. Appends an application event to the tenant hash chain. The actor comes from the authentication; the sequence, the hashes and occurred_at from the server; the client details are kept under evidence.details.attributes, next to stream: sdk. The event is sealed and exported to the outbox and the SIEM like the platform events.
Route: /v1/audit/events (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
action | str | yes | Action name in the app. namespace, lowercase, at most 128 characters, for example app.invoice.approved. | |
resource_type | str | yes | Type of the resource the event is about (resource.type), for example invoice. | |
resource_id | str | yes | Identifier of the resource the event is about (resource.id). | |
outcome | str | None | None | no | success (default), failure or error. |
details | dict[str, Any] | None | None | no | Free attributes of the event, at most 16384 bytes once serialized. |
resource_name | str | None | None | no | Readable name of the resource (resource.name), optional. |
classification | str | None | None | no | Data classification of the event: public, internal, confidential, restricted or secret. |
trace_id | str | None | None | no | W3C trace id, 32 lowercase hexadecimal characters, to correlate the event with a trace. |
event_time | str | None | None | no | When the action happened on the client clock (ISO 8601), at most the allowed clock skew ahead of the server. Default: the server time. |
Returns: Any. Decoded JSON answer of the operation "Record an application audit event".
Raises: the typed errors of the transport (Errors).
AuditClient.verify
verify(**params: Any) -> Any
Verify the audit chain. Recomputes the hash chain of the tenant from the first event and returns tenant_id, valid, count, last_hash, broken_at, reason and verified_at. When the chain is broken, broken_at is the sequence of the first faulty event and reason says why: sequence gap, prev_hash mismatch or hash mismatch. Needs auditor, security_officer or tenant_admin. The verification is recorded in the evidence access log.
Route: /v1/audit/verify (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
**params | Any | no | Extra fields merged into the request. |
Returns: Any. Decoded JSON answer of the operation "Verify the audit chain".
Raises: the typed errors of the transport (Errors).
AuditClient.verify_evidence
verify_evidence() -> 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).
Functions
confirm_recorded
confirm_recorded(answer: Any) -> Any
Return an application audit event only when the server reports its event_id and chain hash.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
answer | Any | yes | Answer of POST /v1/audit/events to check. |
Returns: Any. The same answer, unchanged; otherwise audit_unconfirmed is raised.
Raises: EaiError.
canonical
canonical(event: dict[str, Any]) -> str
Canonical JSON of an event without its hash field.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
event | dict[str, Any] | yes | Audit event as a dict; its hash key is left out. |
Returns: str. JSON text with sorted keys and no spaces, the input of the chain hash.
chain_hash
chain_hash(prev_hash: str, event: dict[str, Any]) -> str
Hash of an event in the audit chain: sha256(prev_hash + canonical(event)) in hexadecimal.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
prev_hash | str | yes | Hash of the previous event of the chain (empty string for the first one). | |
event | dict[str, Any] | yes | Audit event to hash; its hash key is ignored. |
Returns: str. SHA-256 digest in hexadecimal.
verify_chain
verify_chain(events: list[dict[str, Any]], prev_key: str = 'prev_hash') -> dict[str, Any]
Return {valid, checked, broken_at} for a locally exported chain.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
events | list[dict[str, Any]] | yes | Exported audit events, in chain order. | |
prev_key | str | 'prev_hash' | no | Key of each event holding the previous hash (default prev_hash). |
Returns: dict[str, Any]. valid (bool), checked (number of events checked before the break) and broken_at (event_id or index of the first broken event, None when valid).