Skip to content

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:

StatusMeaning
CREATEDThe entity's first version
UPDATEDA later version, some field(s) changed
DELETEDThe 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.

FieldTypeDescription
keystringThe log table's identifier, used as log_table in the other endpoints (e.g. order_log)
labelstringHuman-readable name of the underlying resource (e.g. Order)
columnsarrayThe columns mirrored from the source resource - see below

Each entry in columns:

FieldTypeDescription
namestringThe column name - the key it appears under in values/changes
labelstringHuman-readable column name
typestringA render hint: string, number, boolean, date, datetime, json, or reference
target_tablestring | nullFor 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.

FieldTypeDescription
source_idstringThe entity's own id
display_namestringA human-readable name for the entity, or its source_id if the resource has nothing to name it by
log_statusstringCREATED / UPDATED / DELETED - status of the latest version
logged_atdatetimeWhen the latest version was written
valid_todatetime | nullWhen the latest version stopped being current - only set once a newer version exists; always set on a DELETED entity
version_countnumberTotal number of versions this entity has
changed_bystringWho made the latest version - a display name, or "System" for a background/unauthenticated change
valuesobjectThe mirrored columns' values at the latest version
labelsobjectDisplay 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.

FieldTypeDescription
logged_atdatetimeWhen this version was written
valid_todatetime | nullWhen it stopped being current
log_statusstringCREATED / UPDATED / DELETED
valuesobjectEvery mirrored column's value at this version
changesarrayFields that differ from the previous version - see below. Empty for the entity's first version
changed_bystringWho wrote this version
labelsobjectDisplay names for this version's reference-typed columns

Each entry in changes:

FieldTypeDescription
fieldstringThe column name
oldanyIts value in the previous version
newanyIts value in this version
old_label / new_labelstring | nullDisplay 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:

ParameterDescription
service_idRequired. The service whose entities to list
statusOptional, repeatable. Keep only entities whose latest version has one of these log_status values
changed_from / changed_toOptional. Keep only entities last changed within this range
source_idOptional. A single entity's id, exact match
limit / offsetPagination, 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:

ParameterDescription
service_idRequired. The entity must belong to this service
limit / offsetPagination 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 shows log_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 CREATED entry, with version_count always 1.
  • changed_by is 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/values without 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.