Versioning and deprecation

Versions

• The version is in the path: https://reeltopus.com/api/v1. v1 is the current and only version.
• Within a version, changes are additive only. Code written against v1 today keeps working without changes.
• A change that could break a working client goes into a new version (/api/v2), never into v1. The two run side by side.
• The webhooks and the MCP server at /api/mcp follow the same rules. Webhook payloads carry the same objects the API returns.

What can change in v1 without notice

These are not breaking changes. Write your client so they can't break it:

• New endpoints, new optional request fields, new query parameters.
• New fields in responses and webhook payloads. Ignore fields you don't know.
• New values in response enums (a new project status, a new caption style, a new platform). Treat an unknown value as "other", not as an error.
• New webhook event types. An endpoint that subscribes to every type (an empty events list) receives them, so check type and acknowledge events you don't handle with a 2xx.
• New error codes for new failure cases, and clearer error messages. Match on code, never on message.
• Higher rate limits, or new limits on new endpoints.
• New MCP tools, and new optional tool arguments.

What counts as breaking

• Removing or renaming an endpoint, field, enum value, error code, webhook event or MCP tool.
• Making an optional request field required, or narrowing what a field accepts.
• Changing a field's type or meaning, or the shape of errors or pagination.
• Changing authentication, or the webhook signature scheme.
• Lowering a published rate limit for a plan.

Deprecation

• Notice: at least 6 months before anything in v1 stops working, and at least 12 months before a whole version is switched off after its successor is released.
• How you'll hear: an entry in the API changelog, an email to the owners and admins of every workspace whose keys or connected apps used the deprecated thing in the previous 30 days, and response headers on every call to it:

Deprecation: @1798761600          # RFC 9745: when it was deprecated (Unix time)
Sunset: Thu, 01 Jul 2027 00:00:00 GMT   # RFC 8594: when it stops working
Link: <https://reeltopus.com/docs/api/changelog>; rel="deprecation"

• Until the sunset date, the deprecated endpoint or field keeps working exactly as before.
• A renamed MCP tool keeps answering to its old name until the sunset date.
• Security exception: if keeping something would put customers' data at risk, we may change it sooner, with as much notice as the risk allows, and say why in the changelog.

SDKs and the OpenAPI document

• The OpenAPI document always describes production. Its info.version is the v1 contract version.
• The TypeScript and Python SDKs use semantic versioning of their own. A minor release adds support for new API features; a major release is only for breaking changes to the SDK itself, and supports the same API versions as the release before it for at least 6 months.

Beta features

Anything marked beta in the reference or the changelog can change with 30 days' notice in the changelog. Nothing in v1 is beta today.