The change feed

There are no webhooks. The API never calls you. To learn what changed, read the change feed, GET /v1/events, on a schedule that suits you. In MCP the same feed is the changes_since tool.

How the feed worksCopy Anchor Link

Every change written to the data is an event with an ever-growing id. The feed lists events oldest first. Each event names the record that changed, by its family and id, so you know what to read again.

{
  "id": "1",
  "kind": "meeting.agenda_posted",
  "jurisdiction_id": "port-ellery",
  "family": "meeting",
  "subject_id": "900000",
  "occurred_at": "2026-05-03T01:00:00.000Z"
}

family is one of meeting, agenda_item, motion, recording, bylaw, post, jurisdiction and topic_tag. Filter the feed to one with kind, as in ?kind=meeting.

Keep your placeCopy Anchor Link

1. Read the feed once, from the start or with since, and keep the last event id you read.
2. Next time, pass that id as after. You get only the events that came after it.
3. Follow next_cursor until it is null, then keep the new last id.

curl "https://data.heytownhall.com/v1/events?after=1" \
  -H "Authorization: Bearer $HTD_KEY"

import os
import requests

def changes_after(last_id):
    params = {"after": last_id, "limit": 100}
    headers = {"Authorization": f"Bearer {os.environ['HTD_KEY']}"}
    while True:
        page = requests.get("https://data.heytownhall.com/v1/events", params=params, headers=headers, timeout=30).json()
        if "error" in page:
            raise RuntimeError(page["error"]["message"])
        for event in page["results"]:
            yield event
            last_id = event["id"]
        if page["next_cursor"] is None:
            return
        params["cursor"] = page["next_cursor"]

Then read each changed record. A meeting, a motion, a bylaw and a jurisdiction each have a detail endpoint, such as GET /v1/meetings/{id}. The others are in their family's list.

Things to knowCopy Anchor Link

• Each feed page is one records request, billed like any other list page.
• An answer can be up to 15 seconds old. The feed is cached at the edge that long, so polling faster returns the same page.
• Poll within your rate limit. A sandbox key takes far fewer requests a minute than a live one.
• since works on most lists too. It keeps records read at or after an instant, for a sweep of one family without the feed.

The endpointCopy Anchor Link