Trust Calibration

Real-time trust calibration analysis — the core of EU AI Act Article 14 compliance.

POST /calibrate

Analyze a single decision for trust calibration patterns.

Request

{
  "user_id": "string",
  "ai_recommendation": "string",
  "user_decision": "string",
  "context": "string",
  "confidence": 0.0-1.0,
  "timestamp": "ISO8601"
}

Field	Type	Required	Description
user_id	string	✅	Unique user identifier
ai_recommendation	string	✅	What the AI recommended
user_decision	string	✅	What the user decided
context	string	❌	Additional context
confidence	number	❌	AI confidence (0-1)
timestamp	string	❌	ISO8601 timestamp

Response

{
  "calibration_category": "WELL_CALIBRATED",
  "trust_score": 0.75,
  "ai_correct": true,
  "user_correct": true,
  "pattern_detected": "none",
  "recommendation": "Continue monitoring.",
  "regulation_mapping": {
    "eu_ai_act": "Article 14(4)(b)",
    "texas_traiga": "§ 2056.002",
    "colorado": "§ 6-1-1303",
    "fda": "Section IV.A"
  }
}

Calibration Categories

Category	Description
WELL_CALIBRATED	Appropriate trust level
OVERTRUSTING	Automation bias detected
UNDERTRUSTING	Algorithm aversion detected
INCONSISTENT	Erratic trust patterns

Example

curl -X POST https://api.athenatrust.ai/v1/calibrate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "doctor_456",
    "ai_recommendation": "Prescribe antibiotic",
    "user_decision": "Prescribe antibiotic",
    "context": "Patient symptoms: fever, cough",
    "confidence": 0.92
  }'

---

POST /trust-score

Calculate aggregate trust score for a user over a time period.

Request

{
  "user_id": "string",
  "time_period": "7d|30d|90d"
}

Field	Type	Required	Description
user_id	string	✅	Unique user identifier
time_period	string	❌	Time window (default: 30d)

Response

{
  "user_id": "doctor_456",
  "trust_score": 0.75,
  "calibration": "WELL_CALIBRATED",
  "total_decisions": 142,
  "override_rate": 0.28,
  "ai_accuracy": 0.82,
  "user_accuracy": 0.79,
  "automation_bias_incidents": 3,
  "algorithm_aversion_incidents": 8
}

Example

curl -X POST https://api.athenatrust.ai/v1/trust-score \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "doctor_456",
    "time_period": "30d"
  }'

---

GET /trust-score/trend

Retrieve historical trust score trend for trend analysis (Colorado AI Act § 6-1-1303).

Request

GET /trust-score/trend?user_id=user_123&days=30

Param	Type	Required	Description
user_id	string	✅	Unique user identifier
days	number	❌	Number of days (default: 30)

Response

{
  "user_id": "user_123",
  "time_period": "30d",
  "data_points": [
    {
      "date": "2025-12-01",
      "trust_score": 0.72,
      "calibration": "WELL_CALIBRATED"
    },
    {
      "date": "2025-12-02",
      "trust_score": 0.74,
      "calibration": "WELL_CALIBRATED"
    }
  ]
}

Example

curl -X GET "https://api.athenatrust.ai/v1/trust-score/trend?user_id=user_123&days=30" \
  -H "Authorization: Bearer YOUR_API_KEY"

---

SDK Examples

JavaScript

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

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

// Analyze calibration
const result = await athena.calibrate.analyze({
  userId: 'doctor_456',
  aiRecommendation: 'Prescribe antibiotic',
  userDecision: 'Prescribe antibiotic',
  confidence: 0.92
});

// Get trust score
const score = await athena.trustScore.calculate({
  userId: 'doctor_456',
  timePeriod: '30d'
});

// Get trend
const trend = await athena.trustScore.trend({
  userId: 'doctor_456',
  days: 30
});

Python

from athena import Athena

athena = Athena(api_key='YOUR_API_KEY')

# Analyze calibration
result = athena.calibrate.analyze(
    user_id='doctor_456',
    ai_recommendation='Prescribe antibiotic',
    user_decision='Prescribe antibiotic',
    confidence=0.92
)

# Get trust score
score = athena.trust_score.calculate(
    user_id='doctor_456',
    time_period='30d'
)

# Get trend
trend = athena.trust_score.trend(
    user_id='doctor_456',
    days=30
)

---

Next: Bias Detection API