> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soundpiece.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> How the API is versioned, what counts as a breaking change, and how deprecations are communicated

## Why version in the URL?

Every Soundpiece endpoint lives under a `/v1/` URL prefix:

```
https://api.soundpiece.co/v1/create.new_song
```

This commits us to a contract:

* Within `/v1/`, you'll never have to read a migration guide. We only add to the surface — new fields, new optional parameters, new endpoints — never break or remove.
* When we eventually need a genuinely breaking change, it'll go on `/v2/` and `/v1/` keeps running side by side for at least **6 months** so you have time to migrate without pressure.
* You can pin your integration to a major version simply by hardcoding the prefix. No header dance, no opt-in flags.

The cost is that one day there'll be a `/v2/`. The benefit is that until then, `/v1/` is stable in a strong sense.

***

## What counts as a breaking change?

These require a new major version (`/v2/`):

* Removing an endpoint.
* Removing a field from a response, or renaming one.
* Removing or renaming a required request field.
* Changing the type of a field.
* Tightening validation (a value that used to be accepted now returns `422`).
* Adding a new required request field.
* Changing the meaning of a `status` value or other enum.
* Changing the auth mechanism.

These are **not** breaking and may happen at any time under the current version:

* Adding a new endpoint.
* Adding a new optional request field (with a sensible default).
* Adding a new field to a response object.
* Adding a new enum value (e.g. a new `error.code`). Treat unknown codes as the closest stable category — typically `internal_error`.
* Loosening validation (a value that used to be rejected is now accepted).
* Bug fixes that bring behaviour in line with documented intent.
* Performance changes with no observable behaviour change.

Build your client to be tolerant of new enum values and new response fields and you'll never need to touch it for a non-breaking change.

***

## Deprecation process

When something does need to move from `/v1/` to `/v2/`:

1. **Announcement.** We email all active API key holders and publish the change on the dashboard at least **6 months** before `/v1/` of that endpoint goes away.
2. **Side-by-side availability.** `/v1/` and `/v2/` of the changed endpoint both work during the deprecation window. You migrate at your own pace.
3. **`Sunset` header.** `/v1/` responses on deprecated endpoints carry the [`Sunset` header](https://www.rfc-editor.org/rfc/rfc8594) (an HTTP-date) so your logs and monitoring can pick it up:
   ```http theme={null}
   Sunset: Wed, 21 Oct 2026 07:28:00 GMT
   ```
4. **Sunset.** After the announced date, the deprecated endpoint returns `410 Gone` with a `detail` field pointing to the replacement.

Emergency changes (e.g. critical security fixes) may need a shorter window. We notify affected accounts directly and provide a migration path.

***

## What this looks like in practice

A typical year:

* **Several non-breaking changes per month** — new endpoints, new optional fields, new error codes. No action needed from you.
* **One or two `/v2/` migrations across the whole API** — announced 6 months ahead, dual-running, with a clear migration guide for each affected endpoint.

You shouldn't be surprised by anything we ship. If you ever are, that's a bug — write to [business@soundpiece.co.uk](mailto:business@soundpiece.co.uk) and we'll look at how the communication chain broke down.

***

## Recommendations

* **Watch the `Sunset` header** in your logs. A request returning `Sunset` doesn't fail — it just tells you when to migrate by.
* **Keep `last_used_at` honest** on every API key. We use it to identify who to email when something is changing, so a key that's still being used by an old integration will get the deprecation notice.
* **Test against the latest version regularly.** New optional fields and new endpoints sometimes solve problems you didn't realise you had.