Build my stackAPI Versioning & Deprecation Policy
GoPickStack provides a stable, predictable API contract so developers, MCP integrations, and autonomous AI agents can build without unexpected breaking changes.
1. Versioning Architecture
We use URL path prefixing for major version boundaries (e.g. /api/v1/) combined with standard HTTP response headers for semantic minor versions. Non-breaking additive changes (such as new tool fields, new categories, or optional query parameters) are released continuously under the current major version without requiring endpoint migration.
Breaking changes, route restructuring, or field deletions increment the URL prefix (e.g. /api/v1/ to /api/v2/).
Prior major versions remain fully functional for a minimum of 180 calendar days after the release of a replacement version.
2. Deprecation Signaling & HTTP Headers
When an endpoint or version enters the deprecation phase, our servers automatically emit IETF standard HTTP headers on every response:
| Header | Example Value | Purpose |
|---|---|---|
| API-Version | 1.0.0 | The exact semantic release serving the request. |
| Deprecation | @false / @2026-09-01 | Indicates active status (@false) or the timestamp when deprecation started. |
| Sunset | Sat, 01 Sep 2029 00:00:00 GMT | The final date after which the endpoint will return HTTP 410 Gone. |
| Link | <.../deprecation-policy>; rel="deprecation-policy" | Direct link to this policy document for automated scrapers. |
3. Notice & Communication Channels
Deprecation announcements are published across three independent channels:
- In-Band Headers: Automated agents parsing HTTP responses detect the
DeprecationandSunsetheaders in real time. - Developer Portal: The Developer Hub and Changelog reflect all planned deprecation timelines.
- OpenAPI Specs: The official OpenAPI 3.1 specification at
/api/openapi.jsonincludes deprecation annotations and migration paths.
4. Support & Feedback
Have questions about an upcoming migration or need guidance integrating the MCP server with your custom agents?