# Prop AI Deals API

> The Prop AI Deals API is a REST API for UK property data, market intelligence, investment analysis, and AI-powered search. It exposes 2.1M+ on-market UK property listings aggregated from every major UK property portal, plus an exclusive off-market lead pool (distressed sales, motivated sellers, repossessions, probate stock), enriched with HM Land Registry sold history (~5M transactions), EPC certificates, rental estimates, BMV (below-market-value) scoring, build cost data from Spon's 2026 price book, and a multi-agent AI chat system. Built for property investors, fintech apps, lettings platforms, valuation tools, and research teams.

Base URL: `https://api.propaideals.co.uk`
Authentication: Bearer API keys (prefix `paid_`) sent in `Authorization` header
All endpoints under `/api/v1/`. JSON responses wrapped in `{ data, meta }` envelope.
Plans: Starter £99/mo (20K req, 10 req/s, 100 AI chats, £0.00495/req), Professional £299/mo (100K req, 25 req/s, 1K AI chats, AI + build cost, £0.00299/req), Business £999/mo (400K req, 50 req/s, 4K AI chats, AI + build cost, £0.00250/req). All tiers paid — no free tier. Per-request cost is cheaper than every comparable competitor tier and rate limits are 20-25x higher. Sign up at https://propaideals.co.uk/developers.
MCP Server: `https://docs.propaideals.co.uk/mcp` — connect Claude Code, Cursor, Claude Desktop, Continue, or any MCP-aware AI client to query our docs in real time. No setup required, public read-only access.

## Getting started

- [Overview](https://docs.propaideals.co.uk): API overview, capabilities, base URL, quick example, and links to all reference docs
- [Quickstart](https://docs.propaideals.co.uk/quickstart): Make your first authenticated request in under 3 minutes with cURL, Node.js, Python, Ruby, and Go examples
- [Authentication](https://docs.propaideals.co.uk/authentication): API key format (`paid_*`), creating keys from the dashboard, scopes per plan, key rotation, and the difference between API keys and Clerk JWT tokens
- [Rate limits](https://docs.propaideals.co.uk/rate-limits): Per-second rate limits, monthly request quotas (HARD caps — no soft/hard split), AI chat quotas, plan comparison table, rate limit headers, 503 backpressure handling, and best practices
- [Errors](https://docs.propaideals.co.uk/errors): Standard error envelope, error codes (`invalid_api_key`, `rate_limit_exceeded`, `monthly_quota_exceeded`, `ai_chat_quota_exceeded`, `insufficient_scope`, `endpoint_not_in_public_api`, `Service temporarily busy`), and recommended retry policy with exponential backoff
- [Response format](https://docs.propaideals.co.uk/response-format): JSON envelope, pagination (offset and cursor), timestamps, money values, coordinates, and field availability conventions
- [Connect with AI agents](https://docs.propaideals.co.uk/connect-with-ai): Connect Claude Code, Cursor, Claude Desktop, Continue, and any MCP-aware AI client to the Prop AI Deals docs via the MCP server, llms.txt, or llms-full.txt

## API reference

- [Properties endpoint](https://docs.propaideals.co.uk/endpoints/properties): Search, list, and retrieve UK property listings via `GET /api/v1/properties` and `GET /api/v1/properties/{id}`. 140+ filter parameters (location, price, bedrooms, property type, features, investment metrics, agent), pagination, sorting, and full response schema. Required scope `properties:read`.
- [Spatial search endpoint](https://docs.propaideals.co.uk/endpoints/spatial): PostGIS-powered spatial queries via `POST /api/v1/spatial/search/viewport`, `POST /api/v1/spatial/search/polygon/draw`, and `POST /api/v1/spatial/search/radius`. Bounding box, drawn polygon, and radius search. Required scope `spatial:read`.
- [Market data endpoint](https://docs.propaideals.co.uk/endpoints/market-data): Sold history (`GET /api/v1/market-data/{id}/sold-history`), on-street comparables (`GET /api/v1/market-data/{id}/on-street`), and area price trends. Combines HM Land Registry full price-paid data with multi-portal sold listings via PostGIS spatial matching. Required scope `market-data:read`.
- [EPC certificates](https://docs.propaideals.co.uk/endpoints/epc): Energy Performance Certificate lookups via `GET /api/v1/epc/postcode/{postcode}`, `GET /api/v1/epc/uprn/{uprn}`, and `GET /api/v1/epc/property/{id}`. Returns rating, score, certificate URL, construction era, UPRN, and address. Required scope `epc:read`.
- [UPRN lookup](https://docs.propaideals.co.uk/endpoints/uprn): Resolve a Unique Property Reference Number via `GET /api/v1/uprn/{uprn}`. Returns linked property metadata, address, postcode, EPC band, construction era, and source confidence. Required scope `epc:read`.
- [Area aggregates](https://docs.propaideals.co.uk/endpoints/area-aggregates): Yields by area (`GET /api/v1/yields/area/{outcode}`), rents by area with per-bedroom breakdown (`GET /api/v1/rents/area/{outcode}`), and active estate agents (`GET /api/v1/agents-list/area/{outcode}`). Required scope `areas:read`.
- [Demographics](https://docs.propaideals.co.uk/endpoints/demographics): Population, household income, employment rate, crime rating, and ONS deprivation index for any UK postcode district via `GET /api/v1/demographics/{postcode_district}`. Sourced from ONS census, ONS IMD, and police.uk. 742 districts loaded. Required scope `areas:read`.
- [Flood risk](https://docs.propaideals.co.uk/endpoints/flood-risk): PostGIS spatial check against 144,000+ flood zone polygons via `GET /api/v1/flood-risk/coordinates?lat=&lon=` or `GET /api/v1/flood-risk/property/{property_id}`. Sourced from EA flood map, NRW, and SEPA. Returns risk level (high/medium/low), zone category (3a/3b/2/1), and source. Required scope `planning:read`.
- [Heritage](https://docs.propaideals.co.uk/endpoints/heritage): Listed building and conservation area status via `GET /api/v1/heritage/property/{property_id}` and area-level aggregates via `GET /api/v1/heritage/area/{outcode}`. Sourced from Historic England + local authority planning records. Required scope `planning:read`.
- [Points of Interest](https://docs.propaideals.co.uk/endpoints/points-of-interest): Nearby airports, hospitals, and tourist attractions for any UK coordinate via `GET /api/v1/points-of-interest/airports`, `GET /api/v1/points-of-interest/hospitals`, and `GET /api/v1/points-of-interest/tourist-attractions`. PostGIS radius search with distance, type, and category-specific extras (IATA codes, NHS codes, annual visitors). Required scope `areas:read`.
- [Build cost](https://docs.propaideals.co.uk/endpoints/build-cost): Search Spon's Architects' & Builders' Price Book 2026 for UK construction and refurb cost data via `GET /api/v1/build-cost/search?q=`. Hybrid vector + full-text search across 68 chunks of the canonical industry reference. Required scope `build-cost:read` (Professional and Business plans only).
- [AI chat endpoint](https://docs.propaideals.co.uk/endpoints/ai-chat): Conversational property intelligence via `POST /api/v1/ultimate-ai/chat` and `POST /api/v1/ultimate-ai/chat-stream`. GPT-4.1-powered multi-agent system with natural language search, multi-turn conversations via `session_id`, SSE streaming, and a `show-more` pagination endpoint. Required scope `ai:chat` (Professional and Business plans only). Costs 5 requests per call against the monthly request quota plus 1 against the AI chat quota.
- [API keys (dashboard endpoints)](https://docs.propaideals.co.uk/endpoints/api-keys): Create, list, and revoke API keys via `POST/GET/DELETE /api/v1/api-keys`. Get current usage via `GET /api/v1/api-billing/usage`. List available plans via `GET /api/v1/api-billing/plans`. Subscribe via `POST /api/v1/api-billing/subscribe`. Manage subscription via `POST /api/v1/api-billing/portal`. These endpoints use Clerk JWT auth, not API keys.

## Optional

- [Changelog](https://docs.propaideals.co.uk/changelog): Version history, breaking changes, and deprecation timeline
- [OpenAPI spec](https://api.propaideals.co.uk/openapi.json): Machine-readable OpenAPI 3.1 specification
- [Status page](https://status.propaideals.co.uk): Real-time API uptime and incident history