> The Markdown source of https://developer.suredocs.ie/versioning-and-deprecation.html. The index of these files is [llms.txt](llms.txt), and the brief for coding agents building an integration is [agents.md](agents.md).

# Versioning and deprecation

We promise that a version of an API is not broken under you, and that a version we retire is announced in
advance, in the responses themselves, with at least six months before it goes.

## The path carries the version

Every product API is served at `https://api.suredocs.ie/<api>/v<n>/...`: the API's name, then its own version integer.
The upload, for example, is `POST https://api.suredocs.ie/files/v1`.

- **APIs version independently.** `/files/v1` may sit beside `/quotes/v2`. Never infer that `/files/v2`
  exists because another API is at version 2. The table below lists every API and version we publish.
- A version integer starts at 1 and only increases. It changes only for a breaking change. There is no minor
  version, because additive changes never need one.
- The API's name is part of the contract and never changes.

**The token endpoint is the exception, deliberately.** `/oauth/token` has no name and no
version. It is the OAuth authorization server, and OAuth libraries are configured with one fixed token URL.
It changes only in ways the OAuth RFCs allow.

## What we publish

| API | Version | Status | Reference |
| --- | --- | --- | --- |
| `files` | 1 | Live | [SureDocs files API, version 1](reference/files-v1.html) |
| Authorization server (`oauth`) | none | Live | [SureDocs authorization server](reference/oauth.html) |

## What counts as a breaking change

We never make these to a live version. Each ships as the next version integer of that API alone.

1. Removing an operation.
2. Removing or renaming a response field.
3. Adding a required request field, or making an optional one required.
4. Removing an accepted request field.
5. Narrowing an enum or a type: a request field that accepts fewer values, or a response field that may
   return a type you were not promised, such as a field becoming nullable.
6. Tightening a limit: a smaller maximum size, a shorter maximum length, fewer items allowed.
7. Changing a status code for an existing outcome.
8. Changing an error reason code for an existing outcome.

Two further changes break callers without being visible in an operation's schema, and we rule them out
for a live version too: removing a response header these pages promise, and requiring a scope an existing
operation did not require before.

## What is not, and what your code must tolerate

These ship inside the current version, without notice. Write your client so that none of them breaks it.

- A new optional request field.
- A new response field. **Ignore fields you do not recognise.**
- A new operation.
- A newly accepted content type.
- A new value in a **response** enum, including a new error `reason` for a new outcome. **Handle a
  `reason` you do not recognise by its HTTP status.**

Do not depend on the order of fields in a response, or on the length or format of any identifier we return.
Identifiers are opaque.

## Deprecation and removal

When a version has to break, we ship the next version and deprecate the old one. The old one keeps working.

- **At least six months** pass between the day a version is deprecated and the day it can be removed. The
  removal date is fixed when the version is deprecated, and it is never earlier than the deprecation date
  plus six months.
- The tables above and the [API reference](reference/index.html) show the removal date beside a deprecated
  version. Both are generated from the code that serves it, so they cannot disagree with it.
- **Every response from a deprecated version says so**, in headers:

  | Header | Meaning |
  | --- | --- |
  | `Deprecation: @<unix seconds>` | The moment the version was deprecated (RFC 9745). |
  | `Sunset: <HTTP date>` | The removal date (RFC 8594). |
  | `Link: <address>; rel="deprecation"` | Where the migration notes are. |

- A version is removed on or after its removal date, and not before.

Log these headers and alert on them, so that a deprecation reaches a person on your side long before the
removal date does.

## Changes to these documents

The reference documents and the numbers on these pages are generated from the code that serves the APIs,
by the same build that ships it. When the two differ, the code is right and the build is wrong, and we want
to hear about it.