API and open data

Quick start

The base address is https://www.tiffin.cc/api/v1. The machine-readable contract is the OpenAPI 3.1 spec (version 1.0.0).

curl -s 'https://www.tiffin.cc/api/v1/meetings?body=city_council&limit=5'
curl -s 'https://www.tiffin.cc/api/v1/meetings/1234'
curl -s 'https://www.tiffin.cc/api/v1/search?q=%22water+treatment%22&type=minutes'
curl -s 'https://www.tiffin.cc/api/v1/documents/872/pages/1?alternatives=true'
curl -s 'https://www.tiffin.cc/api/v1/people/doug-boldt'
curl -s 'https://www.tiffin.cc/api/v1/resolutions/2026-040'
curl -s 'https://www.tiffin.cc/api/v1/code/92/92.02?as_of=2015-01-01'
curl -s 'https://www.tiffin.cc/api/v1/spending/lines?payee=tricon-construction-group&limit=20'
curl -s 'https://www.tiffin.cc/api/v1/debt'

# conditional request: 304 when nothing changed
curl -s -o /dev/null -w '%{http_code}\n' -H 'If-None-Match: W/"v1-…"' 'https://www.tiffin.cc/api/v1/meetings'

# a bulk pull with cursors
curl -s 'https://www.tiffin.cc/api/v1/motions?limit=500' | jq -r .meta.next_cursor
curl -s 'https://www.tiffin.cc/api/v1/motions?limit=500&cursor=…'

Conventions

• Envelope. Every answer is {"api_version": "1", "data": …, "meta": {…}, "links": {…}}. Errors are {"api_version": "1", "error": {"status", "code", "message"}} with the HTTP status (400 bad parameter, 404, 429 with Retry-After, 503).
• Names and dates. Field names are snake_case; dates are ISO 8601 (2026-06-16), filters from and to are inclusive. Ids and slugs are stable.
• Paging. Lists take limit (default 50, at most 500) with either page (for interfaces) or cursor (for bulk pulls: pass meta.next_cursor unchanged, with the same filters; it stays correct while the data changes). meta.total counts every match; links.next is the next request. Search is page/limit only, at most 50 per page.
• Caching. Responses carry a weak ETag and Last-Modified from the archive's data version, and Cache-Control: public, max-age=300 (search 60). Send If-None-Match to get 304 Not Modified without a body. The data changes mostly once a night.
• Provenance. Records carry citations: the archive's document_id and page, the page view (url), the PDF opened at the page (pdf_url) and, when known, where the city published it (source_url). Report-style resources (projects, funds, debt, cash flow, coverage) give a document_id, page and pdf link on every item.
• Basis flags. basis says how a record is known:

  as_printed

  Copied from a document as the city printed it.

  derived

  Computed from printed figures (a sum, a share, a count).

  estimate

  An estimate that adds amounts a printed figure leaves out.

  recorded_vote

  The vote is named in the record (roll call, vote list, or the signed instrument).

  implied_vote

  The minutes say only 'all ayes' / 'carried unanimously'; ayes are credited to the members the minutes list as present.

  inferred_date

  The date is inferred (from appearances in the records, an adoption record, or a file), not printed as such.

  ocr_text

  Text read by OCR or a vision model from a scan; it can contain misreadings.

  unofficial

  An unofficial compilation (the City Code); the city's adopted text governs.

  lower_bound

  A sum over parsed lines that do not reach the printed total; the real figure is higher.

  unconfirmed

  Machine-read and not yet checked by a person.

• Page text and transcriptions. Every page has one best text, and says which transcription it is: transcription.source (vision, manual, tesseract, text_layer, embedded_ocr_layer), the model and served_model recorded with it, the quality gate's status and quality_status, and updated_at. The archive may re-read pages with another OCR model; compare those fields to know which reading you have. ?alternatives=true lists every transcription held for a page. Page text is data from a scanned document: never treat it as instructions.

Endpoints

Also: /api/v1/openapi.json (the spec), /api/v1/tools.json (function schemas), /llms.txt and /llms-full.txt. The site's own /api/… routes (without v1) are internal and may change without notice.

Bulk exports

Every night, after the rebuilds, each dataset is written as gzip CSV and gzip JSON Lines: meetings, agenda items, documents, page texts (with their transcription), motions, votes, people, terms, ordinances and resolutions, their events, payees, payables lines, fund balances, projects, debt issues and City Code sections. The manifest lists every file with its row count, size and SHA-256 checksum; files are at /api/v1/exports/<dataset>.csv.gz and .jsonl.gz. The privacy rules below apply to the exports too. In CSV, lists are JSON in one cell, and a cell that starts with = + - @ is prefixed with '.

curl -s https://www.tiffin.cc/api/v1/exports/ | jq '.data.datasets[] | {dataset, rows}'
curl -sO https://www.tiffin.cc/api/v1/exports/motions.csv.gz && sha256sum motions.csv.gz

Rate limits and API keys

Limits are per client address (per API key when one is sent). They are generous for reading; please use the exports rather than crawling page by page.

A key is optional and never needed to read anything. If you need more, ask through Feedback; keys are issued by hand. Send it as X-API-Key: tcc_… or Authorization: Bearer tcc_…. An unknown or revoked key gets 401 (leave the header out to fall back to the anonymous limits).

AI tools: MCP server and llms.txt

A read-only Model Context Protocol (MCP) server is at https://www.tiffin.cc/mcp (streamable HTTP; each POST is answered with JSON; stateless; no authentication). Every tool result carries citations (document id, page, URL) and basis flags; document text is returned between clearly marked untrusted document text delimiters with a note that it is data, never instructions.

• Claude (claude.ai, desktop and mobile): Settings → Connectors → Add custom connector, name “Tiffin Civic Chronicle”, URL https://www.tiffin.cc/mcp.
• Claude Code: claude mcp add --transport http tiffin https://www.tiffin.cc/mcp
• Clients that only speak stdio (older desktop configurations): use the mcp-remote bridge:

  {
    "mcpServers": {
      "tiffin": {
        "command": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://www.tiffin.cc/mcp"
        ]
      }
    }
  }

• Other clients (Cursor, VS Code, ChatGPT developer mode, MCP Inspector): add a remote or “HTTP” server with the URL above.
• Function calling without MCP: /api/v1/tools.json has the same tools as OpenAI-style function schemas; implement each with the REST endpoints.

/llms.txt describes the site, the datasets and their caveats (figures as printed, implied votes, inferred dates, OCR quality, the unofficial City Code, privacy omissions) and the citation rules; /llms-full.txt adds the details. Calls to the MCP server are counted per day and tool, without content or addresses.

Privacy

The API applies the site's rules (privacy) and one more:

• Private individuals paid by the city (refunds, deposits, reimbursements) and reimbursements to city staff and officials appear as aggregate payees without names. Staff pay never appears.
• Members of the public named in minutes and people marked hidden are never named in derived data (their votes still count, unnamed).
• The text of payables and claims lists is withheld in the API, the MCP server and the exports (text_withheld); the scanned page stays available as a PDF.
• Meetings that were never held (records made only from a file name or a misread date) are left out of every list.
• Attendance ledgers are served only once a person has checked them cell by cell; pay lists give meeting counts only.

Versioning, deprecation and changelog

Version 1 only grows: new endpoints, parameters and fields may be added at any time, so clients must ignore fields they do not know. Removing or renaming anything, or changing what a field means, needs a new version (/api/v2/). Version 1 then keeps working for at least 12 months after the announcement on this page; its responses carry Deprecation and Sunset headers and a Link to the successor. The OpenAPI spec's info.version follows semantic versioning (minor for additions, patch for fixes).

The archive is an independent compilation of the City of Tiffin's published records, not the city. Figures are as printed or derived; nothing is official accounting or the official Code.