Developers › Versioning and deprecation
Versioning and deprecation
How the REST API and the MCP server change, how you hear about it, and how long old behaviour keeps working.
The version is part of every REST path: /rest/<version>/…. Today there is one version, beta, so every endpoint is under /rest/beta/. The OAuth routes (/rest/auth/…) have no version segment. Always use the full path shown for an endpoint; /rest/workflows/ without the version does not exist.
Every change is listed in the changelog (also as an Atom feed).
What beta means
beta is open to every Sheetgo account and safe to build on. It can still change. A breaking change to beta is announced in the changelog at least 30 days before it ships. Security fixes are the exception and can ship at once.
Changes that cannot break a client ship at any time, without notice beyond the changelog.
Stable versions
A stable version (the first will be /rest/v1/) is a promise: no breaking change inside it. A breaking change goes into the next version (/rest/v2/), and the previous version keeps working for at least 12 months after the next one is published. While both exist, each has its own pages here and its own OpenAPI document.
Until a stable version is published, beta is the version to use.
What counts as breaking
| Breaking (announced in advance) | Not breaking (can ship any time) |
|---|---|
| Removing or renaming an endpoint, a field, a query parameter or an enum value you can send | A new endpoint |
| A new required request field or parameter | A new optional request field or parameter |
| Changing a field's type or meaning | A new field in a response |
Changing an error's HTTP status or code | A new enum value in a response, a new error code |
| Tighter limits (lower rate limits, smaller page sizes) | Looser limits, better error messages, faster responses |
Write clients that ignore fields they do not know and accept enum values they have not seen, so non-breaking changes never break them.
Deprecation and removal
- Deprecated. The operation is marked deprecated in this reference and in the OpenAPI spec (
deprecated: true, withx-deprecated-on), and the changelog says what to use instead. Every response from it carries:Deprecation: @<unix time>: when it was deprecated (RFC 9745);Link: <…/versioning/#deprecation>; rel="deprecation": this page.
- Removal date set. Responses also carry
Sunset: <HTTP date>(RFC 8594), at least 90 days before removal forbetaand at least 12 months for a stable version. The changelog shows the date. - Removed. After the sunset date the operation answers
410 Gonefor a while, then404.
To find deprecated calls in your code, log any response that has a Deprecation header.
Deprecated today
| Operation | Deprecated on | Use instead | Removal |
|---|---|---|---|
POST /rest/beta/automations/run/{id} | 2025-08-15 | POST /rest/beta/automations/{id}/run | not scheduled |
POST /rest/beta/workflows/run/{id} | 2025-08-15 | POST /rest/beta/workflows/{id}/run | not scheduled |
MCP tool changes
The MCP server has no path version: its contract is the tool list. The same rules apply to tools:
- Breaking (announced in the changelog at least 30 days ahead): removing or renaming a tool or a parameter, a new required parameter, a different result shape, or a tool that needs a wider API key scope.
- Not breaking (any time): new tools, new optional parameters, new fields in a result, clearer descriptions.
Clients should read tools/list when they connect rather than keep a fixed copy. The tool reference lists the current tools.