/.well-known/build.json — single GET answers 'is this deploy current?'

2026-05-16

apimarketing-siteai-discoverability

What We Built

Two parallel .well-known/build.json endpoints — one on the API (api.brainstormrouter.com/.well-known/build.json) and one on the marketing edge (brainstormrouter.com/.well-known/build.json) — that return the commit SHA, build timestamp, version, and surface name of the running deploy.

Both are baked at build time:

API surface: scripts/generate-static-assets.ts reads GITHUB_SHA (or

falls back to local git rev-parse HEAD) and inlines a BUILD_INFO const into src/api/static-assets.generated.ts. The route serves it with Cache-Control: no-store.

Marketing surface: site/scripts/stamp-build.mjs runs as the first

step of site/package.json's build script, reads VERCEL_GIT_COMMIT_SHA, and writes site/public/.well-known/build.json with surface: "marketing-site" so consumers can tell which edge they hit.

The two surfaces share the same schema. The API and marketing site can drift (they ship independently), so surface is the field that disambiguates.

Why It Matters

Three consecutive automated reviews — two model councils and a Computer eval — fetched brainstormrouter.com after a confirmed deploy and reported "stale CDN edge, cannot verify the new content." Each one spent multiple turns probing content strings to infer freshness. The failure mode is generic: any reviewer (human, agent, or model) that infers deploy state from cached HTML loses a turn to CDN noise.

A build.json endpoint with the commit SHA collapses that into one GET. The reviewer doesn't have to know which strings should be present; they compare commit_sha against git rev-parse origin/main and they're done.

This is the same pattern AWS, Stripe, and Cloudflare expose internally — it just hadn't been wired here yet.

How It Works

Read either endpoint:

curl -s https://api.brainstormrouter.com/.well-known/build.json | jq

{
  "commit_sha": "c32bc959c903fa80b48f8302cb8cf3c334ed7245",
  "commit_short": "c32bc959c903",
  "branch": "main",
  "built_at": "2026-05-16T19:24:50.522Z",
  "version": "1.0.0-beta.1",
  "node_version": "v22.22.0",
  "surface": "api",
  "generator": "brainstormrouter/scripts/generate-static-assets.ts"
}

Compare against the expected SHA in one line:

test "$(curl -s https://api.brainstormrouter.com/.well-known/build.json | jq -r .commit_sha)" \
  = "$(git rev-parse origin/main)" && echo CURRENT || echo STALE

The marketing site has the same shape with surface: "marketing-site".

agents.json advertises the API endpoint via build_info_url so discovery clients pick it up alongside openapi_url without out-of-band documentation.

Lockstep Checklist

[x] API route added (/.well-known/build.json in src/api/server.ts)
[x] Build-time generator emits BUILD_INFO (scripts/generate-static-assets.ts)
[x] Marketing-site stamper runs in Vercel build (site/scripts/stamp-build.mjs)
[x] Agent card advertises endpoint (site/public/.well-known/agents.json)
[x] Test guards the shape (src/api/static-assets.test.ts)
[x] Ship-log entry (this file)
[n/a] TypeScript SDK — discovery endpoint, consumers curl directly
[n/a] Python SDK — same
[n/a] MCP tools — surfaced via agents.json.build_info_url