# 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`.

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

```json
{
  "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.