Versioning

API prefix policy, additive changes, breaking changes, notice channels, and basket retirement behavior.

Philidor's public API is under the /v1 prefix. This page describes the current operating policy for versioned public interfaces.

Customer-specific commitments are controlled by signed agreements.

Additive Changes

Clients should tolerate additive response fields, new enum values where documented as open, new optional query parameters, and new endpoint families under /v1.

Philidor may add fields to data, meta, and nested objects without changing the path prefix.

Breaking Changes

The following changes are treated as breaking for public integrations.

Change	Breaking
Removing a documented field	Yes
Renaming a documented field	Yes
Changing a documented type	Yes
Tightening required authentication on a public route	Yes
Removing a route	Yes
Adding an optional field	No
Adding a nullable field	No
Adding a new route	No

Where feasible, breaking changes are handled through a new route, a new versioned family, or a deprecation window.

Notice Channels

Philidor uses the changelog as the primary public notice channel for API and methodology changes.

Webhook customers can also receive basket version lifecycle notices when they pin a subscription to a specific basket version. Those notices include deprecation and retirement events for the pinned version.

Agreement-defined notices can apply for commercial customers.

Basket Version Retirement

Reference basket versions are immutable while supported. A retired immutable version URL returns 410 VERSION_RETIRED.

The response includes the retirement timestamp, a successor URL, and a Link header with rel="successor-version".

This retired-version response is a legacy exception that includes the field success set to false alongside the error object. Clients should key behavior from error.code.

curl https://api.philidor.io/v1/baskets/rwa-tbill-conservative/version/42

{
  "success": false,
  "error": {
    "code": "VERSION_RETIRED",
    "message": "Basket version 42 for \"rwa-tbill-conservative\" was retired. Use the latest version at /v1/baskets/rwa-tbill-conservative.",
    "retired_at": "2026-07-01T00:00:00Z",
    "successor_url": "https://api.philidor.io/v1/baskets/rwa-tbill-conservative"
  }
}

Clients pinned to a retired version should follow the successor URL, review the current version metadata, and update local references after validation.

Client Guidance

Use the response envelope rather than assuming a fixed top-level object beyond data, meta, or error. The retired basket-version exception also carries the field success set to false; clients should still branch on error.code.

Ignore fields you do not understand. Preserve identifiers such as version_id, content_hash, methodology_version, and graph snapshotId in audit logs.