Versioning and deprecation

The API version is part of the URL. /v1 is stable: an integration built against it keeps working until /v1 is retired, and retirement is announced well ahead of time.

The version is in the path

Every base URL ends in the version. See base URLs.

Environment	Base URL
Sandbox	https://sandbox-api.myrt.money/v1
Live	https://api.myrt.money/v1

Every response carries X-MYRT-API-Version: v1. GET /v1/health and GET /v1/config also return apiVersion: "v1". A new major version gets a new path prefix, such as /v2.

What can change without notice

These additions are not breaking. They ship inside /v1 without a version change and without advance notice:

• New endpoints.
• New optional request fields.
• New response fields, on any object.
• New phase values on an order.
• New error.code values.
• The wording of error.message. It is for humans and may be reworded at any time.

What only changes in a new major version

These changes are breaking. They never happen inside /v1; they wait for a new major version:

• Removing or renaming a field.
• Changing the type of a field.
• Changing the meaning of a status value. The six status values are fixed, and no new ones will be added in v1.
• Adding a required request field.
• Tightening validation on an existing field.

Parse defensively

Because additions ship without notice, your parser must tolerate them:

• Ignore fields you do not recognise. Never reject a response because it carries a key you have not seen before.
• Handle a phase you do not recognise. Drive business logic from status, which is fixed, and treat phase as display and support detail. See order lifecycle.
• Handle an error.code you do not recognise. Branch on the codes you know and fall back on the HTTP status for the rest: retry 429, 502, 503 and 504 with backoff, never another 4xx. See errors.
• Branch on error.code, never on error.message.

What Planned means

Some endpoints are documented before they are served. They are part of the v1 contract, carry a Planned badge next to the endpoint, and are marked with this notice:

This is part of the v1 contract and is documented ahead of release. It is not yet served in production. Build against it only once this notice is gone.

When a planned endpoint goes live, the badge and the notice are removed. The version does not change; the endpoint is served under /v1 as documented. The endpoint table shows the current availability of every endpoint.

Deprecation

When /v2 ships, /v1 stays supported for at least 12 months. Deprecation is announced by email to every key owner. While /v1 is deprecated, its responses carry a Sunset header with the retirement date. Plan your migration before that date.