SIGNALS Docs
Reader View

API Versioning

The stable Signals v1 API contract, additive capabilities and supported field guarantees.

Overview

The Signals REST API uses /api/v1/ and contract version 1.0.0. The v1 contract freezes at the beta release. Until that freeze, the contract is being finalised for the beta.

Stability from the beta

After the beta release, every change within /v1 is additive only. Supported endpoints, field names, response structures and request behaviour remain stable. Changing supported contract behaviour requires a new major API version.

The changelog and GET /api/v1/changelog describe the 1.0.0 contract and every additive change after it.

The additive-only guarantee

Within v1, we will only make additive changes. Concretely, the following are considered safe and may ship after the beta:

  • Adding a new endpoint.
  • Adding a new, optional request parameter whose omission preserves existing behaviour (for example ?fields= sparse fieldsets, or the optional Idempotency-Key header).
  • Adding a new field to a response body. Clients must ignore unknown fields.
  • Adding a new optional response header.
  • Adding a new enum value to a field already documented as extensible.
  • Adding a new webhook event to the event registry.
  • Relaxing a validation rule to accept a wider range of input.

Because responses only ever gain fields, a client that reads the fields it knows about will continue to work unchanged.

Contract stability

The v1 contract preserves supported endpoints, fields and request behavior. The following operations require a new major API version (/api/v2/):

  • Removing or renaming an endpoint, field, or response key.
  • Changing the type of an existing field (for example integer → string).
  • Changing the meaning, units, or format of an existing field.
  • Adding a new required request parameter, or making an optional one required.
  • Tightening a validation rule to reject supported input.
  • Removing an enum value, or changing an existing one.
  • Changing default sort order, pagination defaults, or error response shapes.
  • Changing authentication, authorisation, or rate-limit semantics in a way that rejects supported requests.

A response-shape gate in CI freezes the default response shape of the core resources and fails the build if any of these slip through.

Discovering changes

Every client-visible change after 1.0.0 is recorded in a machine-readable changelog:

GET /api/v1/changelog

Each entry records the date, the affected endpoint(s), the change type, and a human-readable description. Poll it to discover new capabilities programmatically.

Pricing field retention

The catalogue pricing contract retains line amount, rate ID, tier, surcharge, FX-lock and tax-lock fields throughout v1.x. Their names, JSON types and meanings remain available alongside additive manifest metadata. pricing_locked continues to describe the FX/tax recalculation lock; accepted_pricing_terms_locked describes accepted commercial terms. Both are supported fields.

All supported pricing fields remain available throughout v1.x. Removing a supported field requires a new major API version. Additive manifest metadata does not alter the meaning or availability of supported response fields.