Audit Log API

Every API write in Cognethics is recorded in an immutable, SHA-256 hash-chained audit trail. Query it programmatically via REST or MCP to retrieve event history, verify chain integrity, and export audit records.

Two audit ledgers

1. Operational audit log

Records every CRUD operation: create, update, delete, export, access.

Use case: Compliance audits, DSAR requests, incident investigation, data lineage.

2. Governance audit ledger

Records policy decisions, agent delegations, escalations, and approval state.

Use case: Agent governance audits, delegation-chain verification, oversight trails.

Both ledgers are SHA-256 hash-chained and verifiable.

Query the operational audit log

List audit entries

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://gtm.cognethics.com/api/audit/?action=create&entity_type=invoice&date_from=2026-05-01&page=1"

Query parameters:

action — create, read, update, delete, export, access, system
category — auth, crud, access, export, system
entity_type — any entity (invoice, document, contact, etc.)
entity_id — specific record UUID
user_id — filter by user
date_from, date_to — ISO 8601 timestamp range
page, page_size — pagination

Response:

{
  "count": 42,
  "results": [
    {
      "id": "audit_550e8400e29b41d4a716446655440000",
      "sequence_number": 1024,
      "action": "create",
      "category": "crud",
      "entity_type": "invoice",
      "entity_id": "inv_550e8400e29b41d4a716446655440000",
      "user_id": "usr_550e8400e29b41d4a716446655440000",
      "changes": {
        "vendor_id": "vnd_550e8400e29b41d4a716446655440001",
        "amount_usd": "2500.00",
        "status": "pending"
      },
      "request_method": "POST",
      "request_path": "/api/v1/finance/invoices/",
      "response_status": 201,
      "ip_address": "203.0.113.42",
      "timestamp": "2026-05-21T15:30:00Z",
      "session_id": "sess_550e8400e29b41d4a716446655440000",
      "entry_hash": "4df9cb7f515bf398a2c7a4e3f1b2c9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2",
      "previous_hash": "d148f12ea2707b21c1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
    }
  ]
}

Fields:

sequence_number — monotonic per-tenant counter (1, 2, 3, ...)
entry_hash — SHA-256 of this entry plus previous_hash (immutable after sealing)
previous_hash — links to the prior entry (the chain)

Export as CSV

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://gtm.cognethics.com/api/audit/export/?action=update&entity_type=PaymentRecord&date_from=2026-05-14&date_to=2026-05-21" \
  > audit_export.csv

Returns CSV with every field. Up to 10,000 rows per export.

Query the governance audit ledger

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://gtm.cognethics.com/api/agents/governance-audit/?governed_agent=agt_550e8400&action=delegation"

Response:

{
  "count": 8,
  "results": [
    {
      "id": "gaent_550e8400e29b41d4a716446655440000",
      "sequence_number": 512,
      "action": "delegation_sent",
      "source_agent_id": "agt_550e8400e29b41d4a716446655440000",
      "target_agent_id": "agt_550e8400e29b41d4a716446655440001",
      "decision_outcome": "approved",
      "trace_id": "trace_550e8400e29b41d4a716446655440000",
      "span_id": "span_550e8400e29b41d4a716446655440000",
      "timestamp": "2026-05-21T15:30:00Z",
      "entry_hash": "abc123def456abc123def456abc123def456abc123def456abc123def456abc1",
      "previous_hash": "789123def456abc123def456abc123def456abc123def456abc123def456abc1"
    }
  ]
}

Verify hash-chain integrity

The chain can be verified at any time to prove no entry has been tampered with, deleted, or back-dated.

Verify the operational audit log

curl -X POST -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://gtm.cognethics.com/api/audit/verify-chain/" \
  -H "Content-Type: application/json" \
  -d '{}'

Request body (all fields optional):

{
  "organization_id": "org_550e8400e29b41d4a716446655440000",
  "sequence_from": 1,
  "sequence_to": 100000
}

Response (valid chain):

{
  "is_valid": true,
  "total_entries": 218010,
  "first_invalid_entry_id": null,
  "error_details": null,
  "sequence_from": 1,
  "sequence_to": 218010,
  "tenant_id": "8a2e8037-96f9-47d1-aef3-3f9c42d48fd0",
  "verified_at": "2026-05-21T20:12:25.165646+00:00"
}

Response (tampered chain):

{
  "is_valid": false,
  "total_entries": 218010,
  "first_invalid_entry_id": "0e97604e-3887-46c3-a3d6-6b3236d59968",
  "error_details": "Entry 218009 entry_hash mismatch (possible tampering). Expected: 4df9cb7f..., Got: d148f12e...",
  "sequence_from": 1,
  "sequence_to": 218010,
  "tenant_id": "8a2e8037-96f9-47d1-aef3-3f9c42d48fd0",
  "verified_at": "2026-05-21T20:12:25Z"
}

If the chain is broken, the API returns the first offending entry ID — letting you narrow down the corruption window.

Verify a specific sequence range

Useful when the chain is long. Anchor evidence to a previously-signed sequence number:

curl -X POST -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://gtm.cognethics.com/api/audit/verify-chain/" \
  -d '{"sequence_from": 1, "sequence_to": 100000}'

Immutability guarantees

The audit log is protected by three independent layers:

Application-level guard — ImmutableAuditModel.save() rejects any UPDATE except the one-time entry-hash seal
Database-level trigger — a PostgreSQL BEFORE UPDATE OR DELETE trigger blocks all mutations and deletions
Hash-chain detection — post-hoc verification identifies tampering even if layers 1 and 2 are bypassed

Compliance notes

SOC 2 / HIPAA — Immutability plus per-tenant hash-chain integrity meet audit-logging requirements (CC6.1, HIPAA 45 CFR 164.312(b))
Self-audit — Every data export is logged, creating a verifiable record of "who accessed what"
Retention — Audit entries are retained per organizational policy

Use cases

DSAR (Data Subject Access Request)

Find all operations on a specific customer's record:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://gtm.cognethics.com/api/audit/?entity_type=Customer&entity_id=cust_550e8400&date_from=2025-01-01"

Incident investigation

Find all changes to a sensitive field in the last 7 days:

curl -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://gtm.cognethics.com/api/audit/?action=update&entity_type=PaymentRecord&date_from=2026-05-14" \
  | jq '.results[] | select(.changes.account_number != null)'

Chain verification (compliance review)

Run a periodic chain check:

curl -X POST -H "Authorization: Bearer YOUR_API_TOKEN" \
  "https://gtm.cognethics.com/api/audit/verify-chain/" \
  -d '{}'

API reference

List audit log entries

GET /api/audit/

Query parameters:

action — filter by action
category — filter by category
entity_type — filter by entity
entity_id — filter by entity ID
user_id — filter by user
date_from, date_to — ISO 8601 timestamp range
page, page_size — pagination

Response: 200 OK with paginated results.

Export audit log

GET /api/audit/export/

Same query parameters as list. Returns CSV.

Verify hash chain

POST /api/audit/verify-chain/

Request body:

{
  "organization_id": "org_id (optional)",
  "sequence_from": 1,
  "sequence_to": 999999
}

Response: 200 OK with is_valid boolean plus error details if tampered.

List governance audit entries

GET /api/agents/governance-audit/

Query parameters:

governed_agent — filter by agent
action — filter by action (delegation_sent, escalation_requested, etc.)
date_from, date_to — timestamp range

Response: 200 OK with paginated results.

Verify governance chain

GET /api/agents/governance-audit/verify_chain/?governed_agent=<id>

Response: 200 OK with chain-validity status.

Permissions

The audit log is accessible to users with:

admin.view_audit_logs — system administrators
compliance.view_audit_logs — compliance officers

Contact your organization administrator to assign the Compliance Officer role if needed.

Next Steps

Export audit history for compliance reviews
Verify chain integrity to prove no tampering
Correlate with governance decisions using trace_id from agent execution logs
Wire alerts on specific entity types or users via webhooks

Questions? Reach our Security & Compliance team through the contact form.