Skip to main content

​
Versioning scheme

The Shipstar REST API is versioned in the URL path:
v1 is the current stable version. You never need to send a version header — the path is the contract. The MCP server (https://mcp.shipstar.ai/mcp) follows the same policy: tools may gain new optional parameters at any time, but existing tools and parameters are not removed or repurposed without the deprecation process below.

​
What we may change without notice

Additive, backwards-compatible changes can ship at any time within v1:
  • New endpoints, and new optional query or body parameters on existing endpoints
  • New fields in response objects (build clients that ignore unknown fields)
  • New enum values in fields documented as extensible
  • New response headers

​
What counts as a breaking change

Breaking changes only ship in a new version path (e.g. /api/v2), never silently within v1:
  • Removing or renaming an endpoint, parameter, or response field
  • Changing a field’s type or meaning
  • Making an optional parameter required
  • Tightening authentication or narrowing a scope in a way that rejects previously valid requests

​
How deprecations are announced

When an endpoint or field is scheduled for removal:
  1. The changelog and this documentation announce the deprecation and its replacement.
  2. Affected endpoints start returning a Deprecation header, and — once a removal date is fixed — a Sunset header (RFC 8594) with that date:
  3. Deprecated v1 surface stays available for at least 6 months after the announcement before removal.
No endpoint currently carries a Deprecation or Sunset header — nothing is deprecated today.

​
Recommendations for clients and agents

  • Key your integration to the versioned base URL, not to undocumented behavior.
  • Ignore response fields and headers you don’t recognize.
  • Watch for Deprecation/Sunset headers in responses and subscribe to the changelog feed for announcements.