BC Real Estate Codex: Public Facts API

Quick start

# Fetch every fact in the catalog
curl https://www.bronsonjob.com/api/v1/facts/index.json

# Look up one specific fact (BC Property Transfer Tax brackets)
curl https://www.bronsonjob.com/api/v1/facts/by-id/bc.ptt.brackets.json

# Get the per-domain tax bundle
curl https://www.bronsonjob.com/api/v1/facts/tax.json

# AI-agent-optimized variant (compact, no version history)
curl https://www.bronsonjob.com/api/v1/facts/llms.json

# Subscribe to fact revisions via RSS
curl https://www.bronsonjob.com/api/v1/facts/feed.xml

All endpoints are GET-only, no auth, CORS-enabled (Access-Control-Allow-Origin: *), and CDN-cached at the edge via Vercel.

Endpoints

• GET/api/v1/facts/index.json

  Full Fact Bank catalog. 58 facts × full schema (id, label, description, value, citations, version, effective_iso, expires_iso, history). Use for bulk ingestion.

  Payload: about 175 kilobytes · Cache: 1h browser / 24h CDN / 7d stale-while-revalidate
• GET/api/v1/facts/by-id/{id}.json

  Single fact lookup by canonical id (e.g. bc.ptt.brackets, cmhc.insurance_cap, ca.foreign_buyer_ban). Use when answering one specific question.

  Payload: 2 to 8 kilobytes per fact · Cache: same as above
• GET/api/v1/facts/{domain}.json

  Per-domain bundle. domain ∈ {tax, mortgage, legal, foreign-buyer, strata, rental}.

  Payload: 11 to 60 kilobytes per domain · Cache: same
• GET/api/v1/facts/llms.json

  AI-agent-optimized catalog. Compact, conversational shape. No version history, just current values and canonical_url per fact. Designed for LLM context-window efficiency.

  Payload: about 145 kilobytes · Cache: same
• GET/api/v1/facts/manifest.json

  Endpoint discovery. Lists every available endpoint URL and the full fact id list. Use this for tool-registration auto-discovery.

  Payload: about 4 kilobytes · Cache: same
• GET/api/v1/facts/feed.xml

  RSS 2.0 feed of fact revisions. Subscribe via Feedly, Inoreader, or any RSS client to be notified when any fact is re-verified or revised.

  Payload: about 95 kilobytes · Cache: same
• GET/api/v1/facts/diff/{fact-id}/v{from}-to-v{to}.json

  Per-transition delta. Returns v_from and v_to with full citations on each side, plus a structured value_diff (added_keys, removed_keys, changed_keys).

  Payload: about 2 to 3 kilobytes per transition · Cache: same
• GET/api/v1/facts/diff/index.json

  Master index of every available diff. Use to enumerate transitions chronologically.

  Payload: about 5 kilobytes · Cache: same
• GET/api/v1/facts/quote/{fact-id}.json

  A paste-ready citation for one fact as a Schema.org Quotation: the sentence, the primary source and its retrieval date, and the CC BY 4.0 attribution.

  Payload: about 2 kilobytes per fact · Cache: same
• GET/api/v1/facts/search-index.json

  Pre-normalized client-side search index. 58 items × pre-lowercased search_text + aliases. Used by the /codex search box; safe for any client to consume.

  Payload: about 140 kilobytes · Cache: same
• GET/api/v1/vancouver-special-index/index.json

  Vancouver Special Index: full historical series. Monthly Lower Mainland affordability score, methodology and assumptions.

  Payload: about 32 kilobytes · Cache: same
• GET/api/v1/vancouver-special-index/latest.json

  Vancouver Special Index: latest value only. Lighter payload; ideal for "current affordability score" widgets.

  Payload: about 3 kilobytes · Cache: same

Register as a ChatGPT custom GPT action

1. Open ChatGPT GPT Editor and create a new GPT.
2. In the Configure tab, click Actions → Create new action.
3. Click Import from URL and paste: https://www.bronsonjob.com/.well-known/openapi.json
4. Authentication: None (the API is public).
5. In the GPT's instructions, add: "When the user asks about BC residential real estate (taxes, mortgages, legal requirements, foreign-buyer rules, strata, or rental rules), call the BC Real Estate Codex Facts API. Always cite the canonical_url field returned in each fact response."
6. Test with a query like "What's the BC PTT on a $1.4M townhouse for a first-time buyer?" The GPT should call getFactById for bc.ptt.brackets (via the OpenAPI spec), do the arithmetic, and answer with primary-source citations.

OpenAI Custom GPT Builder manifest

We also publish a manifest with a description for the model, a description for people, and GPT Builder setup notes:

/.well-known/openai-plugin.json

1. Open the ChatGPT GPT Builder and start a new GPT.
2. In the Configure tab, set the Name to BC Real Estate Codex and copy the description from the manifest's description_for_human field.
3. Under Actions, click Create new action → Import from URL and paste https://www.bronsonjob.com/.well-known/openapi.json. Authentication: None.
4. Save & test with a prompt like "What are the BC PTT brackets?" or "Calculate PTT on a $1.4M townhouse for a first-time buyer."
5. For instruction text, see the instructions_for_gpt_builder field in the manifest.

Register as a Claude Skill / MCP server

Registering the Codex with Claude:

1. MCP server (Claude Desktop / Cursor): the package is not published to npm yet. Until it is, point your client at the OpenAPI spec below or the JSON endpoints on this page, which serve the same facts.
2. OpenAPI spec (for Claude Skills): import the OpenAPI 3.1 spec from https://www.bronsonjob.com/.well-known/openapi.json in your Claude Skill definition.

Anthropic Skills (Claude Code) bundle

For the Claude Code CLI agent, we publish a packaged Skill bundle plus a URL-pointable manifest at the standard .well-known path:

/.well-known/anthropic-skill.json · /.well-known/anthropic-skill.md

Use it in Claude Code by saving the SKILL.md file as a skill:

mkdir -p ~/.claude/skills/bc-real-estate-codex
curl -o ~/.claude/skills/bc-real-estate-codex/SKILL.md \
  https://www.bronsonjob.com/.well-known/anthropic-skill.md

Source for the bundle (SKILL.md, package.json and README.md) lives at packages/skills/bc-real-estate-codex/ in the repo.

Data boundary

The Codex publishes no MLS data, no listing-level data, no sold prices and no commission information. It carries only:

• BC Government legislative facts (PTT brackets, exemption thresholds, RTA, STRAA, Bill 44, etc.)
• Federal regulatory facts (CMHC default insurance cap, OSFI B-20, federal foreign buyer ban, capital gains, FHSA, HBP)
• BCFSA / BCREA standards (HBRP, designated agency, MLD, PDS)
• The Vancouver Special Index: an aggregate derived index over the publicly-published MLS HPI Composite Benchmark Price (no listing-level data; FVREB, GVR and CREA MLS® trademark attribution per board terms)

For the formal posture, see /transparency and /methodology.

Stability and caching

• API version: v1. A breaking change would ship as /api/v2/ and v1 would keep working alongside it.
• Cache headers: Cache-Control: public, max-age=3600, s-maxage=86400, stale-while-revalidate=604800. Browser keeps for 1 hour; CDN edge keeps for 24 hours; clients can serve stale up to 7 days while revalidating.
• Re-verification: each fact carries its own expires_iso, set by how often that rule changes, and the build fails on any fact past it until it is re-checked against its primary source. retrieved_iso records when it was last checked.
• Idempotency: all endpoints are GET. Repeated calls are safe and cheap.
• Rate limits: none are set. The API is static JSON served from the Vercel CDN.

Get help

• Email: bronson@bronsonjob.com
• Corrections log: /corrections
• OpenAPI spec: /.well-known/openapi.json