Source: https://developers.tokportal.com/versioning/
Markdown: https://developers.tokportal.com/versioning.md

# Versioning & Stability

TokPortal's public API is versioned as a stable contract. The current public API version is:

```http
X-TokPortal-API-Version: 2026-05-25
X-TokPortal-API-Stability: stable
X-TokPortal-Request-ID: req_...
```

Every public API response includes these headers, including errors, CORS preflight responses, and idempotency replays.

Authenticated API responses also include rate limit metadata:

```http
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1779724800
```

Use `X-TokPortal-Request-ID` to correlate client-side failures with TokPortal logs. You can optionally send `X-Request-ID` on a request; if it is a safe ASCII value up to 128 characters, TokPortal echoes it as `X-TokPortal-Request-ID`. Otherwise TokPortal generates a `req_` identifier.

429 responses include `Retry-After`.

## Compatibility Policy

We treat the public API as backwards-compatible by default.

Non-breaking changes can ship inside the current version:

- New endpoints
- New optional request fields
- New response fields
- New enum values when clients should already tolerate unknown values
- New SDK, CLI, MCP, OpenAPI, or documentation surfaces generated from the schema

Breaking changes require a new public API version and changelog entry before adoption:

- Removing or renaming an endpoint
- Removing, renaming, or changing the meaning of a response field
- Making an optional request field required
- Changing authentication semantics
- Changing error codes in a way that breaks existing retry or recovery logic

## Deprecations

Deprecated fields or endpoints remain documented during the migration window. The changelog is the source of truth for deprecation timelines and replacement paths.

## Client Identification

Generated SDKs, CLI, and MCP clients send:

```http
X-TokPortal-Client: tokportal-node/0.1.1
```

The exact value changes by surface, for example `tokportal-node/0.1.1`, `tokportal-cli/0.1.2`, or `tokportal-mcp/1.15.0`. Custom clients can send their own product/version string for support and diagnostics.