# Versioning and deprecation

> How Gomry Cloud versions its API, what counts as a breaking change, and the notice and headers you get before anything is withdrawn.

Source: https://cloud.gomry.com/docs/versioning

The API is versioned by its **`/v1` path prefix**, which is the contract you code against. This page says what we may change inside it without telling you, what we may not, and how you find out before something goes away.

## What the version covers

`/v1` is the whole data plane. There is no date-pinned version, no `Api-Version` header and no per-account pin — one live contract, and the machine-readable description of it is at [/openapi.json](https://cloud.gomry.com/openapi.json). That document's own `info.version` is its revision, not the API's; branch on the path prefix, never on that number.

## What we may change without notice

Anything a correctly written client already tolerates. **Write your client to ignore fields it does not recognise** — that single habit is what makes every change below safe for you.

- New endpoints, and new optional request fields.
- New fields in a response body, and new values in a field that is already documented as open-ended.
- New error codes, within a status you already handle. Branch on the code, treat an unknown one as the class its status implies.
- New response headers.
- Rate-limit defaults, and the per-unit rates — rates are published at [Pricing](https://cloud.gomry.com/pricing) and always render from the live price list. A change there is a price change, not an API change.
- Wording of any `message`. It is written for a person and may be rewritten at any time.

## What counts as breaking

- Removing or renaming an endpoint, a request field, a response field or an error code.
- Narrowing what a request field accepts, or making an optional field required.
- Changing the type or the meaning of an existing field.
- Changing which scope an operation requires.
- Changing the unit an operation is metered in — the rate may move freely; what the unit *counts* may not.

> **Important:** Service **identifiers** never change even when display names do. `scrape`, `toolsapi` and `tasks` are written into live API keys, usage records and scope strings — the name a page shows you and the identifier the contract uses are allowed to disagree, and `tasks` / Superagent already do.

## Notice, and the headers that carry it

A breaking change ships as a new path prefix — `/v2` — and never as an edit to `/v1`. Once a successor exists, the older operation is marked deprecated and stays serving for the notice period below.

| Signal | Where | Means |
| --- | --- | --- |
| `Deprecation` | Response header, [RFC 9745](https://www.rfc-editor.org/rfc/rfc9745) | An HTTP date. This operation is deprecated as of then; a successor exists and is named in `Link`. |
| `Sunset` | Response header, [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) | An HTTP date. The operation stops serving after it. |
| `Link: rel="successor-version"` | Response header | Where to go instead. |
| `deprecated: true` | [/openapi.json](https://cloud.gomry.com/openapi.json) | The same fact, for a client generator and an agent. |

**The notice period is twelve months** between the first `Deprecation` header and the `Sunset` date, and we will mail the technical contact on every organization whose keys called the affected operation in the preceding ninety days. Nothing is withdrawn without both.

> **Note:** An automated caller should log a `Deprecation` header rather than ignore it: it is the one signal that arrives long before anything breaks, and an unattended integration is exactly the kind that finds out on the sunset date otherwise.

## The two exceptions

**Security.** If serving an operation is actively unsafe — a vulnerability, a credential exposure, an upstream provider withdrawing something under us — we will change or withdraw it faster than twelve months, and say why. This is the only case in which notice is shortened.

**Third-party catalogues.** ToolsAPI runs tools published by other vendors. Which tools exist, what they cost and what their inputs look like is the vendor's decision, not ours, and none of it is covered by this policy — `discover` and `inspect` tell you the current state, which is why the docs tell you to read them rather than cache what they returned.