Logging events

One endpoint does the logging: POST /api/v1/events. This page explains each field and the conventions that make the data useful. The formal contract lives in the Swagger reference.

Required fields

`event_type`	`error` or `success`
`error_class`	Required for errors: `technical` (infrastructure faults: bad gateways, timeouts, connection failures, usually retryable, routed to IT) or `business` (data problems: malformed input, missing fields, needs human review, surfaced to the business/Salesforce).
`integration`	A stable, lowercase name for the process or flow, e.g. `salesforce-nebulaw-sync`. Pick one name per flow and stick to it; reports group by this.
`message`	One human-readable sentence (max 500 chars). Someone reading only this line should understand what went wrong.
`occurred_at`	When it happened in YOUR system, ISO 8601 with timezone, e.g. `2026-08-13T06:15:00Z`. We convert and store UTC.

Optional but valuable

`severity`	`info`, `warning`, `error` or `critical`. Defaults to `error` for errors and `info` for successes. Alerting keys off this: reserve `critical` for "wake someone up".
`code`	A short machine code, e.g. `HTTP_502`, `MISSING_FIELD`. The system groups recurrences by app + integration + code (first seen, last seen, occurrence counts), so a consistent code makes a repeating fault show as one story instead of scattered noise. The code `HEARTBEAT_MISSED` is reserved for the heartbeat monitor.
`detail`	The long version: stack trace, response body, anything a developer will thank you for.
`payload`	A JSON snapshot of the offending data (object or string). Invaluable for business errors someone must fix by hand.
`source_ref`	External record reference, e.g. `Salesforce:006Ab00001XyZ` or an invoice number.
`correlation_id`	Your run or request id. All events sharing it can be found together with one filter.
`retryable`	`true` if the same call could plausibly succeed later.

Do not log secrets. Keep passwords, API keys and tokens out of message, detail and payload. Personal client data belongs there only when needed to fix the problem.

Reading and updating events

Any app key can also query, which is how Salesforce or a dashboard can pull business errors:

# List: filter by anything, page through results
GET /api/v1/events?app=toca-ai&event_type=error&status=open&per_page=50

# One event
GET /api/v1/events/123

# Update the workflow status (open | in_progress | resolved | ignored)
PATCH /api/v1/events/123
{ "status": "resolved", "status_notes": "Re-ran after fix", "resolved_by": "jane.smith" }

Filters: app, event_type, error_class, severity, status, integration, correlation_id, from/to (ISO 8601 against occurred_at), plus page and per_page (max 200).

Next: Alerts and notifications