Skip to main content

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.

​
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 (an HTTP-date) so your logs and monitoring can pick it up: 
    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 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.