Versioning & deprecation

The API is path-versioned. There is currently one version: /v1 — every endpoint lives under https://api.actuallycare.com/v1.

What we change without notice (non-breaking)#

These can happen at any time and your integration must tolerate them:

• New endpoints, and new optional request parameters
• New fields in response objects (parse what you need; ignore unknown fields)
• New enum values in fields that are documented as open-ended (e.g. new status values on new features)
• New webhook event types (subscribe explicitly; ignore types you don't handle)
• Documentation-only changes to the OpenAPI spec (descriptions, examples)

What counts as breaking#

Anything that would make a working integration stop working:

• Removing or renaming an endpoint, request parameter, or response field
• Changing a field's type or meaning
• Tightening validation so previously-valid requests fail
• Removing an enum value or changing error code strings

Breaking changes ship under a new version path (/v2), not in place. /v1 keeps working while any published version is supported.

How deprecations are communicated#

No /v1 endpoint is deprecated today. When a deprecation is scheduled it will be announced in the changelog, marked deprecated: true in the OpenAPI spec, and given an explicit sunset date in both places — with a migration path documented before the clock starts.

MCP tools#

MCP tools follow the same philosophy at the tool level: tool inputs only gain optional parameters in place, and renamed tools keep their old name callable as an alias (see the aliasOf field in tools.json). New tools appear without notice — enumerate them via tools/list or the discovery tools rather than hardcoding the tool set.