# Moveezi API versioning and deprecation policy

Applies to every endpoint under `https://www.moveezi.com/api/`, to the MCP server at
`https://www.moveezi.com/mcp`, and to the markdown and discovery files. Last reviewed
2026-09-04.

## Versioning

The version is in the path: `/api/v1`. The MCP server negotiates its protocol
version per request and currently supports 2026-07-28, 2025-11-25, 2025-06-18,
2025-03-26 and 2024-11-05.

## What will not change without notice

Within a major version this API changes **additively only**. We may add
endpoints, add optional parameters, and add fields to responses. We will not,
without going through the notice period below:

- remove or rename an endpoint, a parameter or a response field
- change the type or meaning of an existing field
- make an optional parameter required
- remove a value from an enum, or change what an existing value means
- tighten a rate limit

Adding a field to a response is not a breaking change. Parse responses so an
unknown field is ignored rather than fatal.

## Notice period

When an operation is going to be withdrawn:

1. It is marked `deprecated: true` in `https://www.moveezi.com/openapi.json`, with the
   replacement named in its description.
2. Its responses carry `Deprecation: <http-date>` (RFC 9745) and
   `Sunset: <http-date>` (RFC 8594), and a `Link` header with
   `rel="deprecation"` pointing at this document.
3. Both dates are at least **six months** apart, and the sunset date is at
   least six months from the day the header first appears.
4. The old and the new behaviour run in parallel for the whole notice period.

**Nothing is deprecated today.** No response from this API currently carries a
`Deprecation` or `Sunset` header. If you are reading one, it is real.

## How to check

- `https://www.moveezi.com/openapi.json` - the current surface. Any `deprecated: true`
  operation is on the way out.
- Watch for `Deprecation` and `Sunset` response headers on the operations you
  call. An agent that reads them gets six months of warning without asking
  anyone.
- `https://www.moveezi.com/auth.md` - authentication, which is none, and is not going to
  change for the public API.

## Limits

Reads: 120 requests per minute per IP. `POST /api/lead`: 5 per hour per
IP. Both report `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and
`RateLimit-Policy` on every response, and `Retry-After` on a 429. A limit will
only ever be raised without notice, never lowered.

## Sandbox

`POST https://www.moveezi.com/api/v1/lead/validate` runs a lead payload through exactly the
same rules as `POST /api/lead` and writes nothing: no CRM record, no email, no
budget consumed. Use it before submitting anything for real.

## Contact

Breaking something you depend on is a bug on our side. sales@moveezi.com.