Versioning & Compatibility
This page defines exactly what VoxBurst commits to stabilizing, what can change without notice, and how breaking changes are communicated.
API versioning
The current API version is v1, indicated in every URL path (/v1/posts, /v1/accounts, etc.).
VoxBurst does not use date-stamped versions (like 2026-06-01) or header-driven versioning. All production requests go to https://api.voxburst.io/v1.
What is and is not a breaking change
Non-breaking (deployed without notice)
These changes are backward-compatible. Well-written clients handle them automatically:
| Change | Required client behavior |
|---|---|
| New optional request field | Ignore — existing requests work unchanged |
| New response field | Ignore unknown fields (don’t fail on unrecognized keys) |
| New enum value | Handle unknown enum values gracefully |
| New endpoint | No action required |
| New error code on an existing error status | Branch on status code first, then code |
| Performance improvements, latency reductions | Transparent |
| Webhook: new event type | Subscribe to * or ignore unrecognized event types |
Breaking (announced 30 days in advance)
These changes require client updates:
| Change | Example |
|---|---|
| Remove a required or widely-used field from a response | Removing post.status |
| Rename a field | scheduledFor → scheduledAt |
| Change a field’s type | string → string[] |
| Change an enum value’s meaning | "failed" → "error" with different semantics |
| Remove an endpoint | Removing GET /v1/posts/:id |
| Change authentication scheme | Replacing Bearer tokens |
| Change pagination behavior | Moving from cursor to offset |
| Change an error code’s HTTP status | Moving RATE_LIMITED from 429 to 503 |
Required: ignore unknown fields. The most common source of breakage is a client that fails on unexpected JSON keys. All VoxBurst clients should use a JSON parser configured to ignore unknown fields. The TypeScript and Go SDKs do this automatically.
Deprecation process
- Day 0 — Field or endpoint marked as deprecated in docs with removal date
- Day 0 — Deprecation announced in the changelog and via email to all API key owners
- 90 days — Deprecated field remains fully functional
- Day 90 — Field or endpoint removed
For high-impact removals (widely-used endpoints, required fields), the deprecation window may be extended to 180 days. The changelog entry will specify the exact removal date.
SDK versioning
SDKs follow semantic versioning :
| Bump | When |
|---|---|
Patch (1.2.0 → 1.2.1) | Bug fixes, documentation, internal refactors |
Minor (1.2.0 → 1.3.0) | New methods, new optional parameters, new typed properties |
Major (1.2.0 → 2.0.0) | Breaking interface changes (method renamed, parameter removed, error class renamed) |
SDK major versions track API v1 — a breaking SDK change does not imply an API version bump. An API v2 would trigger SDK major bumps across all packages.
Current SDK versions
| Package | Version | Install |
|---|---|---|
@voxburst/sdk (TypeScript) | See changelog | npm install @voxburst/sdk |
voxburst-go (Go) | See changelog | go get github.com/FortheanLabsProjects/voxburst-go |
@voxburst/cli | See changelog | npm install -g @voxburst/cli |
What is stable vs. experimental
| Status | Meaning |
|---|---|
| Stable | Follows the full breaking-change policy above. Any change will be announced 30 days in advance. |
| Beta | Under active development. May change without notice. Marked (beta) in docs. |
| Deprecated | Scheduled for removal. Marked (deprecated) in docs with removal date. |
Resources currently in beta or preview are noted on their individual API reference pages.
Contract precedence
When sources appear to conflict, this ordering determines which is authoritative:
- API source code — the implementation is ground truth
- This documentation —
/api-reference/*pages are validated against the codebase before publishing - OpenAPI spec — machine-readable contract at
https://api.voxburst.io/api/openapi.yaml; kept in sync with the implementation - SDK docs — derived from the REST contract; SDK behavior defers to REST on conflict
- Examples — illustrative, not normative; may omit optional fields
Staying informed
| Channel | What you get |
|---|---|
| Changelog | Every API and SDK change, tagged by type |
| Docs & contract changes | Schema corrections, new pages, field table updates, spec changes |
| Breaking-change announcements sent 30 days before removal to all API key owners | |
| @voxburst on X | Major release announcements |
OpenAPI spec
The machine-readable API contract is published at:
https://api.voxburst.io/api/openapi.yaml # YAML
https://api.voxburst.io/api/openapi.json # JSONThe spec is kept in sync with the implementation and follows the same versioning rules above. Use it with Postman, Insomnia, openapi-typescript, oapi-codegen, or any OpenAPI-compatible toolchain.