External Bias Integration

Version: 1.1.0 Base URL: https://api.athenatrust.ai/v1

POST /model-fairness-signals

Ingest a fairness signal from an external bias detection tool.

Request

POST /api/v1/model-fairness-signals
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Body

Field	Type	Required	Description
externalToolId	string	Yes	Tool identifier: ibm_aif360, fairlearn, aws_clarify, google_vertex, custom
externalToolVersion	string	No	Version of the external tool
modelId	string	Yes	Your AI model identifier
modelVersion	string	No	Version of your model
metricName	string	Yes	Fairness metric name (see supported metrics)
metricValue	number	Yes	Metric value (0 to 1 normalized)
threshold	number	No	Acceptable threshold for this metric
passesThreshold	boolean	No	Whether metric passes the threshold
protectedAttribute	string	Yes	Protected attribute name (for example, gender)
privilegedGroup	string	No	Privileged group identifier
unprivilegedGroup	string	No	Unprivileged group identifier
sampleSize	integer	No	Number of samples analyzed
confidenceInterval	object	No	{ lower: number, upper: number }
rawPayload	object	Yes	Raw output from external tool
signalTimestamp	string	Yes	ISO 8601 timestamp when signal was generated

Supported Metric Names

Category	Metrics
Group Fairness	demographic_parity, equalized_odds, equal_opportunity, disparate_impact, statistical_parity_difference
Individual Fairness	consistency, flip_rate
Calibration	calibration_error, predictive_parity
Custom	custom

Example Request

{
  "externalToolId": "ibm_aif360",
  "externalToolVersion": "0.6.1",
  "modelId": "loan_approval_v3",
  "metricName": "demographic_parity",
  "metricValue": 0.42,
  "threshold": 0.45,
  "passesThreshold": true,
  "protectedAttribute": "gender",
  "privilegedGroup": "male",
  "unprivilegedGroup": "female",
  "sampleSize": 10000,
  "confidenceInterval": {
    "lower": 0.40,
    "upper": 0.44
  },
  "rawPayload": {
    "statistical_parity_difference": 0.15,
    "disparate_impact": 0.82
  },
  "signalTimestamp": "2025-12-27T10:30:00Z"
}

Response

{
  "signalId": "sig_abc123def456",
  "message": "Fairness signal ingested successfully"
}

Error Codes

Code	HTTP Status	Description
FAIRNESS_INVALID_SOURCE	400	Unknown external tool ID
FAIRNESS_INVALID_METRIC	400	Unsupported metric name
SIGNAL_IN_FUTURE	400	Timestamp is in the future
SIGNAL_TOO_OLD	400	Signal older than 90 days
FAIRNESS_RATE_LIMIT	429	Max 100 signals per hour

GET /model-fairness-signals

List ingested fairness signals with optional filters.

Request

GET /api/v1/model-fairness-signals
Authorization: Bearer YOUR_API_KEY

Query Parameters

Parameter	Type	Default	Description
modelId	string		Filter by model ID
externalToolId	string		Filter by external tool
protectedAttribute	string		Filter by protected attribute
passesThreshold	boolean		Filter by threshold status
startDate	string		ISO 8601 start date
endDate	string		ISO 8601 end date
page	integer	1	Page number
limit	integer	50	Results per page (max 100)
sortBy	string	signalTimestamp	Sort field
sortOrder	string	desc	asc or desc

Response

{
  "signals": [
    {
      "id": "sig_abc123",
      "customerId": "cust_xyz",
      "externalToolId": "ibm_aif360",
      "externalToolVersion": "0.6.1",
      "modelId": "loan_approval_v3",
      "metricName": "demographic_parity",
      "metricValue": 0.42,
      "threshold": 0.45,
      "passesThreshold": true,
      "protectedAttribute": "gender",
      "privilegedGroup": "male",
      "unprivilegedGroup": "female",
      "sampleSize": 10000,
      "signalTimestamp": "2025-12-27T10:30:00Z",
      "ingestedAt": "2025-12-27T10:30:05Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 50,
  "hasMore": false
}

GET /model-fairness-signals/:id

Get a single fairness signal by ID.

Response

Returns the full signal object as shown above.

GET /bias/amplification

List bias amplification alerts.

Query Parameters

Parameter	Type	Default	Description
status	string		open, acknowledged, resolved, false_positive
severity	string		low, medium, high, critical
protectedAttribute	string		Filter by attribute
startDate	string		ISO 8601 start date
endDate	string		ISO 8601 end date
page	integer	1	Page number
limit	integer	50	Results per page (max 100)

Response

{
  "alerts": [
    {
      "id": "alert_xyz789",
      "customerId": "cust_abc",
      "fairnessSignalId": "sig_abc123",
      "amplificationScore": 0.68,
      "amplificationType": "overtrust",
      "overtrustRate": 0.42,
      "undertrustRate": 0.08,
      "correlatedDecisions": 156,
      "protectedAttribute": "gender",
      "affectedSubgroup": "female",
      "severity": "high",
      "status": "open",
      "detectionMethod": "correlation",
      "confidenceScore": 0.85,
      "analysisWindowStart": "2025-12-20T00:00:00Z",
      "analysisWindowEnd": "2025-12-27T00:00:00Z",
      "createdAt": "2025-12-27T10:35:00Z",
      "updatedAt": "2025-12-27T10:35:00Z"
    }
  ],
  "total": 3,
  "page": 1,
  "limit": 50,
  "summary": {
    "by_severity": {
      "critical": 0,
      "high": 1,
      "medium": 2,
      "low": 0
    },
    "by_status": {
      "open": 3,
      "acknowledged": 0,
      "resolved": 0
    }
  }
}

GET /bias/amplification/:id

Get a single amplification alert by ID.

Response

Returns the full alert object with the related fairness signal:

{
  "id": "alert_xyz789",
  "amplificationScore": 0.68,
  "severity": "high",
  "status": "open",
  "fairnessSignal": {
    "id": "sig_abc123",
    "externalToolId": "ibm_aif360",
    "metricName": "demographic_parity",
    "metricValue": 0.42
  }
}

PATCH /bias/amplification/:id

Update an amplification alert status.

Request Body

Field	Type	Required	Description
status	string	Yes	open, acknowledged, resolved, false_positive
resolutionNotes	string	No	Notes about resolution
resolvedBy	string	No	User who resolved

Example Request

{
  "status": "resolved",
  "resolutionNotes": "Retrained model with bias mitigation",
  "resolvedBy": "[email protected]"
}

Response

{
  "id": "alert_xyz789",
  "status": "resolved",
  "resolvedAt": "2025-12-27T15:00:00Z",
  "message": "Alert status updated successfully"
}

POST /bias/amplification/analyze/:signalId

Trigger on demand amplification analysis for a specific fairness signal.

Response

{
  "signalId": "sig_abc123",
  "amplificationRisk": "high",
  "amplificationScore": 0.68,
  "alertCreated": true,
  "alertId": "alert_new123",
  "message": "Amplification analysis complete"
}

Rate Limits

Endpoint	Limit
POST /model-fairness-signals	100 per hour
GET endpoints	Standard rate limits apply
POST /bias/amplification/analyze	10 per minute

Next Steps

• Webhooks API

• Trust Calibration API