Developer Docs

Guardian Metrics API

Ingest drift and fairness metrics from your AI systems. Guardian derives compliance status, triggers alerts, and maintains your EU AI Act audit trail automatically.

Authentication

All write endpoints require an API key with WRITE scope. Pass it as a Bearer token in the Authorization header.

Authorization: Bearer grd_a1b2c3d4e5f6...

API keys are generated in the Guardian dashboard under Settings → API Keys. The raw key is shown only once at creation. Keys are stored as SHA-256 hashes.

POST /api/v1/metrics

Ingest a single metric snapshot for an AI model. Guardian will derive the compliance status (GREEN / AMBER / RED), create alerts if thresholds are breached, and update the audit trail.

Request

POST /api/v1/metrics
Content-Type: application/json
Authorization: Bearer grd_your_api_key

{
  "modelId": "clx1abc2d0001...",
  "driftScore": 15.2,
  "fairnessScore": 92.1,
  "sampleSize": 5000,
  "capturedAt": "2025-01-15T10:30:00Z",
  "notes": "Weekly scheduled run"
}

Field	Type	Required	Description
modelId	string	Yes	The Guardian model ID
driftScore	number	Yes	0 = no drift, 100 = max drift. >50 AMBER, >70 RED.
fairnessScore	number	Yes	0 = unfair, 100 = perfectly fair. <90 AMBER, <80 RED.
sampleSize	integer	Yes	Number of samples in this evaluation
capturedAt	ISO 8601	No	Defaults to server time if omitted
notes	string	No	Free-text annotation for this snapshot

Response (200)

{
  "success": true,
  "snapshotId": "clx1xyz...",
  "complianceStatus": "GREEN"
}

GET /api/v1/metrics

Returns simulated metrics for testing. No authentication required. Useful for verifying your integration before switching to real data.

GET /api/v1/metrics?modelId=test-model&seed=42

The seed parameter produces deterministic results for reproducible testing.

POST /api/v1/metrics/batch

Ingest up to 100 snapshots in a single request. Same validation and compliance logic as the single endpoint.

POST /api/v1/metrics/batch
Content-Type: application/json
Authorization: Bearer grd_your_api_key

{
  "snapshots": [
    { "modelId": "...", "driftScore": 12, "fairnessScore": 95, "sampleSize": 3000 },
    { "modelId": "...", "driftScore": 55, "fairnessScore": 88, "sampleSize": 2500 }
  ]
}

GET /api/v1/thresholds

Returns the compliance thresholds applied to your models. Custom thresholds (configured via Risk Metric Links) override global defaults.

GET /api/v1/thresholds?modelId=clx1abc...

{
  "modelId": "clx1abc...",
  "source": "global_defaults",
  "thresholds": {
    "drift":           { "amber": 50, "red": 70 },
    "fairness":        { "amber": 90, "red": 80 },
    "psi":             { "amber": 0.10, "red": 0.20 },
    "disparateImpact": { "amber": 0.80, "red": 0.60 }
  }
}

Rate Limiting

Endpoint	Limit	Window
POST /api/v1/metrics	60 requests	1 minute
POST /api/v1/metrics/batch	10 requests	1 minute

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header (seconds).

Error Codes

Status	Meaning
400	Invalid payload or malformed JSON
401	Missing, empty, or invalid API key
403	API key has READ scope (WRITE required)
404	Model not found or belongs to another org
429	Rate limit exceeded
500	Internal server error

Ready to integrate?

Create your account and generate an API key to start sending metrics.

Get your API key