Halfbill API Versioning and Deprecation Policy

Halfbill's public REST API uses URL path versions. The current OpenAI-compatible base URL is https://api.halfbill.uk/v1. The OpenAPI specification describes the supported operations and typed errors.

Compatibility

Breaking changes to the REST contract use a new path version. Additive fields, new endpoints, and new models can appear within an existing version. Clients should tolerate unknown response fields.

Deprecation and sunset

API deprecation notices are published in the Halfbill changelog, with the affected surface, replacement, migration steps, and any scheduled retirement date. Deprecation means a surface is discouraged; sunset means it will stop serving requests. No retirement date is currently scheduled for /v1.

When an endpoint is deprecated, its notice defines the transition period. There is no blanket minimum notice period. Model availability can change on an upstream provider's schedule, independently of API versioning.

Deprecated endpoints use the Deprecation header with an HTTP Structured Fields date and a Link with rel="deprecation" pointing to the notice. A scheduled retirement additionally uses the Sunset header with an HTTP date. These headers are omitted on endpoints without an announced deprecation or retirement.

Clients should monitor the changelog, migrate before a published sunset, and treat a missing Sunset header as an unspecified date.

Model and provider lifecycle

Model and provider availability is separate from the REST contract. Consult the live models directory before choosing an integration target. Deprecated entries remain available for historical lookups; deactivated models cannot serve new requests.