Versioning

The Factuarea API follows a flat-versioned URL policy (/v1) combined with an optional date header for non-breaking evolution. The commitment is clear: once published, /v1 stays stable. Incompatible changes require /v2.

URL version

https://api.factuarea.com/v1/...

v1 is our first public version (May 2026). No prior versions are accessible.

When /v2 is designed:

• /v1 and /v2 coexist for at least 12 months.
• /v1 routes do not change in that window (no payloads, status codes, fields or semantics).
• Email notices to developers with active keys, banner in the docs, headers on responses (see below).

Factuarea-Version header

Factuarea-Version: 2026-05-15

Optional. If you send it, you pin the behavior of the subset of endpoints that receive non-breaking incremental improvements (new response fields, new optional parameters). Without the header → you get the latest calendar version.

Errors

• Malformed value (not YYYY-MM-DD, e.g. 2026-05 or 15/05/2026) → 422 invalid_param_format with param: "Factuarea-Version".

In v1 the header only validates its format and is recorded for auditing; it does not yet change any response. A well-formed but future or past date is accepted without error.

What is breaking?

We consider breaking (forbidden in /v1):

• Renaming / removing JSON response fields.
• Changing a field's type (string → int).
• Changing the type/code of an existing error envelope.
• Changing status codes (e.g. returning 201 where it used to be 200).
• Making a previously optional request field required.
• Changing the format of an identifier (UUID v7 stays UUID v7).
• Removing an endpoint without a documented replacement and migration window.
• Changing the document state machine semantics.

We consider non-breaking (allowed without a new version):

• Adding new fields in responses.
• Adding optional parameters in requests.
• Adding new endpoints.
• Relaxing restrictions (raising a limit, accepting more formats).
• Adding new enum values to fields that aren't critical to client-side state machines.
• Improving error messages (changes message, not type/code).

Deprecation policy

When an endpoint or field is marked deprecated within /v1 (e.g. a legacy alias replaced by a canonical version):

• Email notice to developers with active keys affected.
• Banner on docs.factuarea.com with the changelog.
• Headers on every response of the deprecated endpoint for at least 12 months before retirement (which only happens in /v2):

Deprecation: true
Sunset: Wed, 15 May 2027 00:00:00 GMT
Link: <https://docs.factuarea.com/changelog#v1-deprecations>; rel="deprecation"
Link: <https://docs.factuarea.com/guides/migration-from-holded>; rel="alternate"

• In /v1 the endpoint keeps working until the launch of /v2. The headers warn.
• In /v2 the endpoint is retired / replaced. The window between the first warning and /v2 is ≥ 12 months.

Migration between versions

Each migration (v1 → v2) ships with:

• A dedicated guide at docs.factuarea.com/guides/migration-v1-v2.
• Field-to-field and endpoint-to-endpoint mapping.
• Operational recommendations (keep both keys, dual-write during the transition).
• Webhooks: old events keep their shape; new events live in their own version declared in the payload.

Changelog

Every /v1 change (new field, deprecation, new event, validation fix) is published in Changelog with tags:

• feature — new field / endpoint / event.
• fix — bug fix.
• deprecation — field or endpoint marked obsolete (still active in /v1).
• breaking — only appears in /v2, never inside /v1.
• security — fix with security implications. Read it first.

Subscribe to the RSS feed at https://docs.factuarea.com/changelog.rss or follow @factuarea on X for announcements.

Stability commitment

That's the guarantee. Any exception will be communicated with generous timelines.