Versioning

The version lives in the path: /v1. A new major version would be a new path, served next to this one, not a replacement of it.

What we will not do inside v1

An integration built today keeps working. These are the rules the API is held to:

• A response field is never removed or renamed. A field that stops being meaningful keeps answering with an empty or null value.
• A parameter is never removed, renamed or reordered. New parameters are optional and are added at the end.
• A default never changes. New behaviour arrives behind a new parameter, and the default is what an older client already sees.
• Error codes and their HTTP statuses stay put. Wording in message may change, codes do not.

These are the same rules our mobile apps hold the backend to, for the same reason: a client that is already deployed cannot be asked to update on our schedule.

What may change without notice

• New fields appearing in responses. Ignore what you do not read; do not validate strictly against a closed schema.
• New endpoints, new optional parameters, new enum members in additive positions.
• Ordering within a list, unless the endpoint documents an order.
• Wording of error.message and of human-readable text.
• Corpus contents: clips are added daily and removed when a source video disappears.