Versioning and compatibility

API v3 evolves along four independent axes. A release can change one of them without touching the others, and you track each one through a different channel.

The four axes

Compatible changes

These changes fit within the same major version (3.x) and do not break existing integrations:

• a new operation;
• a new optional request field;
• a new response field;
• a new value in an enum marked x-extensible: true (treat unknown values as opaque);
• a new filter, a new header, or relaxed validation;
• a new error code under an already documented status.

Example: a resource response gains a new field. Clients that already read the JSON keep working, because nothing they received before is missing.

{
  "id": "prd_01J9X8Y7Z6A5B4C3D2E1F0G9H8",
  "object": "product",
  "name": "Curso de Marcenaria",
  "status": "published",
  "visibility": "public"
}

Breaking changes

These changes only ship in v4:

• removing or renaming an operation, field, parameter, or enum value;
• changing the type, format, or meaning of a field;
• making an optional field required;
• changing the HTTP status or the code of an already documented case;
• changing the default ordering of a list;
• lowering a limit (page size, batch size, upload size);
• adding a value to an enum marked x-extensible: false.

Example: renaming name to title in the same response breaks every client that reads name. A change like this only exists under another major version, never within /api/v3:

{
  "id": "prd_01J9X8Y7Z6A5B4C3D2E1F0G9H8",
  "object": "product",
  "title": "Curso de Marcenaria",
  "status": "published"
}

Each enum declares its policy in the OpenAPI document. Closed enums (x-extensible: false) include state enums such as publication status, operation.status, and credential.status, as well as format and denial_reason. Open enums (x-extensible: true) include event type and operation type, and can gain new values without breaking your client.

Runtime deprecation

An operation scheduled for removal gets at least six months of notice before it stops responding:

• the OpenAPI document marks the operation with deprecated: true, x-cademi-deprecated-at (the announcement date), and x-sunset (the cutoff date);
• every response from that operation includes these headers:

Deprecation: @1798761600
Sunset: Thu, 01 Jul 2027 00:00:00 GMT
Link: <https://api.cademi.com.br/docs/deprecations>; rel="deprecation"

• GET /capabilities lists deprecated operations in deprecations[]:

{
  "data": {
    "object": "capabilities",
    "release": "3.2.0",
    "deprecations": [
      {
        "operation_id": "products.legacy_export",
        "deprecated_at": "2027-01-01",
        "sunset_at": "2027-07-01"
      }
    ]
  }
}

• between the announcement and the cutoff, the operation keeps responding normally;
• after the Sunset date, the operation stops executing and returns 410 with the error code below.

Errors

No /api/v3 operation is deprecated at this time. This section describes the process that applies once one is.

Versioned events

Each release publishes, alongside the OpenAPI document, the catalog of public events at that point (type, version, visibility, and payload keys). A published event never changes shape without a new version: removing or renaming a field, or changing its visibility, produces a new version of the same type.

An event delivered to a webhook destination is always the JSON recorded when the event occurred, never rebuilt from the current payload shape. Replaying an older event (POST /webhooks/{id}/replays, GET /events/{id}) returns exactly what was recorded, in the version it was recorded in. Each webhook destination pins payload_version when you register it and receives events in that version. See Webhooks and Events.

Tracking changes

• The changelog for each release describes what changed and what you need to do (nothing, for compatible changes).
• The X-Cademi-Release header on any response tells you which release served the call.
• GET /openapi.json always serves the document for the latest published release, never an earlier one.
• GET /capabilities returns release and deprecations[], so your integration can track both programmatically without reading the changelog.

Version boundaries

API v3 runs on the same host as the legacy APIs (/api/v1, /api/v2, /api/third), but credentials from one are not valid on the other:

• a v3 credential secret (ck_live_…/ck_test_…) sent to /api/v1, /api/v2, or /api/third is rejected with 401;
• a legacy authentication token sent to /api/v3 is rejected with 401 unauthenticated;
• a signed-in dashboard session does not authenticate requests to /api/v3. Calls to v3 require an API credential or an administrator's OAuth access token. See Authentication.

Compatibility matrix

One row per published v3 release. The CLI column is the first cademi CLI version that supports the release: CLI 0.1.0 (September 25, 2026, generated from 3.4.4) works with every 3.x release, and cademi doctor warns when the server runs a newer minor (its new operations are still reachable through cademi api) or a different major. Up to 3.3.2 each release only added. 3.4.0 corrects behavior that did not match the documentation, including a few changes that are not backward compatible, 3.12.0 replaces the score.removed event with score.deleted, 3.13.0 requires the release of the first import of an account and changes the status code of three responses, 3.14.0 moves the permissions of administrators to the policy format, and 3.15.0 lets an administrator call the API with the OAuth access token alone and retires the combined mode of access token and credential secret, 3.15.2 ends the transition that still accepted the access token of cademi-cli 0.3.x together with a credential secret, 3.15.3 makes the resource_id filter of GET /events take the public ID of the resource and require resource_type, and 3.16.0 removes the anonymous block from support tickets. All are listed in the changelog.