# API versioning & deprecation

> **Title:** API versioning & deprecation — Rival Ads Docs
> **Description:** How the Rival Ads REST API and MCP server are versioned, what counts as a breaking change, and how deprecations are announced.
> **Canonical URL:** https://www.rivalads.io/docs/api-versioning
> **Note:** This is the markdown twin of https://www.rivalads.io/docs/api-versioning. Append `.md` to any Rival Ads page URL to get markdown.

---

Integrations are only worth building against a surface that changes predictably. This page is the policy the Rival Ads [REST API and MCP server](/docs/developer-api) follow.

## How the API is versioned

The REST API carries its version in the URL path: the current and only version is `v1`, at `https://www.rivalads.io/api/v1`. There is no version header to send.

The remote MCP endpoint (`https://www.rivalads.io/api/mcp`) is not path-versioned; its tools follow the compatibility rules below.

## What can change without notice

`v1` is stable, and changes within it are **additive only**. Any of the following may appear at any time and are not considered breaking:

- new endpoints, and new optional request parameters;
- new fields on response objects;
- new values in enumerated fields (for example a new channel or a new sync status);
- new MCP tools, and new optional tool inputs.

Build clients that tolerate unknown fields and unknown enum values instead of rejecting them.

## What counts as breaking

Removing or renaming an endpoint, field or MCP tool, changing a field's type or meaning, tightening validation on existing input, or changing an error code for an existing failure. Breaking changes never land inside `v1` — they ship as a new version path (`/api/v2`) while `v1` keeps working in parallel.

## How deprecations are announced

When an endpoint, field or version is scheduled for removal:

1. The change is announced in the [changelog](/docs) and on the affected pages of the [API reference](/api/docs).
2. Affected responses carry a `Deprecation` header immediately, and a `Sunset` header naming the removal date once one is set.
3. At least **six months** pass between the announcement and the removal, and workspaces with developer credentials that recently used the affected surface are notified by email.

Nothing has been deprecated so far; `v1` has no announced end of life.

## Questions

If a change appears to break your integration inside `v1`, that is a bug — report it to [support@rivalads.io](mailto:support@rivalads.io) and include the request path and response.