Appearance
Audit Log
Almost every resource in TiruPay keeps a full change history: every create, update, and delete is recorded as its own version, in the order it happened. The Audit Log API lets you list which resources have a history, browse the current state of every entity of one kind, and drill into one entity's full version-by-version trail with a diff between each version.
Core concept
Log tables
Each loggable resource (e.g. Order, Customer, Coupon) has a corresponding log table, identified by a key like order_log. GET /audit-logs/tables lists every log table that exists, along with the columns it mirrors from the source resource - this is how you discover which log_table keys are valid and what each one's fields mean, without hardcoding them.
Entities and versions
Within one log table, rows are grouped by the entity they belong to (its source_id, usually the resource's own id). Each entity has one or more versions - one per create/update/delete - and exactly one log_status:
| Status | Meaning |
|---|---|
CREATED | The entity's first version |
UPDATED | A later version, some field(s) changed |
DELETED | The entity's terminal version - it no longer exists live |
GET /audit-logs/{log_table} lists one row per entity (its latest version), while GET /audit-logs/{log_table}/{source_id} returns one entity's full version history, newest first, each version annotated with exactly which fields changed since the previous one.
Reference
Log table info
Returned by GET /audit-logs/tables.
| Field | Type | Description |
|---|---|---|
key | string | The log table's identifier, used as log_table in the other endpoints (e.g. order_log) |
label | string | Human-readable name of the underlying resource (e.g. Order) |
columns | array | The columns mirrored from the source resource - see below |
Each entry in columns:
| Field | Type | Description |
|---|---|---|
name | string | The column name - the key it appears under in values/changes |
label | string | Human-readable column name |
type | string | A render hint: string, number, boolean, date, datetime, json, or reference |
target_table | string | null | For a reference column, the log table its value points at (e.g. customer_log) - look the value up via labels rather than showing it raw |
Entity (list view)
Returned by GET /audit-logs/{log_table}, one per matching entity.
| Field | Type | Description |
|---|---|---|
source_id | string | The entity's own id |
display_name | string | A human-readable name for the entity, or its source_id if the resource has nothing to name it by |
log_status | string | CREATED / UPDATED / DELETED - status of the latest version |
logged_at | datetime | When the latest version was written |
valid_to | datetime | null | When the latest version stopped being current - only set once a newer version exists; always set on a DELETED entity |
version_count | number | Total number of versions this entity has |
changed_by | string | Who made the latest version - a display name, or "System" for a background/unauthenticated change |
values | object | The mirrored columns' values at the latest version |
labels | object | Display names for this version's reference-typed columns, keyed by column name |
Version (history view)
Returned by GET /audit-logs/{log_table}/{source_id}, one per version, newest first.
| Field | Type | Description |
|---|---|---|
logged_at | datetime | When this version was written |
valid_to | datetime | null | When it stopped being current |
log_status | string | CREATED / UPDATED / DELETED |
values | object | Every mirrored column's value at this version |
changes | array | Fields that differ from the previous version - see below. Empty for the entity's first version |
changed_by | string | Who wrote this version |
labels | object | Display names for this version's reference-typed columns |
Each entry in changes:
| Field | Type | Description |
|---|---|---|
field | string | The column name |
old | any | Its value in the previous version |
new | any | Its value in this version |
old_label / new_label | string | null | Display name for old/new, when field is a reference column that resolved |
Endpoints
List log tables
GET /audit-logs/tables
Not scoped to a service - this describes the schema, not any service's data.
json
[
{
"key": "order_log",
"label": "Order",
"columns": [
{"name": "order_number", "label": "Order Number", "type": "string", "target_table": null},
{"name": "status", "label": "Status", "type": "string", "target_table": null},
{"name": "customer_id", "label": "Customer", "type": "reference", "target_table": "customer_log"}
]
}
]List entities
GET /audit-logs/{log_table}?service_id={id}
One row per entity, its latest version, newest change first. Deleted entities are included - see Behavior notes.
Query parameters:
| Parameter | Description |
|---|---|
service_id | Required. The service whose entities to list |
status | Optional, repeatable. Keep only entities whose latest version has one of these log_status values |
changed_from / changed_to | Optional. Keep only entities last changed within this range |
source_id | Optional. A single entity's id, exact match |
limit / offset | Pagination, default limit=20 |
json
{
"count": 1,
"items": [
{
"source_id": "ord_123",
"display_name": "ORD-2026-1",
"log_status": "UPDATED",
"logged_at": "2026-03-01T10:00:00Z",
"valid_to": null,
"version_count": 3,
"changed_by": "Ada Lovelace",
"values": {"order_number": "ORD-2026-1", "status": "PAID"},
"labels": {}
}
]
}Get one entity's history
GET /audit-logs/{log_table}/{source_id}?service_id={id}
Query parameters:
| Parameter | Description |
|---|---|
service_id | Required. The entity must belong to this service |
limit / offset | Pagination over versions, newest first, default limit=50 |
json
{
"source_id": "ord_123",
"version_count": 2,
"versions": [
{
"logged_at": "2026-03-01T10:00:00Z",
"valid_to": null,
"log_status": "UPDATED",
"values": {"order_number": "ORD-2026-1", "status": "PAID"},
"changes": [
{"field": "status", "old": "OPEN", "new": "PAID"}
],
"changed_by": "Ada Lovelace",
"labels": {}
},
{
"logged_at": "2026-02-15T09:00:00Z",
"valid_to": "2026-03-01T10:00:00Z",
"log_status": "CREATED",
"values": {"order_number": "ORD-2026-1", "status": "OPEN"},
"changes": [],
"changed_by": "System",
"labels": {}
}
]
}Behavior notes
- Deleted entities are still returned. An entity's terminal version is
DELETED, and the list endpoint returns each entity's latest version regardless of status - a deleted entity does not disappear from the audit trail, it just showslog_status: "DELETED". - Not every resource has a history. Some resources are themselves already immutable (an email send, a payment transaction) - for those, every "version" is just its own
CREATEDentry, withversion_countalways1. changed_byis not always a real user. A change made by a background job or an unauthenticated process is attributed to"System".- A resource's own field additions appear automatically. If a resource gains a new field, it shows up in
columns/valueswithout any change on your end - there's nothing to opt into.
Relationships
- Services - every audit log request is scoped to one service; entities from other services never appear.
- User Roles & Permissions - which services you may query the audit log for follows the same service assignment as any other endpoint.