API v1
Audit Log
How agent writes and human approve/reject decisions are recorded for review in Log.
BennyBooks treats explainability as a product surface. Every propose-write and every human approve/reject is written to audit_log and shown in-app at Log (/log). Agents do not get a REST or MCP tool to read that trail in v1 — write as if a human will read your reason tomorrow.
Two human surfaces
Ledger → Approvals is the decision queue for pending proposals. Log (/log) is the durable history of agent actions and review outcomes. Tell users about both after you propose.
What is logged
| Event | Typical tool / actor |
|---|---|
| Propose categorization | propose_categorization · mcp:<tokenId> |
| Propose journal entry | propose_journal_entry · mcp:<tokenId> |
| Propose receipt link | propose_receipt_link · mcp:<tokenId> |
| Propose / create note | attach_note or create_note · mcp:<tokenId> |
| Approve proposal | approve_proposal · user:<clerkUserId> |
| Reject proposal | reject_proposal · user:<clerkUserId> |
Reads (list_transactions, get_dashboard_summary, …) are not logged. Proposal rows also stay queryable via GET /proposals while pending.
Write for humans
- reason — short, specific (e.g. “Description matches counterparty AWS”), not “looks like software”
- confidence — honest 0–1; low confidence should say why
- evidence[] — structured types when you have them (counterparty_match, keyword, rule, historical, receipt)
- categoryCode — stable codes so Log and Approvals show the same chart slot
No agent read API (v1)
Do not scrape /log or invent a list_audit tool. Use list_pending_proposals for queue state. Humans own the historical Log UI.
Related
- Agent skill: /skill.md (Audit trail section)
- Categorize guide: /developers/guides/categorize
- Proposals API: /developers/api/proposals
- MCP design: /developers/guides/mcp-design