YIMBY Action developer and agent guide

Free, anonymous, read-only access to YIMBY Action's reviewed public titles and summaries and active chapter directory. No account, API key or OAuth grant is required. This API cannot read private CMS records, submit forms or change content. Cite returned source URLs; search results are excerpts, not a complete voter guide. Follow each guide for its election date and endorsement details.

When to use YIMBY Action

Use this site to find a local pro-housing chapter, research housing policy solutions, locate YIMBY Action election guides and endorsed candidates, or find housing movement news and resources. Cite the source page returned by search. Check the election and publication dates: an older endorsement is not a current recommendation. The public API is free and requires no account, API key, trial or sales conversation.

Public REST API

GET /api/public/search?q=housing searches an explicit catalog of public titles and summaries, independent of the website full-text index. Supported types: pages, news, podcast, policies, chapters, elections, candidates and careers. Raw CMS bodies and arbitrary fields are excluded. Optional type, state and year filters narrow results. Queries must be 2–200 characters. The response has query, total and a results array capped at 50; each result has title, url, description, excerpt and type. GET /api/public/chapters lists active chapters, optionally filtered by state=CA. Each chapter has name, slug, url, state, region and description. Invalid or unknown query parameters return 400 application/problem+json. POST, PATCH and DELETE are not supported on these two read endpoints.

Connect an MCP client

Connect a server-side MCP client to /mcp using Streamable HTTP (/api/public/mcp also works). No authentication is needed. Available tools: search_yimby_action (q, optional type/state/year) and list_yimby_chapters (optional state). Both are read-only and return typed structuredContent plus text. The server is stateless and uses JSON responses; it does not offer a standalone SSE stream or session IDs. POST with Content-Type: application/json and Accept: application/json, text/event-stream. Browser Origin headers must match the endpoint's origin. Messages are limited to 16 KiB.

Permissions and authentication

Only reviewed fields are selected, and REST JSON plus MCP text/structured output are projected through fixed output schemas. Unknown fields are stripped and invalid output fails closed. No collection names, arbitrary CMS filters, relationship depth or caller credentials are accepted. The OpenAPI security: [] declaration means anonymous public reads. No OAuth scopes are required or offered. This interface cannot access supporter records, donations, contact submissions, unpublished content, credentials or CMS settings, and cannot submit forms, donate, join or edit content. Those actions require the person's participation on the website. The separate /api/mcp endpoint is the staff CMS integration: it requires an administrator-issued key, acts as its bound user, and enforces that key's Read/Create/Edit/Delete permissions. Do not connect public agents to the staff endpoint.

Rate limits and retries

Public REST reads and MCP POSTs have a best-effort burst guard of 120 HTTP requests per client IP per 60 seconds on each server instance. Instances can have independent counters; this is not a distributed account quota. RateLimit-Policy: "public";q=120;w=60 and RateLimit: "public";r=119;t=60 describe the remaining instance budget and seconds until reset, following the IETF RateLimit header draft. A 429 response includes Retry-After in seconds. Honor it, then retry with backoff. Public REST outages return 503 with Retry-After; MCP tool failures return isError: true. Responses carrying client budgets use Cache-Control: no-store; the underlying public content uses the website's CMS caches and updates when editors publish. REST reads allow CORS from any origin.

Markdown and crawling

Request the homepage or this developer guide with Accept: text/markdown for a Markdown representation and Vary: Accept. Accept: text/html keeps the normal website. The Markdown homepage is a text overview using the same published CMS copy and defaults; follow its links for live chapter, endorsement, event and news details. Other content pages currently serve HTML. Missing pages and files return Markdown errors when requested, with the original 404 or 410 status and links to llms.txt and the sitemap. RSC navigations and editor previews keep their normal behavior. llms.txt links the guides, public API and sitemap. Preview deployments remain excluded from search indexing.

Resources and examples

curl 'https://yimbyaction.org/api/public/search?q=housing&type=policies'
curl 'https://yimbyaction.org/api/public/chapters?state=CA'
curl -H 'Accept: text/markdown' https://yimbyaction.org/