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 in the X-Boardwalk-Schema-Version header on every response. Selected successful JSON envelopes also echo it as meta.schemaVersion for convenience, but clients should treat the header as authoritative. 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 a request parameter | Adding a request parameter alias |
| 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 as a correctness change, not a breaking change: the response shape does not narrow, while records that did not satisfy the requested constraint stop appearing. Such changes ship with a changelog entry and a schema-version bump so clients can audit when the behavior changed.
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, taxonomy, location lookups and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.