# Blueflo

> What New York City's public records say about a building. Free, no account,
> no API key.

Every value carries its source dataset and the date it was last checked. Cards
report what city records say; they are not inspections and carry no warranty.

## Start here

- **MCP** (Claude, Cursor, any MCP client): `https://blueflo.tech/mcp`, Streamable HTTP, no key.
  Claude Code: `claude mcp add --transport http blueflo https://blueflo.tech/mcp`
- **Any building as markdown**, no browser needed: `https://blueflo.tech/b/<slug>.md`. Find the slug
  with `https://blueflo.tech/v1/search?q=126+macdou`; every card page also links its markdown form.
- **REST API**: `https://blueflo.tech/docs`, typed in `https://blueflo.tech/openapi.json`.

## What you can ask

- A building by address: `https://blueflo.tech/v1/buildings?address=126+MacDougal+St&borough=Manhattan`
- A building by slug: `https://blueflo.tech/v1/buildings/<slug>`
- Just the systems, not the whole card: `https://blueflo.tech/v1/buildings/<slug>/systems`
- One system of a building: `https://blueflo.tech/v1/buildings/<slug>/systems/<key>`
  (keys: heat, water, pests, safety, electrical, gas, elevators, envelope, flood, renting, energy, other)
- Every record behind a card: `https://blueflo.tech/v1/buildings/<slug>/records`
  (narrow with `?kind=complaint_patterns|dob_violations|hpd_violations|permits`)
- One record in full: `https://blueflo.tech/v1/buildings/<slug>/records/<kind>/<record_id>`
  (add `?dataset=` where a kind spans several: `ecb`, `bis`, `safety`, `dobnow_permits`, `bis_permits`)
- Apartments named in a record: `https://blueflo.tech/v1/buildings/<slug>/units`
- Buildings in a map view: `https://blueflo.tech/v1/index?bbox=south,west,north,east`
- Address autocomplete: `https://blueflo.tech/v1/search?q=126+macdou`
- What is indexed: `https://blueflo.tech/v1/coverage`
- The datasets behind any fact: `https://blueflo.tech/v1/sources`
- OpenAPI: `https://blueflo.tech/openapi.json`

There is also a hosted MCP server at `https://blueflo.tech/mcp` (Streamable HTTP, no key, read-only).
Add it to any MCP client as a remote server by that URL. It is generated entirely from
the OpenAPI document -- no endpoint is named in its code -- so it gains a tool whenever
the API gains a read endpoint, unless the route is marked API-only with its reason, and
its calls share the API's per-client rate limit. `https://blueflo.tech/mcp` lists the tools; the
reasons are in openapi.json as `x-mcp-why`.

Every response is fully typed in that OpenAPI document — request AND response — so a
client, or an MCP server, can be generated from it without reading our source. Each
operation carries a stable `operationId`, which is what to use as a tool name: it does
not change if a path moves. Endpoints
returning agency records also carry a `columns` list giving the label for every field,
because `originalcertifybydate` is not self-explanatory and should not be guessed at.

Human-readable pages live at `https://blueflo.tech/b/<slug>`, with `/timeline` and `/records`.

## Limits

There is a per-client budget, and it is not a paywall — we want this data used. It
exists because two of the three things that break first are not ours to spend: the
address autocomplete forwards to a free service run by NYC's Department of City
Planning, and an uncached record falls back to a query under our NYC Open Data token,
which the nightly pipeline also depends on.

- Most endpoints: 120/min per client, bursting to 30.
- `/v1/search` and `/v1/buildings?address=`: 20/min, because they spend
  somebody else's quota rather than reading a file off our disk.
- Over budget returns `429` with `Retry-After` in seconds. Honour it.

Bulk or sustained use is welcome and these numbers are not the answer to it — ask,
and we will work something out rather than have you engineer around a limiter.

Cards, systems, records, units and coverage are all served from disk and none of them
calls an agency at request time, so walking those is cheap for us. Prefer them to
repeated `?address=` lookups.

## Coverage

26330 buildings indexed: Manhattan (26329), Unknown (1). Coverage grows a neighbourhood at a time;
an un-indexed building returns 404 rather than a guess.

## What this will not tell you

- Which apartment anything happened in. Records are building-level by design.
- The names of individual owners. Companies are named; individuals are not.
- Anything usable for tenant screening. That use is prohibited by the terms.
- Valuations, listings or rent history. Those belong to other sites; we link out.

## Citing

Quote the sentence and its as-of date together: a record true in March may be
closed by June. Every fact object carries `source_name` and `as_of` for this.