API versioning and deprecation policy

The current PostPod API version is v1. The version is in the URL path, /api/v1. This page is the public policy for how that version changes and how a later version would be retired.

What can change inside v1

Additive changes can happen within v1. PostPod can add optional request fields, optional response fields, new endpoints, and new error codes without a new version. Clients should ignore response fields they do not use. A documented enum can gain a value only when the contract already says the list can grow.

Breaking changes ship only in a new version. A breaking change removes or renames a documented field, changes the meaning or type of a field, makes an optional input required, or removes an endpoint. That work is published at a new path such as /api/v2. It is not applied silently to /api/v1.

Notice before a version is retired

When a version is retired, PostPod gives at least 6 months' notice. That length is the published default and PostPod may change it. The number stated on this page is the notice that applies. During the notice period the old version keeps working. Individual fields or endpoints get the same notice before they are removed or renamed.

Notice goes out in three places. This page gets a dated announcement that names the affected version, endpoint, or field, the replacement, and the sunset date. Responses for the affected version send a Deprecation header (RFC 9745) set to the announcement time as a structured-field date, and a Sunset header (RFC 8594) set to the HTTP date when it stops working. Those responses also send Link: <https://postpodai.com/developers/deprecation>; rel="deprecation".

Current announcements

Voice ids that are not the lowercase display name are deprecated as of 2026-10-29. Current ids are nora, leo, kristine, ken, and marko. Deprecated voice ids are still accepted and are not returned: stock-nora → nora, stock-reed → leo, stock-sienna → kristine, stock-kai → ken, stock-mira → marko. Responses use the current id. These aliases stay accepted for at least 6 months from 2026-10-29. v1 is the current version. v1 responses do not send Deprecation or Sunset headers for this alias. The notice is this page, the developer docs, and the OpenAPI description. The helper that would set those headers is not active on any route.

Start with the developer docs, the API rate limits, the API changelog, the OpenAPI specification, and llms.txt.