# Versioning and deprecation

> Know what can change in the API, how you are warned, and how long old calls keep working.

HTML version: https://developers.sheetgo.com/versioning/

[Developers](/index.md) › Versioning and deprecation

Policy

## 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](/changelog.md) (also as an [Atom feed](/changelog.xml)).

## 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

1. **Deprecated.** The operation is marked deprecated in this reference and in the OpenAPI spec (`deprecated: true`, with `x-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.It keeps working.
2. **Removal date set.** Responses also carry `Sunset: <HTTP date>` (RFC 8594), at least **90 days** before removal for `beta` and at least **12 months** for a stable version. The changelog shows the date.
3. **Removed.** After the sunset date the operation answers `410 Gone` for a while, then `404`.

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}`](/api/automations.md#post-rest-beta-automations-run-id) | 2025-08-15 | POST /rest/beta/automations/{id}/run | not scheduled |
| [`POST /rest/beta/workflows/run/{id}`](/api/workflows.md#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](/mcp.md#mcp-tools) lists the current tools.