Getting Started

Versioning & Stability

TokPortal public API versioning policy, response headers, stability guarantees, and deprecation rules.

Versioning & Stability

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

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:

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:

X-TokPortal-Client: tokportal-node/0.1.0

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