API Versioning | Speechify API

Speechify uses a dated request header for breaking wire-format changes inside /v1.

1 Speechify-Version: 2026-06-25

The official SDKs send their build-date version by default. Raw HTTP integrations should send Speechify-Version on every request so response shapes stay pinned as the API evolves.

Resolution Order

When a request reaches the API, the server resolves the version in this order:

Priority	Source	Behavior
1	`Speechify-Version` request header	Overrides every other source for this request
2	Workspace default version	Used when the request omits the header
3	Oldest supported version	Legacy fallback when no workspace default exists

New workspaces default to the latest API version available when the workspace is created. Existing workspaces stay pinned to their stored default until you explicitly migrate or Speechify updates the default with notice.

A malformed value (anything other than an ISO YYYY-MM-DD date) returns 400 invalid_api_version.

What counts as a breaking change

Speechify only mints a new version date for a change that could break a client reading an older shape. Most changes are additive and never require you to bump your pinned version. To stay forward-compatible, write your integration as a tolerant reader:

Ignore fields you don’t recognise. We may add new response fields at any time without a version bump.
Ignore enum values you don’t recognise. New status values, new error codes, and other enum members can appear within your pinned version. Handle unknown values with a default branch.
Treat absent optional fields as unset, not as an error.

The following changes are additive and ship without a new version — your pinned integration keeps working unchanged:

Additive change	Effect on your integration
New optional response field	None — ignore it.
New optional request field or query parameter	None — omit it and the server uses its default.
New enum value (including a new error `code`)	None — your default branch handles it.
New endpoint or new path	None — nothing you call changes.
A relaxed constraint (wider range, a field made optional)	None — every request you already send stays valid.

A change only gets a new version date when it would alter a shape you already depend on — a renamed or removed field, a field whose type changes, a new required request field, or a changed default. When that happens, you keep receiving the shape your current version resolves to (so nothing breaks): the official SDKs hold their build-date version, an explicit Speechify-Version stays on its date, and a request with no version at all keeps resolving to the oldest supported shape. The change appears in the changelog with a migration path and a sunset window of at least 12 months before the old shape is retired.

Raw HTTP

Include the header with your API key:

$ curl https://api.speechify.ai/v1/voices \
>   -H "Authorization: Bearer $SPEECHIFY_API_KEY" \
>   -H "Speechify-Version: 2026-06-25"

Deprecation Notices

When a request uses a legacy version, responses include standard deprecation headers:

Header	Meaning
`Deprecation`	When the legacy version became deprecated
`Sunset`	The earliest date the legacy shape may be retired
`Link`	Migration documentation for the deprecated version

Speechify keeps legacy shapes available for at least 12 months after announcing a migration window.

Changelog

Each dated shape change appears in the product changelog with:

Field	Description
Version date	The `YYYY-MM-DD` value to pin
Changed shape	Request or response fields affected
Migration path	How to move from the previous shape
Sunset date	When the old shape may be retired

Adding new error codes is not a breaking change. The ErrorCode enum is additive-only, so new codes do not require a version bump.