API Versioning and Deprecation

Agents and CI systems integrate against a surface that must not change without warning. This page states the rules Reoclo follows.

Versioning

• Machine-facing endpoints carry the version in the URL path. The automation API lives at /api/automation/v1/. A breaking change ships as a new path version. The old version keeps working through its deprecation window.
• Unversioned endpoints (webhooks, OAuth, /.well-known/ documents, public status pages) change only in backward-compatible ways.
• Every response from api.reoclo.com carries an X-API-Version header with the deployed platform version.
• The machine-readable specification lives at https://api.reoclo.com/openapi.json. Its info.version field matches the deployed version.

What counts as a breaking change

These changes ship as a new path version:

• Removal of an endpoint, a request field, or a response field
• A change to the type or the meaning of a field
• A new required request field
• A stricter authentication or scope requirement

These changes do not:

• A new endpoint
• A new optional request field or a new response field
• A new value in an enum field. Write clients to tolerate unknown values.

Deprecation signals

Before Reoclo removes an endpoint, three signals appear:

1. Responses from the endpoint carry a Deprecation header and a Sunset header (RFC 8594) with the removal date.
2. The table in the Deprecated surfaces section lists the endpoint and its removal date.
3. The What’s New changelog in the dashboard announces the change.

The window between the first signal and removal is at least 90 days.

Deprecated surfaces

Surface	Replacement	Sunset date
/mcp/* path prefix on api.reoclo.com	The same paths without the /mcp prefix	Not scheduled

Rate limit signaling

API responses carry the standard RateLimit and RateLimit-Policy fields next to the legacy X-RateLimit-* set. See API Overview for the format and the limits.