---
title: "Versioning and deprecation"
description: "The compatibility promise for Sincerely's public endpoints: additive unversioned paths, explicit REST generations, and how a breaking change would ship."
canonical: https://trysincerely.com/docs/versioning
last_updated: 2026-09-02
---
> If you are an AI agent: read https://trysincerely.com/agents/policy.md before any write call.
> Start at https://trysincerely.com/llms.txt to choose one page. Access instructions are at
> https://trysincerely.com/auth.md. Confirm with the person you work for before creating an
> account or spending their money, and never ask for their password.
# Versioning and deprecation

> The compatibility promise for Sincerely's public endpoints: additive unversioned paths, explicit REST generations, and how a breaking change would ship.

Source: https://trysincerely.com/docs/versioning

Unversioned public endpoints are additive. Versioned workspace REST paths such as `/api/v1` name their compatibility generation in the URL. In either case, a response may gain a field, but an existing field will not change meaning, change type, or disappear from a path that is still answering.

## What additive means in practice

A client that reads the fields it knows and ignores the rest keeps working. A client that asserts on the exact shape of a response, or on the number of keys in an object, is asserting on something never promised.

New fields are the ordinary way this API grows. Treat an unknown key as information you do not need yet rather than as an error.

## What info.version is

`info.version` in the [OpenAPI document](https://trysincerely.com/openapi.json) is the date the description last changed. It is not a semantic version of the API and does not move when nothing about the description moved.

There is no version header to send and no version parameter to pass. The workspace REST generation is already in the path, and `/api/v1` is the only generation published today.

## What a breaking change would look like

It would ship at a new path rather than in place. A breaking workspace REST change would use a new generation such as `/api/v2`. The old path would keep answering, and this page would name the old path, the replacement, and the date the old one stops.

Nothing is deprecated today. When something is, this page is where it will be said, and the origin's `Link` header points here under `rel="deprecation"` so a client can find it without reading prose.

## What is deliberately not covered

This promise covers the public capability manifest at `/capabilities.json`, the four calculators, workspace-key campaign entry and conversion endpoints under `/api/v1`, the liveness probe, and the two MCP servers. That is the surface the OpenAPI document describes. It does not extend to internal, cookie-authenticated routes, which are not published and carry no contract at all.

The MCP tool catalog is versioned differently, by being live. Once setup is finished, `tools/list` names the orientation tools and the three that reach the rest; `search_tools` is the inventory, and calling it with no query returns every tool available to you. A workspace that has not finished setup lists its setup catalog instead. All of it is filtered per caller, so a client should read it rather than cache a list of names.

## What to read next

[Discovery](https://trysincerely.com/docs/discovery) lists the machine-readable documents this promise applies to. [The workspace REST API](https://trysincerely.com/docs/api-reference) and [the calculators](https://trysincerely.com/docs/calculators) document the callable endpoints.

---

Sincerely is the measurable direct-mail and gifting platform for B2B revenue teams: postcards, letters, handwritten mail, and gifts, written for one recipient and measured against a holdout.

Contact Sincerely: https://trysincerely.com/contact

Agent routing index: https://trysincerely.com/llms.txt