> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shipstar.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Shipstar API Versioning & Deprecation Policy

> How the Shipstar API is versioned, what counts as a breaking change, and how deprecations are announced

## Versioning scheme

The Shipstar REST API is versioned in the URL path:

```
https://api.shipstar.ai/api/v1
```

`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](https://shipstar.ai/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](https://www.rfc-editor.org/rfc/rfc8594)) with that date:

   ```
   Deprecation: true
   Sunset: Sat, 01 Jan 2028 00:00:00 GMT
   Link: <https://docs.shipstar.ai/api-reference/versioning>; rel="sunset"
   ```

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](https://shipstar.ai/feed.xml) for announcements.