API Versioning

​

Versioning Strategy

ProBeya uses URL path versioning to maintain backward compatibility while evolving the API. Each major API version is identified by a path prefix.

https://{org}.probeya.com/api/v1/ingest/batch
https://{org}.probeya.com/api/v2/ingest/batch   (future)

​

Current Versions

​

Change Policy

​

Additive (Non-Breaking) Changes

These changes are applied to the current version without bumping the version number:

• Adding new API endpoints or tRPC procedures
• Adding new optional fields to request bodies
• Adding new fields to response objects
• Adding new webhook event types
• Adding new API key scopes
• Adding new enum values to existing string union types
• Relaxing validation constraints (e.g., increasing a field length limit)
• Adding new optional query parameters to existing endpoints

Clients should be written to ignore unknown fields in responses to remain forward-compatible.

​

Breaking Changes

These changes require a new API version:

• Removing or renaming an existing field
• Changing the type of an existing field
• Making a previously optional field required
• Changing the semantics of an existing endpoint
• Removing an endpoint or tRPC procedure
• Changing authentication or authorization behavior
• Tightening validation constraints
• Changing error response shapes or codes for existing error conditions
• Reordering or renaming enum values that clients may have persisted

​

Version Lifecycle

Each API version progresses through three phases:

​

Active

The version is fully supported and receives all additive changes. This is the recommended version for all new integrations. Bug fixes and security patches are applied immediately.

​

Deprecated

The version continues to function but is no longer recommended for new integrations. During the deprecation period:

• The Sunset HTTP header is included in all responses
• The Deprecation: true header is included in all responses
• A Link header points to the successor version’s migration guide
• No new features are added; only security fixes are applied
• The deprecation period lasts a minimum of 6 months

​

Retired

After the sunset date, the version is removed. All requests return 410 Gone with a JSON body containing migration instructions and a link to the successor version.

​

Sunset Header

When a version is deprecated, ProBeya includes the Sunset HTTP header in all responses from that version:

HTTP/1.1 200 OK
Sunset: Sat, 01 Oct 2026 00:00:00 GMT
Deprecation: true
Link: <https://docs.probeya.com/api-reference/migration-v2>; rel="successor-version"

​

Timeline

​

Compatibility Matrix

The following table tracks which features are available in each API version:

​

Migration Guide

When a new version is released:

1. Review the changelog for breaking changes (see API Changelog)
2. Update your client to use the new base path (/api/v2/ etc.)
3. Test in staging against the new version before switching production traffic
4. Monitor the Sunset header on the deprecated version for the retirement date
5. Update webhook endpoints if payload shapes have changed
6. Verify API key scopes — new versions may introduce new scopes for new features

​

Dual-Version Transition Pattern

During the deprecation period, both the old and new versions run simultaneously. We recommend:

Phase 1: Deploy client with new version support (reads from v2, writes to v1)
Phase 2: Validate v2 responses match expected shapes in staging
Phase 3: Switch writes to v2
Phase 4: Remove v1 code paths after confirming no regressions

This phased approach minimizes risk for production integrations.

​

tRPC Considerations

ProBeya’s API is built on tRPC, which provides end-to-end type safety. When using the tRPC client:

• TypeScript types are generated from the router — schema changes are caught at compile time.
• Batch requests — multiple procedure calls can be batched in a single HTTP request for efficiency.
• Subscriptions — real-time updates via WebSocket transport follow the same versioning policy.

For REST consumers using the OpenAPI specification, the same versioning rules apply. The OpenAPI spec at /api/v1/openapi.json always reflects the current state of the v1 API surface.

​

Best Practices for API Consumers

• Pin to a specific version in your integration code (/api/v1/)
• Handle unknown fields gracefully — do not fail on extra response fields
• Monitor Sunset headers — set up alerts when deprecation is detected
• Subscribe to the changelog — stay informed about upcoming changes
• Use API key scopes — request only the permissions your integration needs
• Implement exponential backoff — respect rate limits and retry with increasing delays
• Cache read responses — use ETags and If-None-Match headers where supported
• Log API version headers — track which version your integration is using in production
• Test against staging — ProBeya provides a staging environment that mirrors production API versions