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 — announced in the changelog | Not breaking — ships without an entry |
|---|---|
| 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 |
Every breaking change is recorded in the changelog with the date it took effect and what to send instead. Check it before you depend on a value this API accepts today.
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, 50 record-export credits (search, CSV, MCP), and 5 Find Contact Info lookups. Counting, taxonomy, location lookups and the analytics plane cost nothing, so you can evaluate the data before you spend a credit.