GovDash
Menu

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:

curlcurl
curl "$GOVDASH_API_URL/v1/opportunities" \
  -H "Authorization: Bearer $GOVDASH_API_KEY" \
  -H "govdash-version: $GOVDASH_API_VERSION"
TypeScriptTypeScript
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())
PythonPython
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 missing govdash-version header and lists supported versions.
  • Responses to requests with a supported version include a govdash-version header 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:

  1. We announce the migration deadline in deprecation headers, normally at least 30 days ahead.
  2. Until that timestamp, the field remains functional. Update your integration during this window.
  3. 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

  1. Read the changes between your version and the latest in the list below.
  2. Update your integration for them.
  3. Send the new version in govdash-version.

Versions

VersionChanges
2026-11-17Initial version.