/ Docs
API

Audit events

Botyard REST API endpoints for audit events.

2 endpoints in this group. Every request authenticates with an API key; see the API reference for the other groups.

Decide Approval

Approve or deny a bot's request to spend the organization's money. Approving issues a short-lived, single-use grant bound to the digest of the payload on the card; the bot is woken with that payload handed back to it and retries the same call, which now passes the gate. The wake echoes the payload rather than relying on the bot to remember it, because the default approval lifetime is seven days and the asking session is usually long gone by the time a human answers. Denying issues nothing and tells the bot why. Three refusals sit in front of the transition, in this order: 1. **Authority.** The decider must hold the permission the kind's own action requires, over and above the ``conversation:approval.update`` floor the route already gated on. A member who could not create the MCP server themselves cannot authorize a bot to create it for them — that is the whole sentence the actor rule is built around. 2. **Hard cap.** A grant cannot buy past a plan limit, so approving one that the cap already blocks would mint authority for a call that is going to be refused anyway. Refused as ``plan_limit_reached``, the same code the gate would raise. 3. **Payment method.** On a card-free org a chargeable approval cannot be granted, so the request is left ``pending`` and an activation intent is returned for the client's existing checkout flow. See :class:`~botyard_api.models.approvals.ApprovalActivationIntent` for why there is no "approved, awaiting payment" state. Denials skip 2 and 3 entirely: refusing to spend money is always available, whatever the plan says. **Payload-dependent authority (#3157).** A kind may add an ``approver_shortfall`` hook on top of the static permission; an approve is refused while it names anything. For ``bot_tool.assign`` that is the union of the listed tools' requirements plus their visibility to the approver. **Kinds performed on approval.** For a ``performed_on_approval`` kind the action happens here, in the decision's transaction, and its grant is spent by id before commit — the bot is told it is done rather than to retry. A failure anywhere rolls the decision back with it, so the request stays pending and nothing is half-applied.

List Audit Events

List customer-visible audit events for an organization. Equivalent to ``POST /audit-events/search`` with an empty body. Prefer the search endpoint for new callers — it accepts the shared JSON filter DSL and is the canonical list shape going forward.