# 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 GA and preview deprecation policies 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

> 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 when a removal date has been announced; and a changelog entry marked *Deprecated*.

```http
# Headers present on deprecated endpoints:
Deprecation: true
Sunset: Thu, 31 Dec 2026 00:00:00 GMT
Link: <https://partners.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.

## Documentation shipped with an installation

Each on-prem image includes a verified snapshot of the shared guides, OpenAPI contract, API tester, and recipe examples. OpenAPI downloads at `/openapi.yaml` and `/openapi.json` resolve inside the installation.

Inspect `/api/docs-release` on your installation for its API version, source commit, OpenAPI SHA-256 and bundled artifact hashes. The same hashes are stored in `/docs/release-manifest.json`. Match `sourceCommit` to the approved image release before comparing integration behavior; API v1 alone does not identify a documentation snapshot. Locally built images may report an unknown commit.

Documentation synchronization and hash verification run before release builds. A stale or modified bundle fails the release gate. Hosted API operations still pass through the configured MyStocks gateway, whose lifecycle is independent of the installation image. This snapshot identifies the documentation shipped with the image; it does not certify a broker connection, live execution or settlement.

Stock history/chart routes and legacy pagination fields remain supported compatibility surfaces. Their earlier 1 October 2026 removal notice is superseded, with no removal currently scheduled. Deprecation and successor links remain; a Sunset header is omitted until a new approved removal date exists. Other alias notices retain their separately published policy.
