Audit tools | Pepper Agent API

These read tools use the same event fields and permissions as Settings > Audit log. AI is optional. These tools only read. Exporting the audit trail, making a personal-data report, erasing personal fields, changing retention and removing expired events need your approval of each step in Pepper; see Approve sensitive steps.

List and open events

Tool	Inputs	Result
`audit.list`	Optional page, page size (25, 50 or 100), event, actor, from/to date, record type and record ID	Permitted events and pagination
`audit.get`	Event `id`	One permitted event, its covered facts and stored hash
`audit.integrity`	None	Last verification result, its date and the number of events waiting for a seal
`audit.retention`	None	How many days each class of events is kept, and when old events are next removed
`audit.verify`	None	Seals waiting events and verifies the chain now, as Check history does, then returns the result. It repairs and removes nothing

MCP uses underscores in tool names, for example audit_list. HTTP uses GET /api/v1/audit/events, GET /api/v1/audit/events/{id}, GET /api/v1/audit/integrity, GET /api/v1/audit/retention and GET /api/v1/audit/verify.

The connection needs the Settings read grant. Its person also needs audit_log.view or audit_log.view_own to list or open events. Own-history access returns only that person's permitted events. Integrity, retention and verification need audit_log.view. Current record access applies in every case. An owner cannot use this grant to see another person's private board.

Results include the event, actor, source record, time and covered business facts. A list-read event shows a count instead of sending every identifier to the client. Tools return no raw metadata, IP address, browser details or credentials. Losing record access removes the event, including a whole sampled batch if any referenced record is no longer accessible.

Repeated files.list folder pages can reuse a durable access sample within the same UTC clock minute. Reuse requires the same person, connection, folder, purpose, returned identifiers and versions. Sort order alone does not change the sample. Another connection, changed files or versions, or the next UTC minute requires new evidence. Search results retain ordinary per-page evidence.

Pepper rechecks current access before every reuse. Restored access can reuse an unchanged sample within its minute. The event time and request identifier belong to the first recorded disclosure. They do not identify every later request. Every disclosed file identifier remains stored; tools continue to return a count. Rollback, cache loss or worker restart cannot replace the required durable evidence. Concurrent requests may leave duplicates. See Folder access samples.

Customer account data requests

Use the explicit customer_account subject for an account report or erasure review. A Customer subject does not automatically select every linked account.

The delegate needs current account management and audit access. Only the owner can approve erasure, through the existing audit_subject_erase approval workflow.

Review the exact current report before preparing erasure. Changed records invalidate the reviewed result. Erasure permanently disables that account and blocks registration with the retained email reference.

Issued originals, financial records and purchase ownership remain. The report does not grant access to other purchases or private staff records.

See account erasure and sensitive-step approvals.

Read the integrity result honestly

A stored hash is not a fresh verification. Pending means new events need a seal. Stale means the last check is more than a day old. A client must keep those states visible instead of saying the entire log has been verified.

Open Audit log to check the history. The same guide explains hash coverage, partial signed exports, the limits of a local chain and personal-field erasure.

For local installation checks, use installation.health.