# 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 you upgrade. - Human page: https://mailrith.com/developers/versioning - Markdown page: https://mailrith.com/developers/versioning.md - Category: API Concepts - Reading time: 5 min read - Last updated: 2026-07-13 - Related keywords: Versioning, Versioning developer docs, API Concepts, API Concepts developer docs, Mailrith developer docs, Mailrith public API, Use the Path Version as the Contract Boundary, Plan Upgrades Deliberately, API Reference, Testing the API, Quickstart ## AI Agent Notes - Use this page as implementation guidance, then validate exact endpoint fields against the OpenAPI document. - Keep API keys server-side and workspace-scoped unless a guide explicitly says otherwise. - Do not invent privacy, consent, or lawful-basis evidence. Send only fields that appear in the OpenAPI schema for the endpoint you are using. ## 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 version is part of the path. The current public API contract is under `/v1`, so include `/v1` in every API call. Path versioning gives your integration a clear contract boundary. If a future release has a breaking change, Mailrith will put that change behind a new versioned path instead of silently changing the version your code already uses. Do not build clients with unversioned paths such as `/subscribers` or `/api/subscribers`. In every environment, use the documented base URL and the documented versioned path. 1. In production, set your base URL to `https://api.mailrith.com/v1`. 2. When you test the worker locally, set your local base URL to `http://localhost:8787/v1`. 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 API version that your integration calls. 5. Do not use unversioned paths and `/v1` paths in the same integration. 6. Record the API version in your integration README, runbook, or customer setup notes so future maintainers know which contract the integration uses. - 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. - Use the OpenAPI document for the API 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, handle 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 the change deliberately. The generated OpenAPI document is machine-readable. Your team can use schema diff tooling in CI before adopting a future API version to catch renamed fields, new required fields, removed enum values, or changed response shapes. If you use an SDK, update the SDK only after you confirm which public API version the SDK targets. Generated SDKs make calls easier, but the versioned API contract still defines what the server accepts. - Record which API version each integration uses. - Keep one upgrade branch or test environment where you can compare old API behavior with new API 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 the API reference to find 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): You can test Mailrith's public API manually with local curl requests or automatically with the integration suite. This page shows the repo-native commands for both testing 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 steps needed to create a working subscriber sync.