👀 Overview

This major release introduces many new features with only a minimal number of breaking changes. Most breaking changes stem from stricter naming conventions and can typically be resolved by updating property names in existing integrations.

The most significant change in version 2—while not strictly breaking—is the introduction of the Mutation Engine. Adopting this new model in an existing implementation requires some additional integration effort. We therefore strongly recommend reviewing the mutation engine documentation before starting your migration.

Key themes in this release:

• API hardening and resilience
  Improved handling of upstream latency and data inconsistencies to ensure more predictable and robust behavior.

• Improved developer experience (DX)
  Introduction of a sandbox environment for safely testing integrations API key management workflows, and enhanced error logging and observability.

• Expanded candidate management tools
  Increased the number of available endpoints and capabilities for managing candidates within your region.

• Candidate identity verification
  Introduction of candidate-facing authentication flows based on email verification.

• Region lifecycle
  First-class support for managing regions and their credentials directly through the API.

---

✨ New features

• Domain-based API structure

  Introduced explicit tags and endpoint groups for Auth, Regions, Admin, Candidates, Schema, and Webhooks, making responsibilities and access scopes clearer across the API.

• Candidate email verification flow

  Added a candidate-facing authentication endpoint to initiate email-based identity verification. This enables secure, session-based access patterns for candidates without exposing region API keys.

• Region management endpoints (admin)

  Added admin-only endpoints to list, create, and update regions, including visibility into associated API keys. This formalizes region onboarding and operational control in the API itself.

• API key lifecycle management

  Regions can now programmatically create and revoke API keys. Keys are returned in full only once, enforcing secure storage and rotation practices by default.

• Webhook ingestion for regions

  Introduced a dedicated webhook endpoint for ingesting region updates from Airtable, authenticated via webhook-scoped API keys.

• Region context override (admin)

  Admin-scoped API keys may override region context via a query parameter, enabling safe testing, debugging, and sandbox-style simulations without duplicating credentials.

🛠️ Fixes

• Explicit security requirements per endpoint

  Authentication requirements are now defined per operation instead of implicitly at the API root, preventing accidental exposure of public or candidate-facing endpoints.

• Consistent response envelopes

  Standardized success and error responses across all new endpoints, ensuring predictable response shapes and easier client-side handling.

🛠️ Chore

• Breaking API versioning

  Introduced /api/v2 as a hard version boundary. Existing integrations on v1.x will need to migrate explicitly.

• Expanded OpenAPI schemas

  Refactored and extended core schemas (Region, ApiKey, Schema fields) to support upcoming mutation endpoints and richer validation rules.