Audit Trail

Complete decision logging and retrieval — EU AI Act Article 14(4)(d) and Texas TRAIGA § 2056.103 compliance.

POST /log

Log an AI-mediated decision to the audit trail.

Request

{
  "user_id": "string",
  "ai_recommendation": "string",
  "user_decision": "string",
  "outcome": "string",
  "confidence": 0.0-1.0,
  "context": "string",
  "metadata": {}
}

Field	Type	Required	Description
user_id	string	✅	User who made decision
ai_recommendation	string	✅	What AI recommended
user_decision	string	✅	What user decided
outcome	string	❌	Decision outcome (if known)
confidence	number	❌	AI confidence (0-1)
context	string	❌	Additional context
metadata	object	❌	Custom metadata

Response

{
  "decision_id": "dec_abc123",
  "logged_at": "2025-12-25T10:00:00Z",
  "audit_trail_id": "audit_xyz789"
}

Example

curl -X POST https://api.athenatrust.ai/v1/log \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "doctor_456",
    "ai_recommendation": "Prescribe antibiotic",
    "user_decision": "Prescribe antibiotic",
    "outcome": "patient_recovered",
    "confidence": 0.92,
    "context": "Patient: 45F, symptoms: fever, cough",
    "metadata": {
      "patient_id": "patient_123",
      "department": "Emergency"
    }
  }'

---

GET /audit-trail

Retrieve audit trail with filtering and pagination.

Request

GET /audit-trail?user_id=user_123&page=1&limit=50&from=2025-12-01&to=2025-12-31

Param	Type	Required	Description
user_id	string	❌	Filter by user
page	number	❌	Page number (default: 1)
limit	number	❌	Results per page (default: 50)
from	string	❌	Start date (YYYY-MM-DD)
to	string	❌	End date (YYYY-MM-DD)
calibration	string	❌	Filter by calibration state

Response

{
  "total": 1247,
  "page": 1,
  "limit": 50,
  "decisions": [
    {
      "decision_id": "dec_abc123",
      "timestamp": "2025-12-25T10:00:00Z",
      "user_id": "user_123",
      "ai_recommendation": "Approve loan",
      "user_decision": "Approve loan",
      "outcome": "success",
      "calibration": "WELL_CALIBRATED",
      "ai_confidence": 0.92,
      "ai_correct": true,
      "user_correct": true,
      "context": "Loan application review",
      "metadata": {}
    }
  ]
}

Example

curl -X GET "https://api.athenatrust.ai/v1/audit-trail?user_id=user_123&page=1&limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Filtering Options

By Calibration State

GET /audit-trail?calibration=OVERTRUSTING

Returns only decisions where automation bias was detected.

By Date Range

GET /audit-trail?from=2025-01-01&to=2025-06-30

By Outcome

GET /audit-trail?outcome=success

Combined Filters

GET /audit-trail?user_id=user_123&calibration=OVERTRUSTING&from=2025-01-01&limit=100

---

SDK Examples

JavaScript

import { Athena } from '@athena-ai/sdk';

const athena = new Athena({ apiKey: 'YOUR_API_KEY' });

// Log a decision
const logged = await athena.audit.log({
  userId: 'doctor_456',
  aiRecommendation: 'Prescribe antibiotic',
  userDecision: 'Prescribe antibiotic',
  outcome: 'patient_recovered',
  confidence: 0.92
});

console.log(`Logged: ${logged.decisionId}`);

// Retrieve audit trail
const trail = await athena.audit.list({
  userId: 'doctor_456',
  limit: 50,
  startDate: '2025-01-01',
  endDate: '2025-12-31'
});

for (const decision of trail.decisions) {
  console.log(`${decision.timestamp}: ${decision.calibration}`);
}

Python

from athena import Athena

athena = Athena(api_key='YOUR_API_KEY')

# Log a decision
logged = athena.audit.log(
    user_id='doctor_456',
    ai_recommendation='Prescribe antibiotic',
    user_decision='Prescribe antibiotic',
    outcome='patient_recovered',
    confidence=0.92
)

print(f"Logged: {logged.decision_id}")

# Retrieve audit trail
trail = athena.audit.list(
    user_id='doctor_456',
    limit=50,
    start_date='2025-01-01',
    end_date='2025-12-31'
)

for decision in trail.decisions:
    print(f"{decision.timestamp}: {decision.calibration}")

---

Data Retention

Data Type	Retention	Notes
Decision logs	2 years	Regulatory requirement
Audit trail	2 years	Regulatory requirement
Webhook deliveries	90 days	Debug purposes

---

Next: Compliance Exports API