API Versioning

ZapAPI uses URI-based versioning (/api/v1, /api/v2) as the primary versioning mechanism, with optional header-based versioning for clients that prefer it.

URI versioning (primary)Copy Anchor Link

All endpoints are versioned in the path:

https://api.zapapi.com/api/v1/invoices
https://api.zapapi.com/api/v2/invoices

• The default version is v1 — requests without a version prefix are routed to v1.
• New major versions (v2, v3) are introduced only for breaking changes.
• Within a major version, we may add new fields, endpoints and enum values, but we will never remove or rename existing ones.

Header versioning (alternative)Copy Anchor Link

For clients that cannot easily change URLs, version via headers:

X-API-Version: 2
# or
Accept-Version: 2

Header versioning is equivalent to URI versioning — use whichever fits your HTTP client better.

What counts as a breaking changeCopy Anchor Link

We only bump the major version for changes that would break existing clients:

• Removing an endpoint, field, or enum value.
• Renaming a field or changing its type.
• Changing the meaning of an existing field.
• Tightening validation in a way that rejects previously-valid requests.

The following are not breaking and may ship in any minor release:

• Adding a new endpoint, field, or enum value.
• Adding a new optional request parameter.
• Widening validation (accepting more inputs).
• Adding new webhook event types.

Deprecation policyCopy Anchor Link

When we deprecate an endpoint or a version:

1. Announce — in the Changelog, via email to active integrators, and in the dashboard.
2. Signal — deprecated endpoints return deprecation headers on every response:

   Copy Text

   X-API-Deprecated: true
   X-API-Deprecation-Date: 2026-01-01
   X-API-Sunset: 2026-06-01
   Sunset: Sat, 01 Jun 2026 00:00:00 GMT
   X-API-Alternative: /api/v2/users
   Warning: 299 - "Deprecated API - Sunset: 2026-06-01"

3. Support — we provide a migration guide and a minimum 6-month sunset period.
4. Remove — after the sunset date, the endpoint returns 410 Gone.

Staying up to dateCopy Anchor Link

• Subscribe to the Changelog — every API change is posted there.
• Watch for X-API-Deprecated headers in your response logs.
• Pin to a specific version in production (/api/v1) rather than relying on the default.

SDK compatibilityCopy Anchor Link

The TypeScript SDK is versioned in lockstep with the API. Major SDK versions target major API versions, so npm i @zapapi/sdk@latest always gives you a client that matches the current API.