API policy

Versioning & release policy

VehiCode protects production integrations while improving vehicle identification and technical data coverage. Stable contracts and future early-access releases have different compatibility expectations.

Stable API

The Stable API is intended for production integrations. The current deployed version is identified by the OpenAPI document.

Existing integrations remain compatible within the supported major version.
Bug fixes, data improvements, and compatible optional fields may be released regularly.
Breaking contract changes normally require a new major version or an announced migration.
Deprecation and migration requirements are communicated in advance.

v1.2.0 compatibility exception

API v1.2.0 adds supported alternatives with an unknown engine code to the existing possibleConfigurations field.

{
  "possibleConfigurations": [{
    "engineCode": "UNKNOWN",
    "coverage": "partial"
  }]
}

UNKNOWN: A reserved placeholder, never a confirmed engine identifier.
partial: The list contains supported possibilities, but is not exhaustive.

Integration action: This is a deliberate compatibility-affecting exception. Update strict parsers that validate engine codes or reject new object keys before handling these responses.

Future significant incompatible changes will use a major version and a documented migration program. v2 Beta remains planned, not released.

Beta API

A v2 Beta channel is planned for future changes but is not currently available. When launched, participation will require explicit version selection and will not change existing Stable integrations.

The response contract may evolve during Beta.
Changes will be documented in the API changelog.
Significant breaking changes will be announced in advance whenever practicable.

Beta describes the API contract, not the verification level of individual vehicle specifications.

Release channels

Channel	Purpose	Status
v1 Stable	Production integrations	Available
v2 Beta	Early access to extended vehicle data	Planned
v2 Stable	Future stabilized v2 contract	Planned

Changelog & notifications

The OpenAPI document identifies the current Stable contract. The API changelog records release status and will record features, compatibility changes, fixes, migration requirements, and release dates. Important integration changes will also be communicated to affected customers.

Beta graduation

Before a Beta API becomes Stable, VehiCode reviews its response contract, integration compatibility, documentation, and operational readiness. A migration guide will be published when needed. A newer Stable version will not automatically discontinue an older supported Stable version.

Deprecation

Deprecation notices will identify the affected version, replacement, migration steps, and planned end-of-support date. We aim to give reasonable advance notice, except when urgent security or operational issues require faster action.

Vehicle data improvements

Vehicle identification and technical coverage may improve independently of API contract versions. Confirmed, estimated, and possible specifications remain distinct from API version stability.