GovDash
Menu

Requests and responses

Every endpoint follows the same conventions for request bodies, ids, timestamps, empty values, and deletes. Read this page once and the rest of the API should hold no surprises.

Request bodies

Send JSON with a Content-Type: application/json header. Bodies can be at most 1 MB, and every write takes a single record, so you won't come close.

Request bodies are strict. A field the endpoint doesn't list returns 400 bad_request instead of being ignored, so a typo fails loudly rather than silently doing nothing.

A PATCH changes only the fields you send. Fields you leave out keep their values. Send at least one field.

curlcurl
curl "$GOVDASH_API_URL/v1/opportunities/$OPPORTUNITY_ID" \
  -X PATCH \
  -H "Authorization: Bearer $GOVDASH_API_KEY" \
  -H "govdash-version: $GOVDASH_API_VERSION" \
  -H "Content-Type: application/json" \
  -d '{ "description": "Recompete of the 2021 award." }'
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/${process.env.OPPORTUNITY_ID}`,
  {
    method: "PATCH",
    headers: {
      Authorization: `Bearer ${process.env.GOVDASH_API_KEY}`,
      "govdash-version": apiVersion,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ description: "Recompete of the 2021 award." }),
  },
)
if (!response.ok) throw new Error(await response.text())
console.log(await response.json())
PythonPython
import os

import requests

response = requests.patch(
    f"{os.environ['GOVDASH_API_URL']}/v1/opportunities/{os.environ['OPPORTUNITY_ID']}",
    headers={
        "Authorization": "Bearer " + os.environ["GOVDASH_API_KEY"],
        "govdash-version": os.environ["GOVDASH_API_VERSION"],
    },
    json={'description': 'Recompete of the 2021 award.'},
)
response.raise_for_status()
print(response.json())

Objects

Every resource comes back as a JSON object with an id and an object field that names its type:

{
  // The record's id. An opaque string.
  "id": "1c9f7a52-3e4b-4d1a-9f0e-6b2a8c5d7e31",
  // What kind of record this is: "opportunity", "contract", "person", ...
  "object": "opportunity",
  // The team that owns the record.
  "team_id": "8e2d4b6a-1f3c-4a5e-b7d9-0c2e4f6a8b1d",
  // When GovDash created and last changed the record.
  "created_at": "2026-10-01T14:02:11.000Z",
  "updated_at": "2026-10-28T09:15:40.000Z",
  // ...the resource's own fields
}

The API reference shows every field of every object, with a comment on each one.

Ids are opaque

Treat every id as an opaque string. Don't parse it, don't build one yourself, and don't assume a format, length, or prefix. Resources may use different id formats, including UUIDs and prefixed strings. Compare ids as exact strings, and store them in a text column.

The ids in these docs are examples. They won't exist on your team.

Timestamps

Timestamps are ISO 8601 strings in UTC, such as 2026-10-28T09:15:40.000Z. Fields you send, such as an opportunity's due_date, accept any ISO 8601 timestamp with a time zone, such as 2026-12-15T17:00:00Z or 2026-12-15T12:00:00-05:00.

Empty values

A field with no value is null. It isn't left out. For example, an opportunity without a due date has "due_date": null.

The exception is expandable fields, which are left out unless you ask for them. See Expanding responses.

Deletes

How a delete finishes depends on how much it has to clean up.

ResponseEndpointsWhat it means
202 AcceptedOpportunities, contracts, documentsGovDash queued the delete and finishes it in the background. The record can still appear until it does.
204 No ContentAgencies, companies, people, agentsThe record is gone when the response arrives.

These responses have no body, except a document delete, which returns the document's id and "status": "deleting". Deleting a record that's already gone returns 404 not_found, which you can treat as success.

Team scope

A key reads and writes the records of the team it was created on. Records on other teams, and records above the key's classification ceiling, behave as if they don't exist. See Classification.