Stashr API versioning and deprecation policy

This page is the contract an integration can rely on: what can change in the Stashr API without warning, what cannot, and exactly how you will hear about anything being retired. It applies equally to the REST API, the CLI built on it, and the MCP server.

Versioning scheme

The API is versioned in the URL path. Everything documented today lives under /v1:

https://stashr.me/v1

An API key or OAuth token works across every change within a major version. There is no version header to send and no date-pinning; the path is the version.

What can change without notice

These are backwards-compatible and can ship at any time inside /v1:

• New endpoints.
• New optional request fields and query parameters.
• New fields in responses.
• New values in open enumerations, such as a new platform id or content type when Stashr adds a source.
• New filters and new values for existing filters.
• Looser validation (accepting something that was previously rejected).

Write clients accordingly: ignore response fields you do not recognize, treat enumerations as open, and never rely on the order of keys in an object.

What counts as breaking

Any of the following is a breaking change and ships only as a new major version (/v2) alongside the old one, never in place:

• Removing or renaming an endpoint, field, or parameter.
• Changing a field's type or meaning.
• Tightening validation so previously valid requests fail.
• Changing the error envelope or the meaning of an error.code.
• Changing authentication or scope requirements for an existing operation.

How deprecations are announced

When an endpoint, parameter, or whole version is scheduled for removal, you will see it in the responses themselves, so an agent can detect it without reading a changelog:

The same dates are posted on the changelog, and the OpenAPI description marks the affected operations with deprecated: true. The policy is also published machine-readably as x-deprecation-policy in /openapi.json.

Guarantees

• At least six months of overlap. A deprecated major version keeps working for a minimum of six months after its replacement is generally available.
• No silent removals. Nothing disappears without first carrying the headers above.
• Security fixes are the one exception. If a change is required to close a vulnerability, it may ship faster; it will still be announced on the changelog.

Nothing is deprecated today, so no current response carries these headers. Checking for them on every response, and treating their appearance as the signal to plan a migration, is the recommended client behavior.

Where to go next