{ "openapi": "3.1.0", "info": { "title": "Lettance public API", "version": "1.0.0", "summary": "Landlord rules and council licensing in England, with sources.", "description": "Lettance is landlord-operated AI letting software for tenant messages, repair preparation, rent records and approved reminders, certificates and a registration-information pack. The current new workspace offer is £29 per home per month; existing subscriptions keep their agreed legacy terms until explicitly changed. Check https://lettance.com/pricing for prices, limits and availability. Public reference access described by this OpenAPI document remains free.\n\nRead-only data for private landlords in England from Lettance: the licence answer for a postcode, a home's dated plan for the next 12 months, a side-by-side comparison of 2 to 4 postcodes, local rents and sale prices from a dated ONS and HM Land Registry snapshot, every English council's licensing research, and a catalogue of landlord rules, each linked to legislation.gov.uk or GOV.UK.\n\nAnswers have `data` and `meta`; errors have `error` and `meta`. `meta.sources` lists the upstream sources the answer draws on, `meta.coverage` says how much of England the council research covers, and `meta.notice` says how to use the answer. Show status, confidence, sources and open questions to your users. This is information, not legal advice.\n\nNo key is needed. Requests are limited to 120 per IP address in a 10-minute window (see the RateLimit headers); a comparison counts once per postcode. Past the limit you get 429 with Retry-After. Responses never include EPC register addresses, accounts or saved property records.\n\nPrivate account access is separate: https://lettance.com/mcp/account requires a paid Lettance plan and OAuth or a personal access token. It lets the landlord's own AI read saved home records and document findings, not original files; directly record reported checks and rent received with write access; and prepare repair-update or renewal-start confirmation cards. The landlord confirms those proposals in Lettance. It does not send tenant messages. This public REST schema contains no private account operations. Connection guide: https://lettance.com/assistants. The product homepage is https://lettance.com/; the free address checker is https://lettance.com/check.", "termsOfService": "https://lettance.com/terms", "contact": { "name": "Lettance", "url": "https://lettance.com/developers", "email": "gm@galleonlabs.io" } }, "externalDocs": { "description": "Developer guide", "url": "https://lettance.com/developers" }, "servers": [ { "url": "https://lettance.com", "description": "Production" } ], "security": [], "tags": [ { "name": "Address check", "description": "The licence answer and planning context for one postcode." }, { "name": "Compare and market", "description": "Postcodes side by side, and local rents and sale prices from a dated open-data snapshot." }, { "name": "Councils", "description": "Council licensing research for every English council." }, { "name": "Rules", "description": "The cited catalogue of landlord rules in England." }, { "name": "Rental plan", "description": "A home's dated plan for the next 12 months, from its postcode and the landlord's answers." } ], "paths": { "/api/v1/check": { "get": { "operationId": "checkAddress", "tags": [ "Address check" ], "summary": "Rules for a rental postcode", "description": "Council licence answer for a postcode in England and a household type, with matching schemes, the planned landlord register window, flood zone, conservation areas and Article 4 directions. A postcode cannot settle a street-level boundary.", "parameters": [ { "name": "postcode", "in": "query", "required": true, "description": "A full UK postcode in England, with or without the space.", "schema": { "type": "string", "minLength": 5, "maxLength": 16, "examples": [ "SE15 5BA" ] } }, { "name": "household", "in": "query", "required": false, "description": "single: one household (default). small_hmo: 3 or 4 people from 2 or more households. large_hmo: 5 or more people from 2 or more households.", "schema": { "type": "string", "enum": [ "single", "small_hmo", "large_hmo" ], "default": "single" } } ], "responses": { "200": { "description": "The licence answer and context for the postcode.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckResponse" } } } }, "400": { "description": "The postcode or household is missing or not valid.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such postcode.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The postcode is outside England. Only England is covered.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The postcode service did not answer. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/plan": { "get": { "operationId": "planRental", "tags": [ "Rental plan" ], "summary": "A rental's dated plan", "description": "Every duty for one rented home with its status, date and cited rules for the next 12 months, from the postcode and the landlord's optional answers. Returns the questions still worth asking. Statuses rely on those answers, not documents.", "parameters": [ { "name": "postcode", "in": "query", "required": true, "description": "A full UK postcode in England, with or without the space.", "schema": { "type": "string", "minLength": 5, "maxLength": 16, "examples": [ "SW9 7AA" ] } }, { "name": "household", "in": "query", "required": false, "description": "single: one household (default). small_hmo: 3 or 4 people from 2 or more households. large_hmo: 5 or more.", "schema": { "type": "string", "enum": [ "single", "small_hmo", "large_hmo" ], "default": "single" } }, { "name": "let", "in": "query", "required": false, "description": "Whether the home is let. Optional.", "schema": { "type": "string", "enum": [ "now", "next" ] } }, { "name": "start", "in": "query", "required": false, "description": "The tenancy start date, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "gas", "in": "query", "required": false, "description": "Whether the home has gas. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "gas_check", "in": "query", "required": false, "description": "The date of the last gas safety check, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "eicr", "in": "query", "required": false, "description": "The date of the last electrical inspection, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "eicr_next", "in": "query", "required": false, "description": "The next inspection date on the electrical report, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "epc", "in": "query", "required": false, "description": "The EPC rating. Optional.", "schema": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G" ] } }, { "name": "epc_expiry", "in": "query", "required": false, "description": "The date the EPC expires, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "licence", "in": "query", "required": false, "description": "Whether you hold the licence. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "licence_end", "in": "query", "required": false, "description": "The date the licence ends, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "deposit", "in": "query", "required": false, "description": "Whether you took a deposit. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "deposit_on", "in": "query", "required": false, "description": "The date you received the deposit, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "deposit_done", "in": "query", "required": false, "description": "Whether the deposit was protected in time. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "rtr", "in": "query", "required": false, "description": "Whether the right to rent checks were done. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "terms", "in": "query", "required": false, "description": "Whether the tenancy document was given. Optional.", "schema": { "type": "string", "enum": [ "yes", "late", "no" ] } }, { "name": "alarms", "in": "query", "required": false, "description": "Whether the alarms were tested. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "increase", "in": "query", "required": false, "description": "The date of the last rent increase, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "period", "in": "query", "required": false, "description": "How often the rent is due. Optional.", "schema": { "type": "string", "enum": [ "month", "four_weeks", "fortnight", "week" ] } }, { "name": "furnished", "in": "query", "required": false, "description": "Whether the home is furnished. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } } ], "responses": { "200": { "description": "The plan.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanResponse" } } } }, "400": { "description": "The postcode is missing or not valid, or an answer is not valid. The message names each problem.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such postcode.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The postcode is outside England. Only England is covered.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The postcode service did not answer. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/plan/calendar": { "get": { "operationId": "planRentalCalendar", "tags": [ "Rental plan" ], "summary": "A rental's plan as a calendar file", "description": "The same plan's future dates as an iCalendar (.ics) file, with reminders 30 and 7 days before certificate, licence and register dates. Takes the same parameters as planRental. Calendar apps can subscribe to the address.", "parameters": [ { "name": "postcode", "in": "query", "required": true, "description": "A full UK postcode in England, with or without the space.", "schema": { "type": "string", "minLength": 5, "maxLength": 16, "examples": [ "SW9 7AA" ] } }, { "name": "household", "in": "query", "required": false, "description": "single: one household (default). small_hmo: 3 or 4 people from 2 or more households. large_hmo: 5 or more.", "schema": { "type": "string", "enum": [ "single", "small_hmo", "large_hmo" ], "default": "single" } }, { "name": "let", "in": "query", "required": false, "description": "Whether the home is let. Optional.", "schema": { "type": "string", "enum": [ "now", "next" ] } }, { "name": "start", "in": "query", "required": false, "description": "The tenancy start date, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "gas", "in": "query", "required": false, "description": "Whether the home has gas. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "gas_check", "in": "query", "required": false, "description": "The date of the last gas safety check, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "eicr", "in": "query", "required": false, "description": "The date of the last electrical inspection, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "eicr_next", "in": "query", "required": false, "description": "The next inspection date on the electrical report, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "epc", "in": "query", "required": false, "description": "The EPC rating. Optional.", "schema": { "type": "string", "enum": [ "A", "B", "C", "D", "E", "F", "G" ] } }, { "name": "epc_expiry", "in": "query", "required": false, "description": "The date the EPC expires, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "licence", "in": "query", "required": false, "description": "Whether you hold the licence. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "licence_end", "in": "query", "required": false, "description": "The date the licence ends, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "deposit", "in": "query", "required": false, "description": "Whether you took a deposit. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "deposit_on", "in": "query", "required": false, "description": "The date you received the deposit, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "deposit_done", "in": "query", "required": false, "description": "Whether the deposit was protected in time. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "rtr", "in": "query", "required": false, "description": "Whether the right to rent checks were done. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "terms", "in": "query", "required": false, "description": "Whether the tenancy document was given. Optional.", "schema": { "type": "string", "enum": [ "yes", "late", "no" ] } }, { "name": "alarms", "in": "query", "required": false, "description": "Whether the alarms were tested. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } }, { "name": "increase", "in": "query", "required": false, "description": "The date of the last rent increase, as YYYY-MM-DD. Optional.", "schema": { "type": "string", "format": "date" } }, { "name": "period", "in": "query", "required": false, "description": "How often the rent is due. Optional.", "schema": { "type": "string", "enum": [ "month", "four_weeks", "fortnight", "week" ] } }, { "name": "furnished", "in": "query", "required": false, "description": "Whether the home is furnished. Optional.", "schema": { "type": "string", "enum": [ "yes", "no" ] } } ], "responses": { "200": { "description": "An iCalendar file.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "text/calendar": { "schema": { "type": "string" } } } }, "400": { "description": "The postcode is missing or not valid, or an answer is not valid.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such postcode.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The postcode is outside England. Only England is covered.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The postcode service did not answer. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/compare": { "get": { "operationId": "compareAddresses", "tags": [ "Compare and market" ], "summary": "Compare 2 to 4 rental postcodes", "description": "Each postcode's check and area market figures, plus a side-by-side table of licence need, register window, planning designations, rent and sale price. Every field names its source, licence and dates; unknown stays unknown. Counts once per postcode.", "parameters": [ { "name": "postcode", "in": "query", "required": true, "description": "Repeat 2 to 4 times, once per full postcode in England.", "style": "form", "explode": true, "schema": { "type": "array", "minItems": 2, "maxItems": 4, "items": { "type": "string", "minLength": 5, "maxLength": 16 }, "examples": [ [ "SE15 5BA", "SW6 1HS" ] ] } }, { "name": "household", "in": "query", "required": false, "description": "single: one household (default). small_hmo: 3 or 4 people from 2 or more households. large_hmo: 5 or more people from 2 or more households.", "schema": { "type": "string", "enum": [ "single", "small_hmo", "large_hmo" ], "default": "single" } } ], "responses": { "200": { "description": "The comparison. A postcode that could not be checked is listed with its error.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompareResponse" } } } }, "400": { "description": "Fewer than 2 or more than 4 postcodes, one is not valid, or the household is not valid.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The postcode service did not answer for any postcode. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/area-market": { "get": { "operationId": "getAreaMarket", "tags": [ "Compare and market" ], "summary": "Local rents and sale prices", "description": "ONS average private rent for the local authority and HM Land Registry median sale price and sales count for the postcode district, from a dated snapshot, with attribution. Area figures, not a valuation.", "parameters": [ { "name": "postcode", "in": "query", "required": true, "description": "A full UK postcode in England, with or without the space.", "schema": { "type": "string", "minLength": 5, "maxLength": 16, "examples": [ "SE15 5BA" ] } } ], "responses": { "200": { "description": "Rents and sale prices for the area.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AreaMarketResponse" } } } }, "400": { "description": "The postcode is missing or not valid.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No such postcode.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "The postcode is outside England. Only England is covered.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "503": { "description": "The postcode service did not answer. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/councils": { "get": { "operationId": "listCouncils", "tags": [ "Councils" ], "summary": "Every English council", "description": "Every current English council with its region, whether its licensing has been researched, research dates and counts of schemes and open questions.", "responses": { "200": { "description": "All councils.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouncilListResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/councils/{slug}": { "get": { "operationId": "getCouncilLicensing", "tags": [ "Councils" ], "summary": "One council's licensing", "description": "Every licensing scheme for an English council with wards, dates, fees, sources and open questions. A council not researched yet returns researched: false with its landlord register window. Not researched never means no licence.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Council slug such as southwark or tower-hamlets. A council name also works.", "schema": { "type": "string", "minLength": 1, "maxLength": 120, "examples": [ "southwark" ] } } ], "responses": { "200": { "description": "The council's licensing, or researched: false.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouncilResponse" } } } }, "404": { "description": "No English council matches.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/rules": { "get": { "operationId": "searchRules", "tags": [ "Rules" ], "summary": "List or search landlord rules", "description": "Without q, every rule in the catalogue. With q, up to 10 rules whose title, summary or topic match the words. Each has its status and a link to the full rule.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search words, for example gas safety or deposit.", "schema": { "type": "string", "maxLength": 500, "examples": [ "gas safety" ] } } ], "responses": { "200": { "description": "Matching rules.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleListResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/rules/{id}": { "get": { "operationId": "getRule", "tags": [ "Rules" ], "summary": "One landlord rule", "description": "The full rule: who it applies to, the requirement, deadline, evidence to keep, penalty, legal basis, official guidance, status and confidence.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Rule id from searchRules, for example gas-safety-annual-check.", "schema": { "type": "string", "minLength": 1, "maxLength": 120 } } ], "responses": { "200": { "description": "The rule.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RuleResponse" } } } }, "404": { "description": "No rule with that id.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Too many requests from this address. Wait for Retry-After seconds.", "headers": { "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" }, "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "Meta": { "type": "object", "properties": { "sources": { "type": "array", "items": { "type": "string", "description": "Absolute URL" }, "description": "Distinct upstream sources this response draws on: legislation, GOV.UK guidance, council pages and data services." }, "coverage": { "type": "string", "description": "How much of England the council licensing research covers today." }, "notice": { "type": "string", "description": "How to use this answer. It is information, not legal advice." }, "catalogueDate": { "type": "string", "description": "The catalogue edition this response was built from." }, "links": { "type": "object", "properties": { "documentation": { "type": "string", "description": "Absolute URL" }, "openapi": { "type": "string", "description": "Absolute URL" }, "html": { "description": "The human page for this answer.", "type": "string" }, "markdown": { "description": "The same page as Markdown, for agents.", "type": "string" } }, "required": [ "documentation", "openapi" ] } }, "required": [ "sources", "coverage", "notice", "catalogueDate", "links" ], "description": "Sources, coverage and links. Present on every response, including errors." }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "not_found", "outside_england", "rate_limited", "upstream_unavailable" ] }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "error", "meta" ] }, "RegisterWindow": { "type": "object", "properties": { "region": { "type": "string" }, "opens": { "type": "string", "description": "ISO date, YYYY-MM-DD" }, "deadline": { "type": "string", "description": "ISO date, YYYY-MM-DD" }, "earlyRegistrationFrom": { "type": "string", "description": "ISO date, YYYY-MM-DD" }, "feeGbp": { "type": "number" }, "status": { "type": "string", "const": "planned" }, "note": { "type": "string" }, "rule": { "type": "string", "description": "Absolute URL" } }, "required": [ "region", "opens", "deadline", "earlyRegistrationFrom", "feeGbp", "status", "note", "rule" ], "description": "The planned landlord register (Private Rented Sector Database) window for the region. The regulations are in draft." }, "CheckScheme": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "selective", "additional", "mandatory_hmo" ] }, "status": { "type": "string", "enum": [ "in_force", "approved_not_started", "consultation", "expired", "quashed", "revoked" ] }, "covers": { "type": "string", "enum": [ "yes", "check" ], "description": "yes: the postcode's ward is inside the scheme. check: confirm the boundary or property criteria with the council." }, "reason": { "type": "string" }, "start": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "end": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "The last day the scheme is certainly in force." }, "ceasesOn": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "The notice's \"ceases to have effect on\" date, the day after end, when recorded. On that day covers is check." }, "endDateUncertainUntil": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "Last disputed day when primary sources conflict. From ceasesOn through this date covers is check, not proof that a licence is required or unnecessary." }, "feeGbp": { "description": "The published standard figure, which may be per room or unit rather than a total. Read feeNotes for the charging basis, supplements and conditions. No property-specific total has been calculated.", "type": [ "number", "null" ] }, "feeNotes": { "description": "The council research's fee conditions, including any charging unit, supplements or discounts. Null means these details have not been recorded.", "type": [ "string", "null" ] }, "licenceLengthYears": { "description": "The published licence term in years, where recorded. This does not turn feeGbp into a total charge for that period.", "type": [ "number", "null" ] }, "appliesTo": { "type": "string" }, "exemptions": { "type": [ "string", "null" ] }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "How sure the research is. Medium or low means read the linked source before relying on it." }, "notes": { "type": [ "string", "null" ] }, "apply": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] }, "sources": { "type": "array", "items": { "type": "string", "description": "Absolute URL" } } }, "required": [ "name", "type", "status", "covers", "reason", "start", "end", "ceasesOn", "endDateUncertainUntil", "feeGbp", "feeNotes", "licenceLengthYears", "appliesTo", "exemptions", "confidence", "notes", "apply", "sources" ] }, "CheckResult": { "type": "object", "properties": { "postcode": { "type": "string" }, "ward": { "type": [ "string", "null" ] }, "council": { "type": [ "string", "null" ] }, "household": { "type": "string", "enum": [ "single", "small_hmo", "large_hmo" ] }, "licence": { "type": "object", "properties": { "needed": { "type": "string", "enum": [ "yes", "no", "check" ], "description": "check means the answer depends on something a postcode cannot settle, or the council is not researched yet. It never means no." }, "summary": { "type": "string" }, "schemes": { "type": "array", "items": { "$ref": "#/components/schemas/CheckScheme" } } }, "required": [ "needed", "summary", "schemes" ] }, "register": { "anyOf": [ { "$ref": "#/components/schemas/RegisterWindow" }, { "type": "null" } ] }, "registerSources": { "type": "array", "items": { "type": "string", "description": "Absolute URL" } }, "registerCheckedAt": { "type": "string", "description": "ISO date, YYYY-MM-DD" }, "planningSource": { "type": "string", "description": "Absolute URL" }, "planningAvailability": { "type": "object", "properties": { "floodZone": { "type": "string", "enum": [ "available", "unavailable" ] }, "conservationAreas": { "type": "string", "enum": [ "available", "unavailable" ] }, "article4": { "type": "string", "enum": [ "available", "unavailable" ] } }, "required": [ "floodZone", "conservationAreas", "article4" ] }, "openQuestions": { "type": "array", "items": { "type": "string" } }, "floodZone": { "anyOf": [ { "type": "object", "properties": { "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ] }, "source": { "type": "string" } }, "required": [ "level", "source" ] }, { "type": "null" } ] }, "conservationAreas": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "null when the dataset was unavailable; empty when the lookup found none at the postcode centre." }, "article4Directions": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "url": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] } }, "required": [ "name", "description", "url" ] } }, { "type": "null" } ] }, "councilPage": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] }, "researched": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "When the council's licensing was researched; null if not researched yet." }, "verified": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "postcode", "ward", "council", "household", "licence", "register", "registerSources", "registerCheckedAt", "planningSource", "planningAvailability", "openQuestions", "floodZone", "conservationAreas", "article4Directions", "councilPage", "researched", "verified", "limitations" ] }, "CheckResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CheckResult" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "MarketSource": { "type": "object", "properties": { "dataset": { "type": "string" }, "publisher": { "type": "string" }, "url": { "type": "string", "description": "The dataset's page." }, "files": { "type": "array", "items": { "type": "string", "description": "Absolute URL" }, "description": "The files the snapshot was compiled from." }, "released": { "type": "string", "description": "When the publisher released the files used." }, "obtained": { "type": "string", "description": "When Lettance downloaded them." }, "measure": { "type": "string" }, "licence": { "type": "string" }, "licenceUrl": { "type": "string", "description": "Absolute URL" }, "attribution": { "type": "string", "description": "The attribution statement to show with the figure." } }, "required": [ "dataset", "publisher", "url", "files", "released", "obtained", "measure", "licence", "licenceUrl", "attribution" ], "description": "Where an area market figure comes from. Show the attribution with the figure." }, "AreaMarket": { "type": "object", "properties": { "postcode": { "type": "string" }, "council": { "type": [ "string", "null" ] }, "councilCode": { "type": "string", "description": "ONS local authority code" }, "rent": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "available" }, "area": { "type": "object", "properties": { "code": { "type": "string" }, "name": { "type": "string" } }, "required": [ "code", "name" ] }, "period": { "type": "string", "description": "The month the figure describes, YYYY-MM." }, "averageMonthlyRentGbp": { "type": "number" }, "annualChangePct": { "type": [ "number", "null" ] }, "byBedrooms": { "type": "object", "properties": { "one": { "type": [ "number", "null" ] }, "two": { "type": [ "number", "null" ] }, "three": { "type": [ "number", "null" ] }, "fourPlus": { "type": [ "number", "null" ] } }, "required": [ "one", "two", "three", "fourPlus" ] }, "england": { "anyOf": [ { "type": "object", "properties": { "averageMonthlyRentGbp": { "type": "number" }, "annualChangePct": { "type": [ "number", "null" ] } }, "required": [ "averageMonthlyRentGbp", "annualChangePct" ] }, { "type": "null" } ] }, "source": { "$ref": "#/components/schemas/MarketSource" } }, "required": [ "status", "area", "period", "averageMonthlyRentGbp", "annualChangePct", "byBedrooms", "england", "source" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable" }, "reason": { "type": "string" }, "source": { "$ref": "#/components/schemas/MarketSource" } }, "required": [ "status", "reason", "source" ] } ] }, "sales": { "oneOf": [ { "type": "object", "properties": { "status": { "type": "string", "const": "available" }, "district": { "type": "object", "properties": { "code": { "type": "string", "description": "Postcode district, e.g. SE15." }, "medianPriceGbp": { "type": "number" }, "sales": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "code", "medianPriceGbp", "sales" ] }, "window": { "type": "object", "properties": { "from": { "type": "string", "description": "ISO date, YYYY-MM-DD" }, "to": { "type": "string", "description": "ISO date, YYYY-MM-DD" } }, "required": [ "from", "to" ] }, "source": { "$ref": "#/components/schemas/MarketSource" } }, "required": [ "status", "district", "window", "source" ] }, { "type": "object", "properties": { "status": { "type": "string", "const": "unavailable" }, "reason": { "type": "string" }, "window": { "type": "object", "properties": { "from": { "type": "string", "description": "ISO date, YYYY-MM-DD" }, "to": { "type": "string", "description": "ISO date, YYYY-MM-DD" } }, "required": [ "from", "to" ] }, "source": { "$ref": "#/components/schemas/MarketSource" } }, "required": [ "status", "reason", "window", "source" ] } ] }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "postcode", "council", "councilCode", "rent", "sales", "limitations" ], "description": "ONS private rents for the local authority and HM Land Registry sale prices for the postcode district, from a dated snapshot. Area figures, not a valuation." }, "AreaMarketResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AreaMarket" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "FieldSource": { "type": "object", "properties": { "publisher": { "type": "string" }, "dataset": { "type": "string" }, "url": { "type": "string", "description": "Absolute URL" }, "licence": { "type": [ "string", "null" ] }, "licenceUrl": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] }, "attribution": { "type": [ "string", "null" ] }, "released": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "obtained": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "Null for live lookups; see note." }, "note": { "type": "string" } }, "required": [ "publisher", "dataset", "url", "licence", "licenceUrl", "attribution", "released", "obtained", "note" ] }, "Comparison": { "type": "object", "properties": { "household": { "type": "string", "enum": [ "single", "small_hmo", "large_hmo" ] }, "postcodes": { "type": "array", "items": { "type": "string" } }, "addresses": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "postcode": { "type": "string" }, "status": { "type": "string", "const": "ok" }, "check": { "$ref": "#/components/schemas/CheckResult" }, "market": { "$ref": "#/components/schemas/AreaMarket" } }, "required": [ "postcode", "status", "check", "market" ] }, { "type": "object", "properties": { "postcode": { "type": "string" }, "status": { "type": "string", "enum": [ "not_found", "outside_england", "unavailable" ] }, "error": { "type": "string" } }, "required": [ "postcode", "status", "error" ] } ] } }, "comparison": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "licence", "register", "floodZone", "conservationAreas", "article4Directions", "averageRent", "medianPrice" ] }, "label": { "type": "string" }, "source": { "$ref": "#/components/schemas/FieldSource" }, "values": { "type": "array", "items": { "type": "object", "properties": { "postcode": { "type": "string" }, "value": { "description": "The value, or \"unknown\" when the source cannot settle it. Unknown never means no." }, "unknown": { "type": "string" }, "detail": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "postcode", "value" ] } } }, "required": [ "field", "label", "source", "values" ] } }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "household", "postcodes", "addresses", "comparison", "limitations" ], "description": "Two to four postcodes side by side. Each field names its source, licence and dates." }, "CompareResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Comparison" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "CouncilListing": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "gss": { "type": "string" }, "region": { "type": "string" }, "researched": { "type": "boolean" }, "researchedAt": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "verifiedAt": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "schemeCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "openQuestionCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "url": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] } }, "required": [ "name", "slug", "gss", "region", "researched", "researchedAt", "verifiedAt", "schemeCount", "openQuestionCount", "url" ] }, "CouncilList": { "type": "object", "properties": { "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "researched": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "councils": { "type": "array", "items": { "$ref": "#/components/schemas/CouncilListing" } } }, "required": [ "total", "researched", "councils" ] }, "CouncilListResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CouncilList" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "Scheme": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "selective", "additional", "mandatory_hmo" ] }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "in_force", "approved_not_started", "consultation", "expired", "quashed", "revoked" ] }, "area": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "borough_wide", "wards", "other" ] }, "wards": { "type": "array", "items": { "type": "string" } }, "streets": { "type": "array", "items": { "type": "string" } }, "ward_boundary_vintage": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "map_url": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] } }, "required": [ "kind", "wards", "streets", "ward_boundary_vintage", "description", "map_url" ] }, "applies_to": { "type": "string" }, "property_eligibility_check": { "type": "string" }, "includes_converted_blocks": { "type": "boolean" }, "exemptions": { "type": [ "string", "null" ] }, "start_date": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "end_date": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "The last day the scheme is certainly in force." }, "end_date_uncertain_until": { "description": "Last disputed day of a sourced final-date conflict; does not extend certain coverage.", "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "ceases_on": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "The designation's own \"ceases to have effect on\" date when it falls before the fifth anniversary. Whether that day is still covered is not settled; treat it as a day to check with the council." }, "fee": { "type": "object", "properties": { "standard_gbp": { "type": [ "number", "null" ] }, "early_bird_gbp": { "type": [ "number", "null" ] }, "notes": { "type": [ "string", "null" ] } }, "required": [ "standard_gbp", "early_bird_gbp", "notes" ] }, "licence_length_years": { "type": [ "number", "null" ] }, "apply_url": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] }, "conditions_url": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] }, "source_urls": { "type": "array", "items": { "type": "string", "description": "Absolute URL" } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "How sure the research is. Medium or low means read the linked source before relying on it." }, "notes": { "type": [ "string", "null" ] } }, "required": [ "type", "name", "status", "area", "applies_to", "exemptions", "start_date", "end_date", "ceases_on", "fee", "licence_length_years", "apply_url", "conditions_url", "source_urls", "confidence", "notes" ] }, "ResearchedCouncil": { "type": "object", "properties": { "researched": { "type": "boolean", "const": true }, "authority": { "type": "string" }, "slug": { "type": "string" }, "gss": { "type": "string", "description": "ONS local authority code" }, "region": { "type": "string" }, "researched_at": { "type": "string", "description": "ISO date, YYYY-MM-DD" }, "verified_at": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "schemes": { "type": "array", "items": { "$ref": "#/components/schemas/Scheme" } }, "article4_hmo": { "anyOf": [ { "type": "object", "properties": { "exists": { "type": [ "boolean", "null" ] }, "area": { "type": [ "string", "null" ] }, "effective_date": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "source_url": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] } }, "required": [ "exists", "area", "effective_date", "source_url" ] }, { "type": "null" } ] }, "civil_penalty_policy": { "anyOf": [ { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] }, "updated_for_renters_rights_act": { "type": [ "boolean", "null" ] }, "notes": { "type": [ "string", "null" ] } }, "required": [ "url", "updated_for_renters_rights_act", "notes" ] }, { "type": "null" } ] }, "consultations": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "status": { "type": "string" }, "closes": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] } }, "required": [ "title", "status", "closes", "url" ] } }, "open_questions": { "type": "array", "items": { "type": "string" }, "description": "Points the research could not settle. Show them; do not treat them as answered." }, "url": { "type": "string", "description": "Absolute URL" } }, "required": [ "researched", "authority", "slug", "gss", "researched_at", "verified_at", "schemes", "article4_hmo", "civil_penalty_policy", "consultations", "open_questions", "url" ] }, "UnresearchedCouncil": { "type": "object", "properties": { "researched": { "type": "boolean", "const": false }, "council": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "region": { "type": "string" }, "gss": { "type": "string" } }, "required": [ "name", "slug", "region", "gss" ] }, "message": { "type": "string" }, "register": { "anyOf": [ { "$ref": "#/components/schemas/RegisterWindow" }, { "type": "null" } ] }, "registerSources": { "type": "array", "items": { "type": "string", "description": "Absolute URL" } }, "registerCheckedAt": { "type": "string", "description": "ISO date, YYYY-MM-DD" } }, "required": [ "researched", "council", "message", "register", "registerSources", "registerCheckedAt" ] }, "Council": { "oneOf": [ { "$ref": "#/components/schemas/ResearchedCouncil" }, { "$ref": "#/components/schemas/UnresearchedCouncil" } ], "description": "A researched council's licensing, or researched: false for a council not researched yet. Not researched never means no licence is needed." }, "CouncilResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Council" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "RuleSummary": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "in_force", "confirmed_future", "proposed" ], "description": "proposed is not law yet; confirmed_future has a set start date." }, "summary": { "type": "string" }, "url": { "type": "string", "description": "Absolute URL" } }, "required": [ "id", "title", "status", "summary", "url" ] }, "RuleList": { "type": "object", "properties": { "query": { "description": "The search words, or null when listing every rule.", "type": [ "string", "null" ] }, "total": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/RuleSummary" } } }, "required": [ "query", "total", "rules" ] }, "RuleListResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/RuleList" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "Rule": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "category": { "type": "string" }, "status": { "type": "string", "enum": [ "in_force", "confirmed_future", "proposed" ], "description": "proposed is not law yet; confirmed_future has a set start date." }, "summary": { "type": "string" }, "applies_when": { "type": "string" }, "conditions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "requirement": { "type": "string" }, "deadline": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string" }, "interval_months": { "type": [ "number", "null" ] }, "event": { "type": [ "string", "null" ] }, "days": { "type": [ "number", "null" ] }, "date": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "notes": { "type": [ "string", "null" ] } }, "required": [ "kind", "interval_months", "event", "days", "date", "notes" ] }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "string" } }, "penalty": { "anyOf": [ { "type": "object", "properties": { "max_civil_penalty_gbp": { "type": [ "number", "null" ] }, "criminal": { "type": "boolean" }, "rent_repayment_order": { "type": "boolean" }, "other_consequences": { "type": [ "string", "null" ] } }, "required": [ "max_civil_penalty_gbp", "criminal", "rent_repayment_order", "other_consequences" ] }, { "type": "null" } ] }, "effective_from": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "effective_to": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] }, "legal_basis": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "description": "Absolute URL" } }, "required": [ "title", "url" ] } }, "guidance": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string", "description": "Absolute URL" } }, "required": [ "title", "url" ] } }, "confidence": { "type": "string", "enum": [ "high", "medium", "low" ], "description": "How sure the research is. Medium or low means read the linked source before relying on it." }, "notes": { "type": [ "string", "null" ] }, "url": { "type": "string", "description": "Absolute URL" } }, "required": [ "id", "title", "category", "status", "summary", "applies_when", "conditions", "requirement", "deadline", "evidence", "penalty", "effective_from", "effective_to", "legal_basis", "guidance", "confidence", "notes", "url" ] }, "RuleResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Rule" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] }, "PlanItem": { "type": "object", "properties": { "id": { "type": "string", "description": "The checklist item a saved home would use for the same duty, such as gas or deposit." }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "action", "due_soon", "unknown", "upcoming", "ok" ], "description": "action: do it now. due_soon: due within 60 days, or before the next tenancy starts. unknown: needs an answer or a council check. upcoming: a later date or a continuing duty. ok: on track by the landlord's own answers, not checked against documents." }, "date": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "The item's key date: a deadline, an expiry or the earliest new rent." }, "dateLabel": { "description": "What the date is, such as Due by, Deadline or Earliest new rent.", "type": [ "string", "null" ] }, "detail": { "type": "string" }, "basis": { "type": "string", "enum": [ "address", "answers", "unanswered" ], "description": "address: from the postcode. answers: from the landlord's answers. unanswered: waiting for an answer." }, "ongoing": { "type": "boolean", "description": "A continuing duty with no date of its own." }, "otherDates": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "ISO date, YYYY-MM-DD" }, "label": { "type": "string" } }, "required": [ "date", "label" ] }, "description": "Other dates for the same item, such as a register window opening." }, "applyUrl": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ], "description": "The council's page to apply for a licence, when one is needed and not held." }, "rules": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "url": { "type": "string", "description": "Absolute URL" } }, "required": [ "id", "title", "url" ] } } }, "required": [ "id", "title", "status", "date", "dateLabel", "detail", "basis", "ongoing", "otherDates", "applyUrl", "rules" ] }, "PlanQuestion": { "type": "object", "properties": { "key": { "type": "string" }, "parameter": { "type": "string", "description": "The query parameter that answers it on /api/v1/plan and /plan." }, "argument": { "type": "string", "description": "The plan_rental MCP tool argument that answers it." }, "prompt": { "type": "string" }, "hint": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "date", "choice" ] }, "options": { "type": "array", "items": { "type": "string" }, "description": "The allowed values for a choice; empty for a date." } }, "required": [ "key", "parameter", "argument", "prompt", "hint", "kind", "options" ] }, "PlanResult": { "type": "object", "properties": { "postcode": { "type": "string" }, "ward": { "type": [ "string", "null" ] }, "council": { "type": "string" }, "councilPage": { "anyOf": [ { "type": "string", "description": "Absolute URL" }, { "type": "null" } ] }, "region": { "type": [ "string", "null" ] }, "household": { "type": "string", "enum": [ "single", "small_hmo", "large_hmo" ] }, "letting": { "anyOf": [ { "type": "string", "enum": [ "now", "next" ] }, { "type": "null" } ], "description": "now: tenants live there. next: a tenancy is starting or the home is being got ready. null: not answered yet." }, "asOf": { "type": "string", "description": "The London date the plan was worked out for." }, "licence": { "type": "object", "properties": { "needed": { "type": "string", "enum": [ "yes", "no", "check" ], "description": "check means the answer depends on something a postcode cannot settle, or the council is not researched yet. It never means no." }, "summary": { "type": "string" }, "kind": { "anyOf": [ { "type": "string", "enum": [ "selective", "additional", "mandatory_hmo" ] }, { "type": "null" } ], "description": "The kind of licence this household needs, which the licence question names." }, "scheme": { "description": "The leading council scheme.", "type": [ "string", "null" ] }, "confidence": { "anyOf": [ { "type": "string", "enum": [ "high", "medium", "low" ] }, { "type": "null" } ], "description": "The research confidence for the leading scheme." }, "sources": { "type": "array", "items": { "type": "string", "description": "Absolute URL" }, "description": "The council sources behind every scheme matched for this household." }, "openQuestions": { "type": "array", "items": { "type": "string" } }, "researched": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ], "description": "When the council's licensing was researched; null if not researched yet." }, "verified": { "anyOf": [ { "type": "string", "description": "ISO date, YYYY-MM-DD" }, { "type": "null" } ] } }, "required": [ "needed", "summary", "kind", "scheme", "confidence", "sources", "openQuestions", "researched", "verified" ], "description": "The council research behind the licence and licensing scheme items. Keep the confidence, sources and open questions with any answer." }, "summary": { "type": "object", "properties": { "now": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "soon": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "upcoming": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ok": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "toAnswer": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "ongoing": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "now", "soon", "upcoming", "ok", "toAnswer", "ongoing" ] }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/PlanItem" }, "description": "Work first, then questions, then dates, then what is on track." }, "questions": { "type": "array", "items": { "$ref": "#/components/schemas/PlanQuestion" }, "description": "Answers that would make the plan more exact, most useful first. Ask the landlord; never guess them." }, "answers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" }, "description": "The answers this plan used, as query parameters." }, "links": { "type": "object", "properties": { "plan": { "type": "string", "description": "The interactive plan page." }, "api": { "type": "string", "description": "Absolute URL" }, "calendar": { "type": "string", "description": "The plan's future dates as an iCalendar file." } }, "required": [ "plan", "api", "calendar" ] }, "notice": { "type": "string" } }, "required": [ "postcode", "ward", "council", "councilPage", "region", "household", "letting", "asOf", "licence", "summary", "items", "questions", "answers", "links", "notice" ] }, "PlanResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PlanResult" }, "meta": { "$ref": "#/components/schemas/Meta" } }, "required": [ "data", "meta" ] } }, "headers": { "RateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before trying again.", "schema": { "type": "integer" } } } } }