Versioning policy
The Partner API is served from https://api.dcast.pro/api/v1/... and exposes its current version on every authenticated response via the DCAST-API-Version header. The current value is v1.
What counts as a breaking change
Within /v1, none of these will happen without a version bump:
- Removing an endpoint, response field, or supported request parameter.
- Renaming an endpoint, response field, or query/body parameter.
- Changing the type of a field (e.g. string → number, single value → array).
- Tightening validation in a way that newly rejects requests the previous version accepted.
- Changing the HTTP status code returned for an established success case.
- Changing the error
codestring returned for an established error case.
What counts as additive (allowed within v1)
We may freely:
- Add new endpoints.
- Add new optional request parameters.
- Add new fields to existing response objects.
- Add new event types to the webhooks catalogue.
- Add new error codes for cases that previously returned a generic envelope.
- Tighten validation in a way that flags requests the previous version silently mishandled, when the tightening closes a security gap.
Build receivers and clients defensively: ignore unknown response fields, ignore unknown event types, and tolerate new error codes by reading error.code rather than matching exact strings.
Unknown fields in a request are handled the same way everywhere: unknown query parameters are always ignored, and unknown body fields are ignored too, except on three endpoints that refuse them instead of dropping them silently. PATCH /videos/{id} and PATCH /streams/{id} answer 400 UNSUPPORTED_FIELD for a field they do not support (for example currency), and PATCH /me answers 403 FORBIDDEN_FIELD for identity, role and plan fields. In both cases error.field names the field.
Version header
Every authenticated response includes:
DCAST-API-Version: v1You may also send the header on a request to pin to a specific version once we ship v2:
DCAST-API-Version: v1Today only v1 is implemented, so the header is informational. When v2 ships, v1 URLs will continue to behave as v1 indefinitely — we will not silently re-route old clients to a new version.
Version lifecycle
If a future v2 introduces breaking changes:
- The change ships under
/api/v2/...with its own subpath. /api/v1/...stays online for a minimum of 6 months afterv2ships.- Critical security fixes are backported to
v1during the overlap. - End-of-life is announced no fewer than 90 days before
v1stops being served.
Changelog
Material changes to v1 are logged, newest first, at GET https://api.dcast.pro/api/v1/changelog (public, no key; each entry is { date, summary }). The same list is published as the top-level x-dcast-changelog array of the OpenAPI spec. We do not log internal refactors or doc-only tweaks — only changes integrators might want to act on.

