What v1 promises
The version lives in the base path. This page says exactly what that buys you, what may change underneath you, and what would cost a new version segment.
The v1 surface is read-only and additive. Anything below under guaranteed will not change without a new version segment; anything under tolerated may change in place, so write clients that cope with it.
Base path: /api/v1
What will not change inside v1
- Endpoint paths and HTTP methods.
- Field names, their types, and their nesting. Existing fields are never removed or renamed.
- Error
codestrings and the HTTP status each maps to. - Documented query-parameter names, their defaults, and their accepted range. A range may widen; it will not narrow.
- The
{ error: { code, message } }envelope shape on every failure.
What may change without notice
These are additive or cosmetic, and they ship inside v1 whenever they are ready. Write your client so that none of them breaks it.
- New fields appearing in a response object. Ignore what you do not recognise rather than rejecting the payload.
- New endpoints, and new optional query parameters on an existing endpoint.
- New values in a documented enum —
https,template,role,status. Give every switch a default arm. - The human-readable
messageon an error. Branch oncode; never onmessagetext. - Ordering, except where an endpoint documents its order explicitly.
A new value in a documented enum is not a breaking change here, which puts a real obligation on your side: a switchon a domain's https state, on a site's template, or on a member's role must cope with a value it has never seen. New templates in particular ship regularly — treat that field as an open set.
What would cost a new version
- Removing or renaming a field, an endpoint, or an error code.
- Changing a field's type, or making a non-nullable field nullable.
- Narrowing an accepted parameter range, or changing a documented default.
- Changing which HTTP status an error code returns.
Deprecation policy
A breaking change ships as a new base path (/api/v2); /api/v1 keeps serving. There is no sunset date for v1 today, and any future one would be announced in the console before it took effect.
In practice that means an integration written against /api/v1 today keeps working: a change we cannot make compatibly arrives beside it at a new path rather than underneath it.
Checking for yourself
The promises above are ours; the OpenAPI document is how you verify them. Keep a dated copy and diff it after a release — anything that moved shows up as a line, and anything on the breaking list above should never appear in one.
curl -s https://webbuddy.radioworkflow.com/api/v1/openapi.json > api-$(date +%F).json diff <(jq -S . api-2026-01-01.json) <(jq -S . api-$(date +%F).json)
It is generated from the same catalogue every page in these docs renders from — see the API reference.
One thing that is explicitly not a promise
An error's message is prose for a human reading a log. It is reworded whenever the wording can be made clearer, and matching on its text will break. The code beside it is the contract — see the errors page for the complete set.