# Versioning



> Mailrith versions the public API in the path. This guide explains the `/v1` contract boundary, which base URLs to call, how to avoid unversioned paths, and how to compare future API versions before upgrading.



- Human page: https://mailrith.com/developers/versioning

- Category: API Concepts

- Reading time: 5 min read



## What this guide covers

Pin clients to the `/v1` path contract and plan future upgrades with the OpenAPI document.



## Use the Path Version as the Contract Boundary

Mailrith's public API is versioned in the path. The current public contract lives under `/v1`, so call `/v1` explicitly.

Path versioning gives your integration a clear contract boundary. A future breaking change belongs behind a new versioned path rather than silently changing the behavior of the version your code already uses.

Do not build clients against unversioned guesses such as `/subscribers` or `/api/subscribers`. Use the documented base URL and versioned path in every environment.

1. Set your base URL to `https://api.mailrith.com/v1` in production.
2. Set your local base URL to `http://localhost:8787/v1` when testing the worker locally.
3. Use the same versioned base URL in REST calls, SDK configuration, generated clients, and agent tools.
4. Download or load the OpenAPI document for the same version you call.
5. Do not mix unversioned paths with `/v1` paths in the same integration.
6. Record the API version in your integration README, runbook, or customer setup notes.

- Production API base: `https://api.mailrith.com/v1`.
- Local API base, when the worker is running locally: `http://localhost:8787/v1`.
- Use the same versioned path in REST calls, SDK configuration, generated clients, and agent tooling.
- Treat the OpenAPI document for the version you call as the source of truth for request and response shapes.

**Version Metadata**

```bash
curl https://api.mailrith.com/v1
```

## Plan Upgrades Deliberately

When Mailrith adds a future API version, treat the upgrade like any other production integration change. Read the new docs, compare the OpenAPI document, update your client in a test environment, and then roll out deliberately.

The generated OpenAPI document is machine-readable, so your team can use schema diff tooling in CI before adopting a future version. This is useful for catching renamed fields, new required fields, removed enum values, or changed response shapes.

For SDK users, update the SDK only after confirming which public API version that SDK targets. Generated SDKs are meant to make calls easier, but the versioned API contract still decides what the server accepts.

- Record which API version every integration uses.
- Keep one upgrade branch or test environment where you can compare the old and new behavior.
- Run real examples from your integration, not only generated schema checks.
- Deploy upgrades gradually when the integration affects subscriber imports, sends, automations, or webhooks.

> Download the developer-site copy of the OpenAPI document or call the public `GET /v1/openapi.json` endpoint directly from your tooling.



## Related Guides

- [API Reference](https://mailrith.com/developers/api-reference.md): The full API reference is generated from the same public contract used by the API worker and SDK tooling. Use it for exact paths, methods, parameters, request schemas, response schemas, operation IDs, and the downloadable OpenAPI document.

- [Testing the API](https://mailrith.com/developers/testing-the-api.md): Mailrith's public API can be tested manually with local curl requests and automatically through the integration suite. This page shows the repo-native commands for both paths.

- [Quickstart](https://mailrith.com/developers/quickstart.md): Start with one workspace API key, one authenticated request, and the generated response envelope. This page covers the minimum needed to go from zero to a working subscriber sync.