Versioning
Within /v1, the API has dated versions. Each version is named by the day it shipped, such as 2026-11-17. Breaking response changes ship in a new version. We aim to keep earlier versions compatible with their published schema. After a field's announced deprecation deadline, preserving its shape may mean returning a placeholder instead of live data.
Send a version
Set GOVDASH_API_VERSION to the version you tested your integration against, then send it in the govdash-version header. Keep that value pinned until you are ready to upgrade:
curl "$GOVDASH_API_URL/v1/opportunities" \
-H "Authorization: Bearer $GOVDASH_API_KEY" \
-H "govdash-version: $GOVDASH_API_VERSION"const apiVersion = process.env.GOVDASH_API_VERSION
if (!apiVersion) throw new Error("Set GOVDASH_API_VERSION")
const response = await fetch(
`${process.env.GOVDASH_API_URL}/v1/opportunities`,
{
headers: {
Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
"govdash-version": apiVersion,
},
},
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())import os
import requests
response = requests.get(
f"{os.environ['GOVDASH_API_URL']}/v1/opportunities",
headers={
"Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
"govdash-version": os.environ["GOVDASH_API_VERSION"],
},
)
response.raise_for_status()
print(response.json())- A request without the header returns
400 bad_request. The error message names the missinggovdash-versionheader and lists supported versions. - Responses to requests with a supported version include a
govdash-versionheader with the version served. - A version the API doesn't serve returns
400 bad_request, and the message lists the versions it does.
What older versions get
When a newer version changes an object, the API rewrites that object back into your version's shape before it responds, wherever the object appears: on its own, in a list, or expanded inside another object.
For a field we plan to remove, the sequence is:
- We announce the migration deadline in deprecation headers, normally at least 30 days ahead.
- Until that timestamp, the field remains functional. Update your integration during this window.
- After the deadline, a newer version may omit the field. Older versions may still include it with a placeholder of the same type, such as an empty string. That value is no longer live data and must not drive your integration.
Pinning a version preserves the supported response shape; it does not extend a deprecated field's useful lifetime beyond its announced deadline.
Versions change responses, not requests. A request body is always read the same way, whatever version you pin.
Upgrade
- Read the changes between your version and the latest in the list below.
- Update your integration for them.
- Send the new version in
govdash-version.
Versions
| Version | Changes |
|---|---|
2026-11-17 | Initial version. |