API v2

New API version.

Overview

An API v2 release is a chance to fix the design choices that v1 got wrong without breaking customer integrations. Cleaner resource shapes, OAuth 2.1 instead of static API keys, cursor pagination instead of offset, signed webhooks. The discipline is shipping the new version alongside v1 for a long enough deprecation window that customers can migrate without panic.

• New API version. Cleaner resources, consistent pagination, OpenAPI 3.1 spec. Modern surface that matches what enterprise customers expect.
• OAuth 2.1 default. Replaces static API keys. Enterprise security frameworks require this.
• Cursor pagination. Replaces offset for stable iteration over large datasets. Offset breaks under concurrent inserts; cursor does not.
• Webhook signing plus deprecation window. HMAC signatures on webhook delivery; six-month parallel run for v1 keeps customer trust intact.

The approach

Three habits produce clean API evolution: OpenAPI as the single source of truth, parallel versions during the deprecation window, and a migration guide per endpoint that customers can actually use.

• OpenAPI 3.1 spec. Single source of truth. Generates clients, drives docs, gates breaking changes.
• v1 and v2 in parallel. Customers migrate on their schedule. Forced flag-day migrations cost customers.
• Migration guide per endpoint. Side-by-side comparison. Reduces the friction that keeps customers on v1.
• Deprecation header plus documented changes. v1 responses include Sunset header for automated clients; per-endpoint migration documented.

Why this compounds

Each clean major version deposits customer trust that survives the migration. The team’s API design fluency deepens; future versions ship from a methodology that is settled rather than reinvented.

• Customer experience improves. Clean v2 surface drives faster adoption. Customer-success calls get easier.
• Security improves. OAuth 2.1 replaces static API keys. Enterprise procurement gets unblocked.
• Operational fit. Cursor pagination supports large datasets without breaking under concurrent writes.
• Year-one investment, year-two habit. First major version is heavy lift. By the second, the methodology is settled.