Skip to main content

Versioning and compatibility

Apps built on the API can run for years without updates, so /v1 changes only in ways an existing client keeps working through.

What may change within /v1​

  • New things are added in place: new operations, new optional request fields and query parameters, new response fields, new event types, new error codes.
  • Sets of values grow: event types, error codes, statuses, progress categories, UI component types and other enumerations may gain values. Ignore a value you do not recognize, and treat an unknown error code by its HTTP status family.
  • Field order in JSON and the wording of human-readable messages may change.

What never changes​

  • How a task ends. A task ends with task.completed, task.failed or task.stopped, and its status reads completed, failed or stopped. A new way for a task to end is a new error code on an existing end event, so a client never waits for an end it cannot recognize.
  • A field is never removed, renamed or given a new type or meaning; a default never changes; an input accepted today is not refused tomorrow; an operation's credential stays the same.

Breaking changes​

A change that would break a client — any of the ones above — ships as a new version of the affected resource only (/v2/… for that resource), next to the old one. Every other resource stays on /v1.

  • An old version is served for at least 36 months after its successor ships, and for as long after that as it is still called.
  • Its retirement is announced in its responses: Deprecation and Sunset headers, from at least six months before the sunset date.
  • After the sunset date it answers 410 endpoint_retired. On /v1, 410 means only that, so a client may treat any 410 as "upgrade needed".

Requests are strict​

Request bodies reject unknown fields and /v1 rejects unknown query parameters (422 validation_failed). A new field is deployed on the server before any client starts sending it, so a client never depends on a field the server does not know yet.

Declaring your client's protocol​

When behavior must differ between client generations, the server switches on the VI-Protocol-Version header: the date of the protocol revision your client was built against, for example VI-Protocol-Version: 2026-10-16. A request without it gets the original behavior, so a client that never sends it never sees behavior change under it.