TradeInsight
Lifecycle & Stability

API Versioning & Deprecation Policy

Effective: August 2026 · Version 2.0.0 · Governed by Mohd Shubair

1. Stability Guarantee for AI Agents & Developers

TradeInsight AI commits to providing predictable, backward-compatible API surfaces. AI agents and automated algorithmic workflows rely on stable contracts. We never introduce breaking schema changes or remove endpoints on active API versions without following the formal deprecation timeline outlined below.

2. Versioning Strategy

TradeInsight AI uses URL-based semantic path versioning:

https://tradeinsight.shubair.in/api/v1/...
  • Non-breaking enhancements (adding new fields, optional parameters, new endpoints) are introduced directly into the current version (v1).
  • Breaking changes (removing fields, altering required parameters, changing response status codes) trigger a new major version (v2).

3. Deprecation Timeline & Protocol

When an endpoint or schema is marked for deprecation:

  1. Minimum 6 Months Notice: The endpoint remains fully operational for at least 180 calendar days from the formal deprecation announcement.
  2. Machine-Readable HTTP Headers (RFC 8594): Responses from deprecated endpoints include standard RFC headers:
    Deprecation: @1771891200
    Sunset: Wed, 24 Feb 2027 00:00:00 GMT
    Link: <https://tradeinsight.shubair.in/docs/deprecation-policy>; rel="deprecation"
  3. OpenAPI Specification: The endpoint is marked with "deprecated": true in /openapi.json.
  4. Developer Notification: Documented in llms.txt, /docs/api, and sent via developer communications.

4. Sunset & Retirement

After the Sunset date passes, retired endpoints will return HTTP 410 Gone or HTTP 404 with structured JSON error responses directing agents to the current replacement endpoint:

{ "error": "Endpoint Sunset", "message": "This API endpoint has been retired.", "code": "ENDPOINT_SUNSET", "hint": "Please migrate to the v2 equivalent documented at https://tradeinsight.shubair.in/docs/api." }

5. Current Deprecated Endpoints

POST /api/v1/auth/login-legacy
Deprecated in favor of POST /api/v1/auth/login. Returns RFC Deprecation and Sunset headers.

6. Questions & Support

For deprecation migration assistance, contact Mohd Shubair at shubair313@gmail.com or open an issue on GitHub.