{"openapi":"3.0.3","info":{"title":"SiteLens API","version":"1.0.0","description":"UK planning intelligence for your own systems: classified applications, verified business contacts, Companies House matches, alert feeds and a CSV export. Authenticate every request with your API key. Where a named party is a private individual, direct contact channels are withheld by design; consume /tombstones to keep your copies compliant.","contact":{"email":"hello@sitelens.co.uk"}},"servers":[{"url":"/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Your API key (\"sl_live_…\"), sent as Authorization: Bearer. X-Api-Key is accepted as an alternative header."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}}},"Application":{"type":"object","description":"A planning application. Contact channel fields are null where the named party is a private individual, where provenance forbids the value, or where the disclosure could not be recorded.","properties":{"id":{},"council_id":{},"council_name":{},"reference":{},"url":{},"address":{},"postcode":{},"latitude":{},"longitude":{},"ward":{},"parish":{},"admin_district":{},"parliamentary_constituency":{},"description":{},"application_type":{},"status":{},"decision":{},"decision_outcome":{},"date_received":{},"date_validated":{},"date_decided":{},"date_target_decision":{},"date_consultation_end":{},"date_committee":{},"determination_level":{},"planning_portal_id":{},"portal_document_count":{},"date_permission_expiry":{},"date_permission_expiry_derived":{},"appeal_status":{},"appeal_decision":{},"agent_name":{},"agent_company":{},"applicant_ch_number":{},"agent_ch_number":{},"charity_number":{},"has_contact":{},"category":{},"subcategory":{},"works_tags":{},"stage":{},"estimated_value_band":{},"unit_count":{},"scheme_stage":{},"cited_reference":{},"doc_enriched_at":{},"doc_unit_count":{},"doc_site_area_ha":{},"doc_floor_area_sqm":{},"doc_parking_spaces":{},"doc_main_contractor":{},"doc_s106":{},"doc_cil_liable":{},"doc_affordable_pct":{},"has_appeal":{},"appeal_outcome":{},"building_type":{},"is_major":{},"is_major_effective":{},"ai_summary":{},"classified_at":{},"in_flood_zone_2":{},"in_flood_zone_3":{},"in_conservation_area":{},"in_green_belt":{},"near_listed_building":{},"in_sssi":{},"in_aonb":{},"in_national_park":{},"in_grey_belt":{},"in_article_4":{},"in_ancient_woodland":{},"near_tpo":{},"in_heritage_coast":{},"in_scheduled_monument":{},"in_world_heritage_site":{},"in_registered_park_garden":{},"in_battlefield":{},"in_heritage_at_risk":{},"in_archaeological_priority_area":{},"in_coal_high_risk_area":{},"near_ancient_tree":{},"in_local_nature_reserve":{},"in_nutrient_neutrality_catchment":{},"in_aqma":{},"alc_grade":{},"listed_building_grade":{},"constraints_enriched_at":{},"brownfield_enriched_at":{},"nearby_app_count":{},"consultation_deadline":{},"uprn":{},"uprn_matched_at":{},"epc_rating":{},"epc_potential_rating":{},"epc_enriched_at":{},"status_checked_at":{},"status_check_count":{},"status_changed_at":{},"created_at":{},"detail_read_at":{},"detail_unreachable_reason":{},"applicant_name":{},"applicant_address":{},"applicant_email":{},"applicant_phone":{},"agent_address":{},"agent_email":{},"agent_phone":{},"case_officer":{},"ch_enriched_at":{},"agent_contact_source":{},"agent_phone_source":{},"agent_address_source":{},"applicant_email_verified_at":{},"applicant_email_checked_at":{}}},"Tombstone":{"type":"object","properties":{"application_id":{"type":"string","format":"uuid"},"action":{"type":"string","enum":["refresh","remove"]},"occurred_at":{"type":"string","format":"date-time"}}}},"responses":{"Unauthorized":{"description":"Missing, malformed, revoked or unknown API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"The account plan does not include API access","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Per-minute rate limit or monthly quota exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/applications":{"get":{"summary":"Search applications","description":"Filtered application search. Regional keys see only their covered councils.","parameters":[{"name":"lat","in":"query","schema":{"type":"number"},"description":"Centre latitude for a radius search. Use with lon and radius_km."},{"name":"lon","in":"query","schema":{"type":"number"},"description":"Centre longitude for a radius search."},{"name":"radius_km","in":"query","schema":{"type":"number"},"description":"Radius in kilometres around lat/lon."},{"name":"bbox_west","in":"query","schema":{"type":"number"},"description":"Bounding-box west longitude. All four bbox_* values are required together."},{"name":"bbox_south","in":"query","schema":{"type":"number"}},{"name":"bbox_east","in":"query","schema":{"type":"number"}},{"name":"bbox_north","in":"query","schema":{"type":"number"}},{"name":"council_id","in":"query","schema":{"type":"string"},"description":"Comma-separated council ids (e.g. \"northumberland,newcastle\"). Regional keys are additionally clamped to their coverage server-side."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Comma-separated categories: residential, commercial, industrial, agricultural, institutional, infrastructure, householder, other."},{"name":"works_tags","in":"query","schema":{"type":"string"},"description":"Comma-separated works tags, e.g. \"renewables\". This is the classification layer: it is how \"commercial rooftop solar near me\" becomes one query."},{"name":"is_major","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Major applications only (LLM flag OR the statutory floor)."},{"name":"decision_outcome","in":"query","schema":{"type":"string"},"description":"Comma-separated: pending, approved, refused, withdrawn."},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"}},{"name":"min_value_band","in":"query","schema":{"type":"string","enum":["under_10k","10k_50k","50k_100k","100k_500k","500k_1m","1m_5m","5m_20m","20m_plus"]},"description":"Minimum estimated value band."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Keyword search over the application description."},{"name":"subcategory","in":"query","schema":{"type":"string"}},{"name":"building_type","in":"query","schema":{"type":"string"}},{"name":"stage","in":"query","schema":{"type":"string"}},{"name":"ward","in":"query","schema":{"type":"string"}},{"name":"parish","in":"query","schema":{"type":"string"}},{"name":"admin_district","in":"query","schema":{"type":"string"}},{"name":"constituency","in":"query","schema":{"type":"string"}},{"name":"developer_ch","in":"query","schema":{"type":"string"},"description":"Filter to applications whose agent or applicant matches this Companies House number."},{"name":"agent_firm","in":"query","schema":{"type":"string"}},{"name":"applicant_name","in":"query","schema":{"type":"string"}},{"name":"constraints","in":"query","schema":{"type":"string"},"description":"Comma-separated constraint flags, e.g. \"green_belt,conservation_area\"."},{"name":"min_units","in":"query","schema":{"type":"integer"}},{"name":"min_storeys","in":"query","schema":{"type":"integer"}},{"name":"min_height_m","in":"query","schema":{"type":"number"}},{"name":"min_floor_area_sqm","in":"query","schema":{"type":"number"}},{"name":"min_affordable_pct","in":"query","schema":{"type":"number"}},{"name":"has_s106","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"cil_liable","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"has_contact","in":"query","schema":{"type":"string","enum":["true"]},"description":"Only applications carrying at least one contact channel."},{"name":"has_appeal","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"appeal_outcome","in":"query","schema":{"type":"string"}},{"name":"epc_max_rating","in":"query","schema":{"type":"string"}},{"name":"alc_grades","in":"query","schema":{"type":"string"}},{"name":"is_charity","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["date_desc","date_asc","value_desc","council"],"default":"date_desc"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"A page of applications","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"total":{"description":"Number, or the string \"10000+\" when capped"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/applications/{id}":{"get":{"summary":"Application detail","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The application","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Application"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found or outside your coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/applications/{id}/history":{"get":{"summary":"Status and decision history","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Status change history for the application"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Not found or outside your coverage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/export":{"get":{"summary":"CSV export (the daily-dump shape)","description":"The same filters as /applications, returned as CSV, up to 10,000 rows. Built for a scheduled import.","parameters":[{"name":"lat","in":"query","schema":{"type":"number"},"description":"Centre latitude for a radius search. Use with lon and radius_km."},{"name":"lon","in":"query","schema":{"type":"number"},"description":"Centre longitude for a radius search."},{"name":"radius_km","in":"query","schema":{"type":"number"},"description":"Radius in kilometres around lat/lon."},{"name":"bbox_west","in":"query","schema":{"type":"number"},"description":"Bounding-box west longitude. All four bbox_* values are required together."},{"name":"bbox_south","in":"query","schema":{"type":"number"}},{"name":"bbox_east","in":"query","schema":{"type":"number"}},{"name":"bbox_north","in":"query","schema":{"type":"number"}},{"name":"council_id","in":"query","schema":{"type":"string"},"description":"Comma-separated council ids (e.g. \"northumberland,newcastle\"). Regional keys are additionally clamped to their coverage server-side."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Comma-separated categories: residential, commercial, industrial, agricultural, institutional, infrastructure, householder, other."},{"name":"works_tags","in":"query","schema":{"type":"string"},"description":"Comma-separated works tags, e.g. \"renewables\". This is the classification layer: it is how \"commercial rooftop solar near me\" becomes one query."},{"name":"is_major","in":"query","schema":{"type":"string","enum":["true","false"]},"description":"Major applications only (LLM flag OR the statutory floor)."},{"name":"decision_outcome","in":"query","schema":{"type":"string"},"description":"Comma-separated: pending, approved, refused, withdrawn."},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"}},{"name":"min_value_band","in":"query","schema":{"type":"string","enum":["under_10k","10k_50k","50k_100k","100k_500k","500k_1m","1m_5m","5m_20m","20m_plus"]},"description":"Minimum estimated value band."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Keyword search over the application description."},{"name":"subcategory","in":"query","schema":{"type":"string"}},{"name":"building_type","in":"query","schema":{"type":"string"}},{"name":"stage","in":"query","schema":{"type":"string"}},{"name":"ward","in":"query","schema":{"type":"string"}},{"name":"parish","in":"query","schema":{"type":"string"}},{"name":"admin_district","in":"query","schema":{"type":"string"}},{"name":"constituency","in":"query","schema":{"type":"string"}},{"name":"developer_ch","in":"query","schema":{"type":"string"},"description":"Filter to applications whose agent or applicant matches this Companies House number."},{"name":"agent_firm","in":"query","schema":{"type":"string"}},{"name":"applicant_name","in":"query","schema":{"type":"string"}},{"name":"constraints","in":"query","schema":{"type":"string"},"description":"Comma-separated constraint flags, e.g. \"green_belt,conservation_area\"."},{"name":"min_units","in":"query","schema":{"type":"integer"}},{"name":"min_storeys","in":"query","schema":{"type":"integer"}},{"name":"min_height_m","in":"query","schema":{"type":"number"}},{"name":"min_floor_area_sqm","in":"query","schema":{"type":"number"}},{"name":"min_affordable_pct","in":"query","schema":{"type":"number"}},{"name":"has_s106","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"cil_liable","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"has_contact","in":"query","schema":{"type":"string","enum":["true"]},"description":"Only applications carrying at least one contact channel."},{"name":"has_appeal","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"appeal_outcome","in":"query","schema":{"type":"string"}},{"name":"epc_max_rating","in":"query","schema":{"type":"string"}},{"name":"alc_grades","in":"query","schema":{"type":"string"}},{"name":"is_charity","in":"query","schema":{"type":"string","enum":["true"]}},{"name":"sort","in":"query","schema":{"type":"string","enum":["date_desc","date_asc","value_desc","council"],"default":"date_desc"}}],"responses":{"200":{"description":"CSV payload","content":{"text/csv":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/companies/{ch}":{"get":{"summary":"Company profile","description":"Company facts and application history by Companies House number. Contact lookups run in the dashboard, on the same account and allowance.","parameters":[{"name":"ch","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Company profile with recent applications"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Company not known to SiteLens","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/alerts":{"get":{"summary":"Your alert definitions","responses":{"200":{"description":"The alert configurations on this account"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/alerts/{id}/matches":{"get":{"summary":"New matches for one alert","description":"The pollable feed: applications matching the alert since the cursor. Poll on your own schedule and carry next_since forward.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 cursor. Use the next_since value from the previous response. Clamped to the last 30 days."}],"responses":{"200":{"description":"Matches plus the cursor to poll from next","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"since":{"type":"string","format":"date-time"},"next_since":{"type":"string","format":"date-time"},"capped":{"type":"boolean"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Alert not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/leads":{"get":{"summary":"Your saved-lead pipeline (read-only mirror)","description":"Pipeline facts for CRM mirroring. Contact channel values are not carried here: fetch /applications/{id} for those.","responses":{"200":{"description":"Your leads"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/tombstones":{"get":{"summary":"Records to refresh or delete (compliance feed)","description":"Data-protection propagation. Your licence obliges you to act on these within 7 days: refresh means re-fetch the record (its served fields have changed), remove means delete your copy.","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 cursor. Use the next_since value from the previous response. Clamped to the last 30 days."}],"responses":{"200":{"description":"Refresh/remove instructions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tombstone"}},"since":{"type":"string","format":"date-time"},"next_since":{"type":"string","format":"date-time"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/usage":{"get":{"summary":"Your meters and coverage","responses":{"200":{"description":"Plan, key, coverage, request and lookup meters"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}