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 administrator session does not authenticate requests to /api/v3. Calls to v3 always require an API credential. See Authentication.

Compatibility matrix

One row per published v3 release. No operation was removed or changed in a breaking way between them: each release only added.