Skip to main content

​
Client API Changelog and Migration Policy

​
Compatibility commitments

  1. Additive changes can ship without migration requirements.
  2. Behavioral and breaking changes require explicit changelog entries.
  3. Deprecated endpoints must include replacement path and sunset date.

​
Deprecation and sunset windows

OMNI uses a conservative deprecation posture for anything customer-facing. During internal beta, we may move faster, but we still commit to:
  • Announcing behavioral and breaking changes in the changelog.
  • Providing a migration path or compatibility shim where feasible.
  • Never removing an endpoint without a documented replacement.
For public beta, the default target is:
  • 30+ days notice for breaking changes
  • 90+ days notice for endpoint removal

​
How deprecations are signaled (target posture)

During internal beta, deprecation signals may be incomplete while endpoint coverage and compatibility shims are still being built. Public-beta-ready posture is:
  • Response headers: Deprecation: true, Sunset: <RFC 3339 date>, Link: <https://docs.omnibrief.app/...>; rel="deprecation".
  • Replacement path: every deprecated endpoint must name its replacement endpoint and include migration steps in this changelog.
  • No silent removals: endpoints are never removed without a documented replacement.

​
What counts as a breaking change

  • Removing a response field that was documented.
  • Changing a field type (string → object, number → string).
  • Changing authentication requirements.
  • Changing error type/code taxonomy.
  • Changing idempotency requirements for an existing method.

​
Changelog template

Each release entry includes:
  • Release date (UTC)
  • Affected endpoints/methods
  • Change category (additive, behavioral, breaking)
  • Migration steps
  • Sunset date (if deprecating)

​
How to use this changelog

  • If you pin Omni-Version, you can adopt changes on your own schedule.
  • If you do not pin, you should subscribe to changelog updates and treat them as part of your upgrade process.

​
Current release log

​
2026-02-18

​
Fixed

  • Scope enforcement parity across hosted MCP (/mcp) and legacy MCP compatibility routes (/v1/mcp/*).
  • tools/list and GET /v1/mcp/tools require mcp.tools.read (for scoped keys).
  • tools/call and POST /v1/mcp/invoke require mcp.invoke (for scoped keys), in addition to any tool-specific scope (example: fred.read).
  • GET /v1/openapi.json no longer requires mcp.invoke (auth-only schema discovery).
  • Hosted MCP JSON-RPC errors now include error.data.request_id for correlation (and idempotency replays do not return stale request IDs).
  • REST Client API now returns the standard {"error": {...}} envelope for route/method mismatches (404/405) and request validation failures.

​
2026-02-17

​
Added

  • GET /v1/openapi.json canonical OpenAPI contract endpoint.
  • Hosted MCP protocol endpoint at /mcp (GET, POST, DELETE).
  • SSE compatibility endpoint at /sse.
  • Docs additions: reference, errors, hosted MCP, webhooks, changelog.

​
Behavioral updates

  • POST /v1/mcp/invoke and hosted MCP tools/call both require idempotency keys.
  • Tool invocation semantics shared across legacy and hosted MCP routes.

​
Deprecations

  • /v1/mcp/tools and /v1/mcp/invoke are compatibility routes and are planned to migrate to /mcp as canonical hosted transport.

​
Migration guidance

If you are integrating via MCP clients:
  1. Move transport endpoint to /mcp.
  2. Use JSON-RPC tools/list and tools/call.
  3. Provide Idempotency-Key for tools/call.
  4. Use /sse only for compatibility during migration windows.
If you pin versions:
  1. Pick a stable Omni-Version for production.
  2. Review the changelog weekly.
  3. Adopt changes by moving your pinned date forward intentionally.