Versioning and change policy
What counts as a breaking change, what does not, how much notice you get, and how to tell versions apart.
The API is versioned in the path (/api/v1). Within a version, the response contract carries its own date-stamped schema version, echoed on every response as meta.schemaVersion and in the X-Boardwalk-Schema-Version header. It is a date rather than a semantic version, so you can compare it against the changelog without a mapping table.
What is a breaking change
| Breaking — you get notice | Not breaking — ships without notice |
|---|---|
| Removing a field | Adding a field |
| Changing a field's type | Adding an optional request parameter |
| Removing or renaming an enum token | Adding a new enum token |
| Removing an endpoint | Adding an endpoint |
| Raising a credit rate | Adding a new error code |
| Making an optional request parameter required | Rewording an error message or a *Label field |
A breaking change ships with at least 90 days of notice, a Deprecation header and a Sunset header on the affected responses, and a changelog entry. The headers appear before the change, so an integration can detect a deadline without anyone reading an email.
Changes to which records come back
We classify that flip as a correctness change, not a breaking change, and it is therefore exempt from the 90-day notice period. The reasoning, stated now rather than on the day: result sets get smaller, not different in shape. No field is removed, no type changes, no enum narrows, so nothing breaks at your parsing layer. It moves the product toward the guarantee already published on every relevant page. When it happens it will ship with a changelog entry, a schema-version bump, and the disappearance of the limitation notice from these docs — those are the signals to watch.
Legacy aliases
Some paths and key prefixes exist for compatibility and are not going away: csk_ keys are accepted indefinitely, and the previous API hostname continues to resolve. They are not advertised, but nothing built against them will be switched off without the notice above.
Ready to make a call?
A free Boardwalk trial includes API access and a sandbox key. Counting, filtering, the location tree and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.