Skip to main content

Changelog and deprecation policy

Versioning​

The URL path is the major-version boundary: everything documented on this site lives under /api/kanban/v1.

Compatible additions stay in v1. New endpoints, new optional request fields, new response fields, and new enum values that do not change the meaning of existing ones are released into the same /v1 surface, recorded in the OpenAPI document and in the changelog below. Build your client to tolerate them:

  • ignore response fields you do not recognize;
  • treat enums you read (but do not write) as open — handle unknown values gracefully;
  • never depend on the order of JSON object keys.

Note that this tolerance applies to what you read. What you send is strict: the API rejects unknown request properties with 400 invalid_request rather than silently ignoring them.

Breaking changes require a new major version. Removing or renaming a field, changing a type or a status code, or tightening semantics ships as /api/kanban/v2, never as an in-place change to v1. When that happens:

  • v1 and v2 run in parallel for a documented coexistence period;
  • v1 responses carry deprecation headers announcing the retirement timeline before v1 is retired;
  • the migration path is documented here.

No v2 exists today and none is planned; this is policy, not a roadmap.

Beta and general availability​

The API distinguishes two lifecycle stages:

  • Controlled beta — the current stage. The contract in the API reference is the one the API implements and is covered by automated contract tests, but access is limited: Kanban-scoped tokens can only be issued in workspaces enrolled in the beta, and the API may be restricted to specific tokens while the rollout gates close. Within the beta, the compatibility rules above already apply — we do not break the documented v1 contract casually — but the surface is not yet declared final.
  • Generally available (GA) — announced here and in the product changelog once the remaining production-readiness gates (security review, audit coverage, production promotion evidence) are complete. From GA onward, the v1 contract is frozen under the compatibility policy above: breaking changes require v2 with coexistence and deprecation headers.

If you are integrating during the beta and hit a 404 not_found on every endpoint with a valid token, your workspace or token is likely not enrolled; contact your FileTag workspace owner.

Changelog​

2026-07 — v1 controlled beta​

Initial publication of /api/kanban/v1:

Subsequent v1 additions will be listed here with their dates.