Bufdir Alignment Validator - API Contract

GET /api/v1/alignment-validations/api/v1/alignment-validations

List alignment validation results

Public

Response Example

{
  "data": [
    {
      "validation_id": "val_001",
      "peer_mentor_id": "usr_4f8a2c",
      "time_window": "quarterly",
      "aligned": true,
      "discrepancy_count": 0,
      "validated_at": "2026-03-26T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1
  }
}

GET /api/v1/alignment-validations/api/v1/alignment-validations/:validationId

Get a specific alignment validation result by ID

Public

Response Example

{
  "validation_id": "val_001",
  "peer_mentor_id": "usr_4f8a2c",
  "time_window": "quarterly",
  "aligned": true,
  "discrepancy_count": 0,
  "discrepancies": [],
  "validated_at": "2026-03-26T09:30:00Z"
}

POST /api/v1/alignment-validations/api/v1/alignment-validations

Validate alignment between a dashboard StatsSnapshot and an export snapshot for a peer mentor

Public

Request Example

{
  "peer_mentor_id": "usr_4f8a2c",
  "time_window": "quarterly",
  "stats_snapshot": {
    "total_activities": 47,
    "completed_activities": 42,
    "hours_logged": 128.5
  },
  "export_snapshot": {
    "total_activities": 47,
    "completed_activities": 42,
    "hours_logged": 128.5
  }
}

Response Example

{
  "validation_id": "val_002",
  "peer_mentor_id": "usr_4f8a2c",
  "aligned": true,
  "discrepancy_count": 0,
  "discrepancies": [],
  "validated_at": "2026-03-26T10:10:00Z"
}

PUT /api/v1/alignment-validations/api/v1/alignment-validations/:validationId

Re-run or annotate an existing validation record

Public

Request Example

{
  "notes": "Manually reviewed — discrepancy due to timezone offset in export",
  "override_aligned": true
}

Response Example

{
  "validation_id": "val_001",
  "peer_mentor_id": "usr_4f8a2c",
  "aligned": true,
  "notes": "Manually reviewed — discrepancy due to timezone offset in export",
  "updated_at": "2026-03-26T10:11:00Z"
}

DELETE /api/v1/alignment-validations/api/v1/alignment-validations/:validationId

Delete a validation record

Public

Response Example

{
  "deleted": true,
  "validation_id": "val_001"
}

GET /api/v1/alignment-validations/api/v1/alignment-validations/peer-mentor/:peerMentorId/discrepancies

Get all discrepancies for a peer mentor in a given time window

Public

Response Example

{
  "peer_mentor_id": "usr_4f8a2c",
  "time_window": "quarterly",
  "discrepancies": [
    {
      "field": "hours_logged",
      "dashboard_value": 128.5,
      "export_value": 126,
      "delta": 2.5,
      "severity": "minor"
    }
  ]
}

GET /api/v1/alignment-validations/api/v1/alignment-validations/peer-mentor/:peerMentorId/status

Check current alignment status for a peer mentor and time window

Public

Response Example

{
  "peer_mentor_id": "usr_4f8a2c",
  "time_window": "quarterly",
  "aligned": true,
  "checked_at": "2026-03-26T10:12:00Z"
}

Additional Metadata

{
  "contract_summary": {
    "total_contracts": 410,
    "total_endpoints": 2416,
    "api_styles_used": [
      "rest"
    ]
  },
  "generated_at": "2026-03-26T06:55:53.316Z"
}