Changelog

All notable changes to the Xref API will be documented here. Versions follow Semantic Versioning and are advertised via the URL prefix (/v1/, /v2/, ...).

v1.0.0 — 2026-09-17

Initial public release of the Xref API.

Added

• Authentication. API-key + user-email header flow ("Scenario 1"). Unauthenticated GET /v1/ping for health checks.
• Endpoints:
  • GET /v1/ping
  • GET /v1/packages (with optional status=active|inactive|disabled and id=<int> filters)
  • GET /v1/packages/{id}/schema
  • POST /v1/requests (asynchronous acceptance, 201 Created with request_id)
  • GET /v1/requests/{id} including child-check rollup, background check display names, and referee reports
  • GET /v1/reports/{check_id} (completed background check PDF proxy via header or signed ?t= token)
  • GET /v1/reports/{check_id}/referees/{referee_id} (completed referee report PDF proxy via header or signed ?t= token)
  • GET /v1/users (list active organisation users, roles, teams, and per-product permissions)
• Webhooks. Single configurable webhook per organisation. Payloads are HMAC-SHA256-signed via the X-Xref-Signature header. v1 emits a single event: request.updated.
• Errors. Uniform {data, status_message, message} envelope. Throttling (per-API-key, per-minute and per-hour windows) returning 429 with Retry-After.