Developer API

GridWatcher Developer API

Programmatic access to point-in-time government contract and disclosure data. Query the archive, diff any two dates, and pull entity-resolved operator rollups. Every record is content-addressed and hash-chained, so a result you cite today can be reproduced byte-for-byte later.

View the OpenAPI spec Plans and pricing

The spec is public on purpose.

Read every endpoint, schema, and error shape before you pay a cent. Only the data endpoints require a key.

Base URL and versioning

https://api.gridwatcher.app/v1

All endpoints are versioned under /v1. Breaking changes ship as a new version prefix; /v1 stays stable.

Authentication

Bearer API keys. Send your key on every data request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.gridwatcher.app/v1/contracts?limit=25"

Mint a free sandbox key with a single call. No card required:

curl -X POST "https://api.gridwatcher.app/v1/keys" \
  -H "Content-Type: application/json" -d '{"email":"you@example.com"}'

Raw keys are never stored - only a SHA-256 hash. If you lose a key, mint a new one and the old one keeps working until you revoke it.

Metering: GW Credits

1 credit = 100 records returned. An empty result costs 0 credits - you never pay for a miss. Overage beyond your included credits is $0.05 per 100 records.

Every response carries your usage headers so you can meter client-side:

X-RateLimit-Limit
X-RateLimit-Remaining

Plans

Plan	Price	Included credits	Rate limit	Notes
Free Sandbox	$0	Throttled	60 / min	Recent data only. No diffs or rollups.
Indie	$49 / mo	50,000 / mo	120 / min	Solo devs and civic hackers.
Pro Most popular	$199 / mo	250,000 / mo	600 / min	Adds point-in-time diffs and entity-resolved operator rollups.
Business	$699 / mo	750,000 / mo	1,000 / min	Adds bulk export, webhooks, 99.9% SLA.
Enterprise	from $2,500 / mo	Custom	Custom	Dedicated support and custom SLA.

Bulk historical backfill add-on: $750 one-time - full-archive pull for quantitative and AI training use. Point-in-time diffs and entity-resolved rollups are available on Pro and above.

Endpoints

GET/v1/healthService liveness. Public, unmetered.

GET/v1/openapi.yamlThis API's OpenAPI 3.1 spec. Public.

GET/v1/contractsList and filter contract records. Supports pagination.

GET/v1/contracts/{id}/historyFull point-in-time version history for one record.

GET/v1/diffWhat changed between two capture dates. Pro and above.

GET/v1/operators/{key}/awardsEntity-resolved award rollups for one operator. Pro and above.

GET/v1/snapshotsArchive capture index with hash chain and provenance.

GET/v1/bulkBulk export. Business and above, or the backfill add-on.

POST/v1/keysMint a free sandbox key. Public.

POST/v1/subscribeStart a checkout session for a paid plan.

Full parameters, schemas, and examples are in the OpenAPI spec.

Errors

Errors are JSON with a stable shape and a real HTTP status:

{ "error": { "status": 401, "message": "Invalid API key" } }

Status	Meaning
`401`	Missing, malformed, or unknown key.
`402`	Subscription past due. Update billing to restore access.
`403`	Key revoked, or the endpoint is fenced to a higher plan.
`429`	Rate limit or monthly credit allowance exceeded.
`5xx`	Our fault. Retry with backoff.

Data integrity

Each archived capture is stored write-once and content-addressed by SHA-256, chained to its predecessor, and covered by a daily Merkle manifest. That means a citation is reproducible: the bytes behind a number you published cannot be quietly rewritten.

Paid access never influences a grade.

Grades come from disclosed public records scored against a published methodology. No operator can pay to change, delay, or remove a grade, and no API plan returns different grades.