# API Versioning

> The MyStocks Partner API is versioned via the URL path, current stable v1. What counts as a backwards-compatible change vs. a breaking change, plus the 90-day deprecation policy and its response headers.

The Partner API is versioned via the URL path. The current stable version is `v1`. The sandbox mirrors
the same versioning scheme.

| Environment | Base URL |
| --- | --- |
| Production | `https://mystocks.africa/api/v1/partner` |
| Sandbox authenticated API | `https://mystocks.africa/api/sandbox/v1/partner` |

`POST /api/sandbox/v1/register` and `POST /api/sandbox/v1/reset` are the only root-level sandbox utilities. All other authenticated sandbox operations use the `/partner` base.

## Backwards-compatible changes (no version bump)

These changes will not break your existing integration. We make them freely within `v1`:

- Adding new optional fields to request bodies.
- Adding new fields to response objects.
- Adding new endpoints or HTTP methods.
- Adding new webhook event types.
- Adding new query parameters (all optional).
- Adding new error codes for new scenarios.

## Breaking changes (require a bump to v2)

- Renaming or removing existing fields from request/response bodies.
- Changing the type of an existing field (e.g. number → string).
- Removing or renaming endpoints or HTTP methods.
- Changing the authentication scheme.
- Changing error-code semantics for existing scenarios.

## API lifecycle

Every public operation or field is `SUPPORTED`, `DEPRECATED`, `SUNSET`, or `RETIRED`. `SUPPORTED` is the default. `DEPRECATED` remains functional while migration guidance and telemetry are available. `SUNSET` has a fixed removal date. `RETIRED` returns `410 Gone` or is absent only after its notice period ends.

Promoted GA contracts receive at least **180 days** between deprecation announcement and retirement. Beta or explicitly preview functionality receives at least 90 days. When a new major version replaces a GA version, MyStocks supports the previous major version for at least 12 months from the new version's GA date.

## Deprecation policy

<Callout type="warn">
  Deprecated GA endpoints and fields receive a minimum **180-day sunset notice**. You will be notified via:
  email to your registered partner address; a `Deprecation` response header on every affected call; a
  `Sunset` response header with the removal date; and a changelog entry marked _Deprecated_.
</Callout>

```http
# Headers present on deprecated endpoints:
Deprecation: true
Sunset: Thu, 31 Dec 2026 00:00:00 GMT
Link: <https://mystocks.africa/partners/docs/changelog>; rel="deprecation"
```

Check for the `Deprecation: true` header in your HTTP client to detect deprecated usage before the
sunset date.

Removal notices identify the affected operation/field, replacement, migration guide, announcement date, last supported date, and removal date. MyStocks publishes the notice in the changelog and documentation, emails registered technical contacts, exposes `Deprecation`, `Sunset`, and `Link` headers, and may emit partner-dashboard alerts. Emergency security changes may use an accelerated timeline only where continued operation creates material risk; MyStocks will publish the reason and mitigation.