Status, versioning and deprecation
What is up right now, what we are allowed to change without telling you, and what we will never change inside a version. Contract version 1.4.0. Everything on this page is also returned by GET /api/v1/meta/status, so an automated procurement review and a human reading this page get the same answer.
Live status
Checked against the API and its database, on load. The endpoint returns 503when the database probe fails, so an uptime monitor pointed at it sees a real failure rather than a 200 carrying the word “degraded” in a field nobody parses.
curl https://commonelements.com/api/v1/meta/statusSupported versions
| Version | Status | Released | Sunset |
|---|---|---|---|
| v1 | current | 2026-06-15 | —The only version. No successor is announced, so no sunset date exists to publish; when one does, it appears here and in the Sunset header before anything is removed. |
What can change
The line between the two lists is the whole compatibility contract. Read the first one as your obligation as much as ours: a client that rejects an unrecognised field will break on a change we are explicitly allowed to make.
Ships without notice
- Adding a new endpoint, a new optional query parameter, or a new field to a response object. Parse responses tolerantly; a client that errors on an unrecognised field will break on a change this policy permits.
- Adding a new value to an open enumeration such as `change_kind`, a county-published milestone status, or a vendor category. Handle an unknown value as a passthrough string rather than a parse failure.
- Raising a plan's row cap or quota, or widening a lookback window.
Never happens inside a version
- Removing or renaming a field, changing a field's type, or changing the meaning of an existing value. Never done inside v1.
- Removing an endpoint, adding a required parameter to an existing endpoint, or tightening an existing parameter's accepted values.
- Moving an endpoint behind a higher plan than the one it shipped under. A new endpoint may launch on any plan; an existing one does not move up.
Deprecation policy
12 months minimum notice
A version is supported for at least 12 months after its successor is generally available. No endpoint inside a supported version is removed during that window.
Announced in three machine-readable places
A deprecated operation carries `deprecated: true` in the OpenAPI document, a `Deprecation` and a `Sunset` HTTP header (RFC 8594) on every response, and an entry in the changelog on /developers/status. Poll any one of them; you do not have to read an email to find out.
Successor named before removal
Nothing is deprecated without a documented replacement that returns the same information. The replacement ships first, and both run concurrently for the whole notice period.
Emergency exception, narrowly scoped
The only change that can ship without notice is one required to stop unlawful or unlicensed disclosure of data — a field withdrawn because a source's terms changed, or a privacy obligation. Affected customers are contacted directly, and the reason is stated in the changelog.
Quota policy
| Window | calendar month, UTC |
| Reset | First request on or after the first day of the next calendar month resets the counter. |
| Overage | None. A key that reaches its included requests returns 429 until the reset or an upgrade; there is no automatic overage charge. |
| What counts as one request | One HTTP request against a /api/v1 endpoint, counted whatever the status code. Meta endpoints (/api/v1/meta/*, /api/v1/openapi) and the sandbox are not metered. |
Changelog
Contract changes, newest first. Additive-only so far, which is the point of publishing it: the surface has only grown.
Added the meta namespace: /api/v1/openapi (machine-readable spec), /api/v1/meta/status, /api/v1/meta/dictionary, /api/v1/meta/usage, and a sandbox at /api/v1/meta/sandbox. Error responses on the new endpoints carry `docs_url` and `next_steps` alongside the existing `error` and `message`.
`display_name` added to the association record: the canonical rendering of the filed name. `name` is unchanged and still the verbatim registry string.
Bulk export gained `format=json` alongside CSV, and `columns=` for selecting a subset of a resource's column spec.
Bulk export resources `building-safety` and `report-card` added.
Change feed endpoints /api/v1/changes and /api/v1/changes/summary released.
v1 generally available.