Developer Docs
Versioning
How /v1 stays stable and how changes are deprecated.
/v1 is a stable contract you can build on. Here is exactly what may change under it, what may not, and how anything is ever retired.
The version lives in the path
Every route is under /v1. A breaking change ships as a new major prefix (/v2), never as a silent change to /v1.
Additive changes are not breaking
New endpoints, new optional request fields, new response fields, and new enum values can appear within /v1 at any time. Write clients that ignore unknown fields.
Breaking changes get a new version
Removing a field, renaming one, changing a type, or changing the meaning of a value is breaking and only happens in a new major version.
Deprecation is announced and windowed
Before anything is retired we mark it deprecated in the changelog and return Deprecation and Sunset response headers, giving a stated window before removal.
Deprecation headers
A deprecated route or field returns a Deprecation header (RFC 8594) and, once a removal date is set, a Sunset header. Watch for them in your logs — they are your early warning.
Freshness is the SLA, not "instant"
We commit to how current data is via the provenance envelope, not to synchronous freshness. Reads never block on a live TikTok fetch; a refresh is asynchronous. Rate limits and realtime limits are covered in Rate limits & Credits.
How changes are announced
Every contract change — a new endpoint, a new event, a changed credit cost, an SDK release — is recorded in the public changelog, dated, in the same change that ships it. That log is the single place to track what moved.