API + MCP reference

Versioning policy

The URL prefix /v1 is our stability contract with you. Anything we ship inside it is additive — your client doesn't break. Anything that would break a working client ships as /v2 on a new prefix.

We have not shipped a breaking change in v1. The only path past this contract is a tagged /v2 release with a published deprecation window for /v1.

What v1 promises

  • Existing endpoints keep their URLs, HTTP methods, and response shapes.
  • Existing fields on responses keep their names, types, and nullability.
  • Existing error error slugs keep their meanings.
  • Existing webhook event types keep their payload shape and HMAC signing scheme.
  • Existing MCP tool names keep their JSON-schema shape.

Additive vs breaking

Inside v1 we ship additive changes at any time without a version bump:

Additive · ships in v1
  • New endpoints
  • New optional query / body params
  • New fields on existing responses
  • New error slugs
  • New webhook event types
  • New MCP tools
  • New tier in pricing (with new fields, never repurposed ones)
  • New signals in the score
Breaking · would ship in v2
  • Renaming or removing a field
  • Changing a field's type or nullability
  • Removing an endpoint
  • Changing an endpoint's URL or method
  • Changing the meaning of an existing error slug
  • Changing the HMAC signing scheme
  • Renaming or removing an MCP tool (we'd alias first, then break in v2)

How v2 would ship

If a breaking change is unavoidable — say a fundamental schema rewrite — we'd ship it on a new URL prefix /v2 and keep /v1 running side-by-side. Your existing client keeps working; you migrate when it's convenient.

Same applies to MCP and webhook contracts: a breaking change would ship as a new tool name or event type, with the old surface kept alive for the deprecation window.

Deprecation window

If we ever deprecate a piece of v1 (intent to remove in a later v2), we'll commit to at least a 180-day deprecation window. Deprecation is announced in three places:

  • The changelog (dated entry tagged [deprecation]).
  • A Deprecation response header on every call to the deprecated endpoint, with an RFC 8594-style timestamp.
  • Email to every active tenant at first announcement and at T-30 days.

As of today () there are no active deprecations.