Versioning and deprecation

How the API and MCP tools change, and how much notice you get before anything is removed.

The REST API is versioned in the path. Every REST endpoint lives under https://api.acquisity.ai/v1, and the OpenAPI description for it is at https://api.acquisity.ai/openapi.json.

The MCP server (https://api.acquisity.ai/mcp) and its discovery card (/mcp/server-card and /.well-known/mcp/server-card.json) are not under /v1. The MCP server reports its version in the initialize response, and its tools follow the rules below.

What can change without notice

These changes are backwards compatible, so they ship to /v1 without a new version:

New endpoints, MCP tools, optional request fields and query parameters.
New fields in responses. Ignore fields you don't recognise.
New values in an enum that is documented as open, and new error codes.
Higher rate limits.

What needs a new version

Breaking changes include removing or renaming an endpoint, MCP tool or field, making an optional field required, and changing a field's type or meaning.

REST API: a breaking change ships as a new path version (/v2) alongside /v1.
MCP server: there is one endpoint, https://api.acquisity.ai/mcp, and it has no path version. A breaking tool change raises the server's major version, which the server reports in its initialize response (serverInfo.version), and follows the MCP tool rules below. Check serverInfo.version and the live tools/list rather than assuming a fixed tool set.

How we deprecate

Whatever is going away, we announce it on this page at least 90 days before removal.

REST endpoints and versions

Responses from a deprecated endpoint carry a Deprecation header (RFC 9745) with the date it was deprecated, a Sunset header (RFC 8594) with the removal date, and a Link header with rel="deprecation" pointing to the migration notes.
The OpenAPI description marks the operation deprecated: true.
After the sunset date the endpoint, or the whole retired version, returns 410 Gone.

Fields

A field that is going away is marked deprecated: true in the OpenAPI description, and the responses that still include it carry the Deprecation and Sunset headers. After the sunset date the field is no longer returned, or is ignored in requests. The endpoint itself keeps working.

MCP tools

A tool that is going away says so at the start of its description, with the removal date, and keeps working until then. After that date it is no longer listed in tools/list, and calling it returns a tool error. The /mcp endpoint itself never returns 410, so other tools are not affected.

Deprecated in /v1 today:

campaignContext on the AI lead-search endpoints (.../leads/search/ai) is ignored. Describe who to target in brief.

For AI agents

Check for a Deprecation or Sunset header on any response, and tell the person if you see one. MCP tool names and input schemas only change in a backwards compatible way within the same server version.