API versioning & deprecation

Integrations are only worth building against a surface that changes predictably. This page is the policy the Rival Ads REST API and MCP server 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 and on the affected pages of the API reference.
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 and include the request path and response.