API Versioning & Migration

ReasonKit follows semantic versioning for all public APIs and protocols. This document explains how we handle changes and how you can ensure your integrations remain stable.

1. Versioning Strategy

1.1 URL Versioning (REST)

The current stable version is v1.

• Endpoint: https://api.reasonkit.sh/v1/think

1.2 Header Versioning (Optional)

You can specify a specific sub-version or experimental feature set using the X-ReasonKit-Version header.

• Header: X-ReasonKit-Version: 2026-01-24

2. Deprecation Policy

When we introduce breaking changes:

1. Announcement: We notify developers via the Changelog and developer newsletter.
2. Deprecation Window: The old version remains functional for 6 months.
3. Warning Headers: Responses from deprecated endpoints will include a Warning: 299 - "This API version is deprecated" header.
4. Sunset: The endpoint is deactivated.

3. Migration Paths

3.1 Migrating from v0.x to v1.0

The transition to v1.0 introduces the formal Reasoning Chain Schema.

Breaking Changes:

• The trace field has been renamed to steps.
• Confidence scores are now mandatory floats (0.0 to 1.0).
• total_time is now total_duration_ms.

Before (v0.x):

{
  "trace": ["thought 1", "thought 2"],
  "total_time": 1.5
}

After (v1.0):

{
  "steps": [
    { "step_id": 1, "content": "thought 1", "duration_ms": 750 },
    { "step_id": 2, "content": "thought 2", "duration_ms": 750 }
  ],
  "metrics": {
    "total_duration_ms": 1500
  }
}

4. Protocol Versioning (ThinkTools)

ThinkTool YAML/TOML definitions use a separate version field.

• version: "2.0.0" in the root of your YAML file ensures compatibility with the latest core engine logic.
• The engine will reject protocols with incompatible versions to prevent runtime logic errors.