{"openapi":"3.1.0","info":{"title":"UK Energy Performance Certificates (BYOK) API","version":"0.1.0","description":"UK Energy Performance Certificates (BYOK) lets an AI assistant read your own UK Energy Performance Certificates data through the UK Energy Performance Certificates API with a key you supply (Energy Performance of Buildings Data API bearer token). Read-only: 7 tools (get_certificate, search_domestic_certificates, search_non_domestic_certificates, search_display_certificates,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-uk-epc-data.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-uk-epc-data/docs"},"termsOfService":"https://connectorbay.com/byok-uk-epc-data/terms"},"servers":[{"url":"https://byok-uk-epc-data.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-uk-epc-data/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_certificate":{"post":{"operationId":"get_certificate","summary":"Get the full record of one energy certificate by its 20-digit certificate number: address, UPRN, assessment type, counci","description":"Get the full record of one energy certificate by its 20-digit certificate number: address, UPRN, assessment type, council and energy efficiency band. Keys vary by certificate type and schema version. Use for \"What is the energy rating of certificate 0000-1672-0000-1732-0000\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"certificate_number":{"description":"The 20-digit certificate number, for example '0000-1672-0000-1732-0000'.","maxLength":30,"title":"Certificate Number","type":"string"}},"required":["certificate_number"],"title":"get_certificateArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_domestic_certificates":{"post":{"operationId":"search_domestic_certificates","summary":"Search domestic (home) energy performance certificates by postcode, UPRN, address text, council, constituency, band or r","description":"Search domestic (home) energy performance certificates by postcode, UPRN, address text, council, constituency, band or registration dates. At least one filter is required. Use for \"Which homes in postcode LS1 4AP have an energy rating of F or G\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"postcode":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Postcode in England or Wales, for example 'LS1 4AP'.","title":"Postcode"},"uprn":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Unique property reference number (UPRN) of the building, as an integer.","title":"Uprn"},"address":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Partial or full address text, for example '9 union street'.","title":"Address"},"council":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Local authority name exactly as the register lists it, for example 'Manchester'. One name per call.","title":"Council"},"constituency":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Parliamentary constituency name, for example 'Manchester Rusholme'. One name per call.","title":"Constituency"},"efficiency_rating":{"anyOf":[{"enum":["A","B","C","D","E","F","G"],"type":"string"},{"type":"null"}],"default":null,"description":"Energy efficiency band to keep: A (best) to G.","title":"Efficiency Rating"},"date_start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First registration date to include, YYYY-MM-DD. Required when no other filter is given; may not be today.","title":"Date Start"},"date_end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last registration date to include, YYYY-MM-DD (defaults to yesterday); may not be today.","title":"Date End"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number to fetch, starting at 1 (see the pagination block in the answer).","title":"Current Page"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 200 in this tool; the register itself allows up to 5000).","title":"Page Size"}},"title":"search_domestic_certificatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_non_domestic_certificates":{"post":{"operationId":"search_non_domestic_certificates","summary":"Search non-domestic (commercial) energy performance certificates by postcode, UPRN, address text, council, constituency,","description":"Search non-domestic (commercial) energy performance certificates by postcode, UPRN, address text, council, constituency, band or dates. At least one filter is required. Use for \"Which commercial buildings in Manchester were certified in March 2025\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"postcode":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Postcode in England or Wales, for example 'LS1 4AP'.","title":"Postcode"},"uprn":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Unique property reference number (UPRN) of the building, as an integer.","title":"Uprn"},"address":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Partial or full address text, for example '9 union street'.","title":"Address"},"council":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Local authority name exactly as the register lists it, for example 'Manchester'. One name per call.","title":"Council"},"constituency":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Parliamentary constituency name, for example 'Manchester Rusholme'. One name per call.","title":"Constituency"},"efficiency_rating":{"anyOf":[{"enum":["A","B","C","D","E","F","G"],"type":"string"},{"type":"null"}],"default":null,"description":"Energy efficiency band to keep: A (best) to G.","title":"Efficiency Rating"},"date_start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First registration date to include, YYYY-MM-DD. Required when no other filter is given; may not be today.","title":"Date Start"},"date_end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last registration date to include, YYYY-MM-DD (defaults to yesterday); may not be today.","title":"Date End"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number to fetch, starting at 1 (see the pagination block in the answer).","title":"Current Page"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 200 in this tool; the register itself allows up to 5000).","title":"Page Size"}},"title":"search_non_domestic_certificatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_display_certificates":{"post":{"operationId":"search_display_certificates","summary":"Search display energy certificates (DEC, for public buildings) by postcode, UPRN, address text, council, constituency, b","description":"Search display energy certificates (DEC, for public buildings) by postcode, UPRN, address text, council, constituency, band or dates. At least one filter is required. Use for \"Which public buildings in Bristol have a display energy certificate\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"postcode":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Postcode in England or Wales, for example 'LS1 4AP'.","title":"Postcode"},"uprn":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Unique property reference number (UPRN) of the building, as an integer.","title":"Uprn"},"address":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Partial or full address text, for example '9 union street'.","title":"Address"},"council":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Local authority name exactly as the register lists it, for example 'Manchester'. One name per call.","title":"Council"},"constituency":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Parliamentary constituency name, for example 'Manchester Rusholme'. One name per call.","title":"Constituency"},"efficiency_rating":{"anyOf":[{"enum":["A","B","C","D","E","F","G"],"type":"string"},{"type":"null"}],"default":null,"description":"Energy efficiency band to keep: A (best) to G.","title":"Efficiency Rating"},"date_start":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"First registration date to include, YYYY-MM-DD. Required when no other filter is given; may not be today.","title":"Date Start"},"date_end":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Last registration date to include, YYYY-MM-DD (defaults to yesterday); may not be today.","title":"Date End"},"current_page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number to fetch, starting at 1 (see the pagination block in the answer).","title":"Current Page"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Rows per page (1 to 200 in this tool; the register itself allows up to 5000).","title":"Page Size"}},"title":"search_display_certificatesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_certificate_changes":{"post":{"operationId":"list_certificate_changes","summary":"List certificates that were removed or had their UPRN changed between two dates, useful for keeping a local copy in step","description":"List certificates that were removed or had their UPRN changed between two dates, useful for keeping a local copy in step. Dates may not include today. Use for \"Which energy certificates were removed last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"date_start":{"description":"First day of the range, YYYY-MM-DD.","maxLength":10,"title":"Date Start","type":"string"},"date_end":{"description":"Last day of the range, YYYY-MM-DD.","maxLength":10,"title":"Date End","type":"string"}},"required":["date_start","date_end"],"title":"list_certificate_changesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_code_tables":{"post":{"operationId":"list_code_tables","summary":"List the names of the coded fields (for example built_form) whose values can be decoded with get_code_values. Use for \"W","description":"List the names of the coded fields (for example built_form) whose values can be decoded with get_code_values. Use for \"Which coded fields does the energy certificate register publish\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_code_tablesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_code_values":{"post":{"operationId":"get_code_values","summary":"Decode one coded field: the meaning of each key (and schema version) for a code name from list_code_tables, optionally n","description":"Decode one coded field: the meaning of each key (and schema version) for a code name from list_code_tables, optionally narrowed to one key or schema version. Use for \"What do the built_form codes mean in the energy certificate data\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"code":{"description":"Code name from list_code_tables, for example 'built_form'.","maxLength":80,"title":"Code","type":"string"},"key":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this key as it appears in certificate data, for example '1'.","title":"Key"},"schema_version":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this EPC schema version, for example 'RdSAP-Schema-17.0'.","title":"Schema Version"}},"required":["code"],"title":"get_code_valuesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}