API Stability
What changes without notice, what never changes without a version, and how to write a client that survives both
FullVision's REST API, CLI, and MCP Server share one stability contract, modeled on Anthropic's API versioning. Additive changes ship continuously without a version bump; breaking changes never do.
Use it when you are writing an integration and want to know what could break it — and what never will without warning.
What may change without notice
These are backward-compatible by definition — a client that ignores what it doesn't recognize is unaffected.
- New optional request fields
- New response fields
- New enum values (report categories, error codes, event types, channel labels, …)
- New error codes
- New webhook event types
What we never change without a version
- Removing or renaming a field or endpoint
- Changing a field's type or default value
- Changing what an existing error code means
A breaking change to any of the above ships as a new version, announced ahead of time — never silently on an existing endpoint.
Client rules (tolerant reader)
Write your integration to these three rules and every additive change above is a no-op for you:
- Ignore unknown fields. Deserialize permissively — don't fail on a response key you don't recognize.
- Never depend on field order. JSON object key order and array element order (unless explicitly documented, e.g. "ranked by revenue desc") carry no meaning.
- Treat unknown enum values as
"other". New channels, error codes, and event types will appear over time — default to a catch-all branch instead of an exhaustive switch that throws.
This is the same contract webhooks follow — see Webhooks for the event-type rule in practice.