API and MCP status
Operational · checked 2026-11-18 15:11:24 UTC
Live checks of what machines call: the REST API at https://flatin.pt/api/v1 and the MCP server at https://flatin.pt/mcp. Each check runs the same code that answers an outside request. Results are cached for 30 seconds. If this page does not load at all, the service is down.
Components
| REST API | Operational | IMT calculation, IMI rates and rate history answer · 4 ms |
| MCP server | Operational | tools/list answers (15 tools); imi_rate answers · 3 ms |
| Database | Operational | connection answers (the request form uses it; the API does not) · 3 ms |
| Tax tables up to date | Operational | IMI rates table (tax year): 2025; IMT tables: 2026; CIMI articles 112, 113, 120 checked against the source: 2026-09-14; Mortgage market rate (BPstat month): 2026-08; Bank mortgage terms table (oldest row check): 2026-10-11 · 0 ms |
| Dated facts re-read on time | Operational | 218 facts, 0 past review, next 2026-12-11 · 2 ms |
Data
IMI rates for tax year 2025, 308 municipalities, checked against the Autoridade Tributária portal on 2026-09-12.
IMT and stamp duty tables for 2026; IMI articles of the CIMI checked against the source on 2026-09-14.
Deployed version: 475800a635fe37e139f460f0670231c4c481ea8d
Changelog
- 2026-10-30 — Dated facts: /api/v1/facts.json
- New GET /api/v1/facts.json: dated facts about Portugal for home buyers, one value per row, with what kind of value it is, the day we state it from, the review date, the official source and a verbatim quote in Portuguese. Each value is checked against its official source. A row leaves the file after its review date, and past_review names those rows.
- 2026-10-27 — MCP server 3.0.0: submit_consultation is its own tool
- Breaking: sending a request to flatin.pt is now its own tool, submit_consultation, with the same arguments the old mode=submit took (the details from prepare, confirmation_token, consent=true, consent_text_version) and destructiveHint: true, so clients ask the person before the call. request_consultation keeps mode=link and mode=prepare, sends nothing and is marked readOnlyHint: true; mode=submit there now returns invalid_input naming submit_consultation. Tokens from prepare work unchanged. POST /api/v1/consultation keeps its mode field (link, prepare, submit). Every tool description now starts with when to use the tool and says when not to, naming the tool to use instead; every tool declares securitySchemes [{type: noauth}] at the top level and in _meta. Server version 3.0.0 in initialize, the server card and server.json.
- 2026-10-26 — Monthly report: completion ratio, case ages and municipality cards
- From the November 2026 edition, the CSV and JSON of the monthly report 'Obra nova em Portugal' (/api/v1/reports/obra-nova/{edition}.csv|.json) carry new columns at the end: dwellings completed per 100 licensed two years earlier (INE, with the window, INE status and both sums) and, for municipalities with a licensing layer, the median age of licensing cases with its case count. Earlier editions keep their figures and leave the new cells empty; unknown values are empty with unknown_reason, never 0. New /api/v1/reports/obra-nova/{edition}/cards/{code}.png: a 1200×630 PNG card in Portuguese for any of the 308 municipalities, drawn from the frozen edition, with ETag.
- 2026-10-26 — Age of licensing cases: /api/v1/licensing-duration
- GET /api/v1/licensing-duration and /api/v1/licensing-duration.csv publish the age of licensing cases in progress, frozen monthly with the barometer edition (vintage= returns an earlier edition): for Porto, pending ages from the council's in-progress list and observed exits; for Lisbon, days from application to the date of the title and the share titled within 90, 180 and 365 days before and after 3 August 2026, compared at equal age. municipality_housing_pipeline (MCP and /api/v1/funnel) gains a durations section. A cell with too few cases is null with unknown_reason, never 0.
- 2026-10-26 — Housing pipeline: url points to the page of all 308 municipalities
- In GET /api/v1/funnel and the municipality_housing_pipeline MCP tool, url (and the attribution page) now points to the barometer page with the table of all 308 municipalities and the map of dwellings completed per 1,000 residents (for example https://flatin.pt/en/construction-barometer/municipalities/), instead of the #funnel section of the barometer, which now shows only the national stages. Fields and values are unchanged.
- 2026-10-25 — MCP server 2.3.0: required_income; POST /api/v1/mortgage/calculate
- POST /api/v1/mortgage/calculate takes the fields of the mortgage calculator page (price, down, term, use, young, territory, age, income, debts, rate) as JSON and returns the same numbers as the page: monthly and stressed payment, min_income_cents (net monthly income of the borrowers at the Banco de Portugal 45 % debt-service limit), upfront_cents (cash at the deed), the rate with its month and the source documents of every rule. Invalid input gets 422 with error, field and message. New MCP tool required_income(price, territory): the same calculation in one fixed scenario (buyer aged 30, permanent own home, 40-year loan, minimum deposit, IMT Jovem), returning min_net_monthly_income_cents and savings_needed_cents; unknown arguments are refused (unknown_argument). tools/list carries outputSchema for all 14 tools. Server version 2.3.0 in initialize and the server card.
- 2026-10-25 — Open data of the 308 municipalities
- New dataset GET /api/v1/open-data-coverage.csv and its JSON twin GET /api/v1/open-data-coverage, under CC BY 4.0: one row per municipality, all 308, by population, saying whether the municipal council publishes its building-works cases as open data, what that data carries, our coverage status and the status and dates of our access request. Values not yet checked are unknown, never no or 0. The same table is a page under the construction barometer in seven languages.
- 2026-10-25 — Housing pipeline per municipality: /api/v1/funnel and a new MCP tool
- GET /api/v1/funnel?municipality= and the municipality_housing_pipeline MCP tool return one municipality's housing pipeline stage by stage: building-works cases (where we collect them), ADENE pre-certificates, INE dwellings licensed (12 months and last year) and completed (last year), units for sale and unpriced developments in our catalogue, and completed / licensed over three years with a two-year lag. Without municipality, /api/v1/funnel lists all 308; /api/v1/funnel.csv has one row per municipality and stage (CC BY 4.0). Every row carries its own period, source_url and checked_on; a value we do not hold is null with unknown_reason, never 0; ine_status marks INE's provisional and estimated years.
- 2026-10-24 — New-build developer can be null
- Some projects in the catalogue come from an estate agency's listing, and their developer is not confirmed. For those projects developer is null in GET /api/v1/newbuilds, GET /api/v1/newbuilds/{slug} and in the search_newbuilds and get_newbuild MCP tools, whose output schemas now allow null. Before, developer was always an object.
- 2026-10-23 — MCP server 2.2.0: request_consultation takes several places and a budget range
- flatin.pt handles buyers of new-build apartments only. request_consultation and POST /api/v1/consultation take places (a list of municipalities or districts, most important first) and budget_min / budget_max in whole euros; city still works and is merged with places, city first. deal_type and property_type are deprecated and ignored: every request is recorded as buying an apartment, and sell, rent or house are accepted without an error. budget is deprecated and read as budget_max; budget_band (0-250k, 250-400k, 400-600k, 600k+) is read as its range; both only when budget_min and budget_max are empty. The prepare summary gains places, budget_min_eur and budget_max_eur; city, property_type, deal_type and budget_eur stay (budget_eur equals budget_max_eur). Server version 2.2.0 in initialize and the server card.
- 2026-10-22 — request_consultation: requests are handled by flatin.pt itself
- flatin.pt now holds its own estate-agency licence (AMI licence no. 28163). request_consultation and POST /api/v1/consultation send the request to flatin.pt, which answers it itself; the tool title, description and the text returned on success say so. The success text no longer names a response time. Parameters, the two-step confirmation and the answer fields are unchanged.
- 2026-10-19 — MCP server 2.1.0: output schemas and rewritten tool descriptions
- tools/list now carries outputSchema for all 12 tools: every success mode and the refusal (an error code) as branches, with the top-level fields, their types and which are always present; units are named (*_cents euro cents, percent fields in percent). The schemas do not forbid extra fields. Each description now starts with what the tool does, says when to use it and which sibling tool to use instead, and states how parameters combine (for example, tax_haven_company takes precedence over non_resident). inputSchema gains default values, examples, format: email and limits the server already enforced; language has the same values (pt, en, ru, ua, de, fr, nl, uk) in every tool that takes it. Answers are unchanged. Server version 2.1.0 in initialize, the server card and server.json.
- 2026-10-11 — Construction barometer in the discovery documents; full /api/v1 index
- The APIs.json index has a fourth API, flatin-pt:barometer, with its four datasets (GET /api/v1/barometer/series.csv, /barometer/series, /barometer/official.csv, /barometer/sce.csv), each named with its own source and terms: our case counts under CC BY 4.0, the INE mirror under INE's licence with credit to INE, the ADENE mirror with a credit and no licence, because ADENE declares none. The index-wide License property now says that CC BY 4.0 covers our own datasets only. GET /api/v1 now lists every endpoint in the OpenAPI schema, with its summary, and links the terms of use; llms.txt names the barometer datasets. No data endpoint changed; GET /api/v1 gained the summary and terms fields.
- 2026-10-11 — IMT for a non-resident buyer and for a listed-regime company
- imt_calculate and POST /api/v1/imt/calculate accept non_resident (boolean, default false) for a buyer who is not and has never been tax resident in Portugal. IMT is then the flat rate of CIMT art. 17.º n.º 10 (Decreto-Lei n.º 97/2026) on the taxable value, with no exemption or reduction: no zero band, no young buyers' table and no stamp duty deduction. They also accept tax_haven_company (boolean, default false) for a company domiciled in, or controlled from, a jurisdiction on the Portuguese list of more favourable tax regimes: 10 % under n.º 4, which overrides non_resident and never applies to an individual. New fields: input.non_resident, input.tax_haven_company, imt_regime (tables, non_resident_flat or tax_haven_flat) and annullable: null unless imt_regime is non_resident_flat, otherwise what the Tax Authority annuls on request (n.º 11–12) if the buyer becomes tax resident (if_resident_cents) or lets the home at a moderate rent (if_let_cents), with the months of each window, the request deadline, formatted amounts and the source. A resident answer now carries a note saying it assumes a buyer who is or has been tax resident. A value that is not true or false gets 422 bad_flag with the field name. Without the two flags nothing changes in the amounts.
- 2026-10-10 — New-build projects: location precision and approximate area
- Every project in GET /api/v1/newbuilds, GET /api/v1/newbuilds/{slug} and the MCP tools search_newbuilds and get_newbuild now carries location_precision: exact, approximate (a street-level point), area (the developer does not publish the address; the project is placed in a named parish or neighbourhood) or municipality (only the municipality is known). For area, location stays null so that no client draws a pin at the centre of a neighbourhood, and the new field area gives name, kind (parish or place), dicofre (parishes only), center and radius_m (places only); no polygon. Existing fields are unchanged.
- 2026-10-09 — MCP server 2.0.0: instructions, card and English place names
- The MCP server describes its whole scope: initialize returns instructions on which tool to use when (taxes, where to live, municipality data, new-build search, glossary), that the two write tools act only after the person's explicit consent (prepare, then submit), and that answers should cite the flatin.pt URL and the attribution. Server version 2.0.0 in initialize, the server card and the MCP Registry entry pt.flatin/property-taxes, whose title and description now cover new-builds and places. imi_rate, imi_annual_cost, the REST IMI endpoints, request_consultation and subscribe_digest accept English and other exonyms (Lisbon, Oporto) like the other tools.
- 2026-10-09 — Acting on the person's behalf: a request and a subscription
- request_consultation can now send the request itself, in two steps: mode=prepare checks the details (name, phone with a preferred channel or else email, city or project, language) and returns a summary, the GDPR consent text in the person's language, consent_text_version and a confirmation_token; mode=submit sends it with the same details, the token, consent=true and the text version, only after the person has read the text and agreed. Changed details, a missing consent or an outdated text are refused. mode=link (the default) answers as before, and consent_version stays in that answer. The tool is now annotated as writing (readOnlyHint false, openWorldHint true). New tool subscribe_digest subscribes an email to new-build developments matching a filter (daily) or to licensed construction in a municipality (weekly); it only sends a confirmation email, and nothing is active until the person clicks. REST twins with the same body and answer: POST /api/v1/consultation and POST /api/v1/subscriptions (422 on invalid input, 429 with Retry-After).
- 2026-10-09 — New-build projects: search and one project, over REST and MCP
- GET /api/v1/newbuilds searches the new-build projects published on flatin.pt by municipality, parish, typology (T0-T5), price_min and price_max, stage, delivery_by, energy_class and on_sale, with sort, limit (up to 50) and offset; each result carries the price range per typology, stage, promised delivery, developer, coordinates and the canonical page URL, and catalog_url is the same selection on the site. GET /api/v1/newbuilds/{slug} returns one project: units and prices per typology with price history, delivery promises, linked building permits, the purchase cost at the cheapest available price (IMT, stamp duty, registration; primary_home and buyer_is_young), nearby places and the page URL in all seven languages. The same answers come from the new MCP tools search_newbuilds and get_newbuild. Unknown parameters and values outside the listed ones are refused with 400, an error code and the field.
- 2026-10-09 — Places and statistics: where to live, municipalities, glossary
- Five new MCP tools, each with a REST twin under /api/v1 that returns the same data. where_to_live (GET /where-to-live, /where-to-live/{city}): the verdict of a where-to-live guide by area (live, depends, avoid) with the reason, who it suits and the sources, plus noise and dated, sourced safety sections; filters profile, verdict and include. municipality_stats (GET /municipalities/{municipality}/stats): IMI rate and history, INE median sale price, purchasing power, population, licensed buildings and new dwellings, municipal building-works cases, the barometer row and catalogue new-builds, each with source and date; a figure that is not published is null. compare_municipalities (GET /municipalities/compare): the same for 2 to 5 municipalities. construction_barometer (GET /construction-barometer): the 12-month summary and index, or one municipality's series with INE's yearly licences. glossary_lookup (GET /glossary, /glossary/{term}): definition, articles of law and the page. Municipality names are matched loosely (case, accents, Lisbon, typos); every answer takes language (pt, en, ru, ua, de, fr, nl) for the site content and carries the page link and an attribution object.
- 2026-10-09 — MCP Registry: version 1.0.4, old GitHub versions deprecated
- The MCP Registry entry pt.flatin/property-taxes has a new version, 1.0.4; the entry differs from 1.0.3 only in the version: its repository has been gitlab.com/flatin-pt-group/mcp since 1.0.3 (24 September). Versions 1.0.1 and 1.0.2, whose repository links point at suspended GitHub accounts, are marked deprecated.
- 2026-10-01 — IMT and stamp duty on the higher of the price and the VPT
- imt_calculate and POST /api/v1/imt/calculate accept an optional vpt (the valor patrimonial tributário from the caderneta predial, in euros). IMT and stamp duty are charged on the higher of the contract price and the VPT (CIMT art. 12.º n.º 1; Código do Imposto do Selo art. 9.º n.º 4): the new taxable_value_cents is that base, taxable_base says which one it is (price or vpt), and input.vpt_cents echoes the VPT or is null. Without vpt nothing changes in the amounts, and the first note says a higher VPT would raise both taxes. New refusals bad_vpt and not_positive_vpt come with field vpt; too_large can now also come with field vpt. Amounts written with a dot for thousands (250.000 or 123.456,78) are now read as thousands: they used to be read as decimals, so 250.000 was 250 EUR. deed_source now also carries the price list itself: single_act_cents and extra_property_cents, with formatted amounts.
- 2026-09-28 — Deed and registration: a published price instead of an estimate
- notary_estimate_cents used to be 90000 (900 EUR), a mid-range guess with no source behind it. It is now 37500 (375 EUR), the published price of one registration act at the Casa Pronta counter of the Ministério da Justiça, and total_cents falls by the same 52500. The new deed_source field carries the URL and the name of that price list. Read the field as the registration only: the purchase contract at a notary, buying with a mortgage and the agency fee are not in it, and notes now say so. Annual IMI is still not part of total_cents: it is charged on the VPT, not on the purchase price.
- 2026-09-24 — Google Sheets add-on
- FLATIN_IMT, FLATIN_SELO, FLATIN_IMI_RATE and FLATIN_IMI put the same numbers into a spreadsheet cell, over the same keyless API, with answers cached for six hours. The add-on has its own privacy policy page in all seven languages.
- 2026-09-24 — Open-source repositories moved to GitLab
- GitHub suspended two accounts of ours in a row, so the MCP bridge, WordPress plugin, browser extension, QGIS plugin and Sheets add-on now live at gitlab.com/flatin-pt-group. The MCP Registry entry points there from version 1.0.3.
- 2026-09-24 — Glossary of Portuguese property and tax terms
- Nineteen terms (IMT, IMI, AIMI, CPCV, caderneta predial, VPT and more) in all seven languages of the site, each with the article of the tax code it comes from, a link to the official source and the date it was checked. Listed in llms.txt.
- 2026-09-24 — Embeddable IMT calculator
- Any site can embed the IMT calculator with one script tag: /embed/imt-1.js renders the form and the result into the host page, in the seven languages of the site, without cookies or storage. The credit link lives in the snippet the site owner pastes, never injected by the script.
- 2026-09-24 — Press kit and dataset DOI
- A press page for journalists in all seven languages: the findings, charts in PNG and SVG, the methodology and the ready credit line, with every number computed from the published tables. The dataset is archived on Zenodo; its concept DOI 10.5281/zenodo.22935147 is now the identifier in the Dataset markup and is shown on the open-data page.
- 2026-09-16 — Open-source repositories moved
- The MCP bridge, WordPress plugin, browser extension and QGIS plugin moved to a second GitHub account after the first one was suspended; the MCP Registry entry pt.flatin/property-taxes pointed there in version 1.0.2. The second account was suspended on 24 September, and the code has lived at gitlab.com/flatin-pt-group since then.
- 2026-09-16 — Stamp duty relief for buyers aged 35 or under
- imt_calculate (REST and MCP) now applies the Imposto do Selo deduction of art. 7.º-A of the Código do Imposto do Selo (Decreto-Lei n.º 48-A/2024) when buyer_is_young and primary_home are both true: stamp duty is reduced by up to 0.8 % of the first band limit of the young buyers' IMT table. stamp_duty_cents is the amount due after the deduction; the new field stamp_duty_relief_cents shows the deduction. No deduction is applied above the second band of the young buyers' table, following official guidance. Previously stamp duty was charged in full.
- 2026-09-16 — IMI rates as GeoJSON and a multi-year CSV
- GET /api/v1/imi/rates.geojson returns the IMI rates of all 308 municipalities with municipal boundaries (CAOP2025, Direção-Geral do Território, simplified); year selects a verified past year. GET /api/v1/imi/rates-history.csv returns every verified tax year in one long-format file. A QGIS plugin reads the GeoJSON.
- 2026-09-16 — MCP tools declare their behaviour
- Every MCP tool has a title and the annotations readOnlyHint (true), destructiveHint (false), idempotentHint (true) and openWorldHint (false). A server card is served at /.well-known/mcp/server-card.json. imi_rate and imi_annual_cost say that municipalities are looked up by their Portuguese name (Lisboa, not Lisbon).
- 2026-09-16 — CORS preflight answered
- OPTIONS requests to existing /api/* addresses get 204 with CORS headers, so browsers can POST JSON to /api/v1/imt/calculate. Before, the preflight got 405 and browsers dropped the request.
- 2026-09-16 — Discovery documents, status page, English by default
- Published an APIs.json index (/.well-known/apis.json), an RFC 9727 api-catalog, an API Onboarding Descriptor, machine-readable plans and rate limits, a Spectral ruleset, security.txt, llms.txt and a live status page (/status/). The OpenAPI schema is also served at /openapi.json. Clients that send no Accept-Language now get the English site.
- 2026-09-16 — Open-source clients
- Published the stdio bridge for the MCP server, the WordPress plugin and the Chrome extension. All of them call this API. Their source is at gitlab.com/flatin-pt-group (mcp, wp, chrome) since 24 September.
- 2026-09-16 — MCP server listed in the official MCP Registry
- The remote server https://flatin.pt/mcp is published in registry.modelcontextprotocol.io as pt.flatin/property-taxes.
- 2026-09-16 — All machine answers in English
- MCP tool descriptions and results, REST API errors and 429 refusals are in English. The consent text of request_consultation is still returned in the user's language.
- 2026-09-15 — Rate limits
- Per-address limits on the REST API and the MCP server. A refused request gets HTTP 429 with a Retry-After header.
- 2026-09-15 — MCP protocol version is checked
- Requests declaring an MCP protocol revision the server does not speak get HTTP 400 with the list of supported revisions.
- 2026-09-15 — IMI rate history
- GET /api/v1/imi/rates/{codigo} returns a history field: the municipality's urban rate by tax year and whether it went up, down or stayed.
- 2026-09-13 — Public REST API v1 and MCP server
- IMI rates for all 308 municipalities as JSON and CSV, IMT and stamp duty calculation on a purchase, and the MCP tools imt_calculate, imi_rate, imi_annual_cost and request_consultation. No key, no sign-up.