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

# Versioning

> URL-path versioning, breaking-change policy, and deprecation timelines.

## Current version

**v1.** All endpoints live under `https://api.novatrade24.com/v1/...`. The
spec document is `openapi-integration-v1.yaml`.

## Version in URL path

We use URL-path versioning (`/v1/`) rather than headers. Reasons:

* Cacheable, bookmarkable, copy-pasteable.
* Obvious in logs and error reports.
* Trivially routable at edge.
* Matches Stripe/GitHub/Twilio convention.

## Non-breaking vs breaking

### Non-breaking (ship in current version, any time)

* New endpoints.
* New optional request fields.
* New response fields.
* New enum values on fields where the schema documents "may add values".
* New error problem types.
* New webhook event types.
* Increased rate limits.

Your client **must ignore unknown fields** and **must accept unknown
enum values gracefully** — wire this assumption into your deserialization.

### Breaking (requires new major version)

* Removing endpoints or fields.
* Renaming fields.
* Changing response types.
* Removing enum values.
* Tightening constraints (stricter validation on existing fields).
* Changing auth flow.
* Changing the signature algorithm on webhooks (bumps webhook
  `schemaVersion` in parallel).

Breaking changes ship as `v2` on a new URL path (`/v2/...`).

## Deprecation policy

* Breaking changes are announced at least **12 months before removal**.
* `v1` remains available for at least **12 months after `v2` launches**.
* Deprecated endpoints return `Deprecation: true` and `Sunset: <date>`
  headers (RFC 8594) on every response during the overlap period.
* Changelog entries flag deprecated features explicitly.

Example headers on a deprecated endpoint:

```
Deprecation: true
Sunset: Sat, 15 Apr 2028 00:00:00 GMT
Link: <https://developers.novatrade24.com/v2/buyers>; rel="successor-version"
```

## Schema version on webhooks

Webhook payloads carry a `schemaVersion` integer separate from the URL
version. Rationale: we may need to evolve the `data` payload for a single
event type without a full major bump.

* Register the schema versions you accept via `acceptedSchemaVersions`
  on the webhook endpoint (`[1]` by default).
* When we ship `schemaVersion: 2` for an event, we dual-emit for a
  6-month deprecation window.
* Your endpoint receives the highest supported version.

## Client compatibility requirements

Any API client you build or consume must:

1. **Ignore unknown JSON fields.** Jackson `NON_NULL` + `FAIL_ON_UNKNOWN_PROPERTIES=false`;
   Pydantic with `extra='ignore'`; TypeScript with loose typing on
   response types.
2. **Accept unknown enum values.** Treat them as "opaque string" and log
   * continue. Never throw on unknown values for our documented enums.
3. **Observe response headers.** `Deprecation`, `Sunset`,
   `X-RateLimit-*` — your monitoring should surface these.
4. **Respect media types.** Always `application/json` for requests/responses
   except multipart uploads and `application/problem+json` for errors.

## Detecting deprecation in CI

Add to your CI pipeline:

```bash theme={null}
# Fail if a deprecated endpoint is in use.
resp=$(curl -sI -X GET "https://api.novatrade24.com/v1/..." -H "Authorization: Bearer $T")
if echo "$resp" | grep -qi "^Deprecation: true"; then
  echo "ERROR: using deprecated endpoint" >&2
  exit 1
fi
```

Or subscribe to the changelog feed — we publish machine-readable entries.

## Next

<CardGroup cols={2}>
  <Card title="Changelog" icon="clock-rotate-left" href="/reference/changelog">
    What changed and when.
  </Card>

  <Card title="Error reference" icon="triangle-exclamation" href="/reference/errors">
    Problem-type stability guarantees.
  </Card>
</CardGroup>