# Overview

> One dataset of what local governments publish, served two ways with one key: a REST API and a hosted MCP server.

Hey Town Hall Data is one dataset of what local governments publish: meetings and minutes, bylaws, budgets, bids, permits, officials and notices. You reach it two ways, with one key.

- **The MCP server** at `https://data.heytownhall.com/mcp`. Connect the AI model your company uses, and your AI client calls its tools.
- **The REST API** at `https://data.heytownhall.com/v1`. JSON over HTTPS for your own code, read with `GET`, paged by cursor.

Both read the same records through the same gate. They share the same rate limits and the same bill, and one tool call is one API request.

Coverage today is British Columbia. The United States is being added.

## What every record carries

Every record carries `source_url`, the public page or document it was read from, and `read_at`, when it was read. Cite them.

A value that could not be read is `null`. Null means unknown, never no.

## Start here

- [Quickstart](https://data.heytownhall.com/docs/quickstart): Your first request against the sandbox, by REST and by MCP.
- [Authentication and keys](https://data.heytownhall.com/docs/authentication): Sandbox and live keys, and the header they go in.
- [The sandbox](https://data.heytownhall.com/docs/sandbox): Three fictional governments in the live shapes, free.
- [Connect the MCP server](https://data.heytownhall.com/docs/mcp): The address, the header and every tool.

## Using the API

- [Pagination and filters](https://data.heytownhall.com/docs/pagination): Cursors, page sizes and the filters lists share.
- [The change feed](https://data.heytownhall.com/docs/change-feed): What changed since you last looked. There are no webhooks.
- [Errors](https://data.heytownhall.com/docs/errors): One envelope, a stable code and a request id.
- [Rate limits](https://data.heytownhall.com/docs/rate-limits): Requests per minute, per key.
- [Billing and the spending cap](https://data.heytownhall.com/docs/billing): Three meters, one flat rate each, and a cap you set.

## The records

The records are filed in seven drawers, plus the topics that cut across them.

- [Meetings](https://data.heytownhall.com/docs/records/meetings): Meetings, agenda items, minutes, motions, votes and transcripts.
- [Laws](https://data.heytownhall.com/docs/records/laws): Bylaws and the documents governments publish.
- [Money](https://data.heytownhall.com/docs/records/money): Financial statements, their lines, and bids and tenders.
- [Development](https://data.heytownhall.com/docs/records/development): Development applications, permits and fees, road and utility works.
- [People](https://data.heytownhall.com/docs/records/people): Elected officials, appointments, departments and job postings.
- [Places](https://data.heytownhall.com/docs/records/places): Jurisdictions, who governs a point, and the software each one runs.
- [Public word](https://data.heytownhall.com/docs/records/public-word): News, notices, events, engagement projects and local press.
- [Topics](https://data.heytownhall.com/docs/records/topics): Follow one business topic across every drawer.
- [Search](https://data.heytownhall.com/docs/records/search): One full-text search across the records.
- [Coverage](https://data.heytownhall.com/docs/records/coverage): What the data holds and where. No key needed.

## API reference

Every endpoint has a reference page with its parameters, its answer and a playground. The pages are built from the API's own OpenAPI 3.1 document at `https://data.heytownhall.com/openapi.json`, so they say what the API does.