# 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 600,000+ 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 (31M+ 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: Free £0/mo (200 credits, no card, key issued instantly), Starter £29/mo (2,500 credits, 5 req/s), Growth £59/mo (7,500 credits, 10 req/s, 25 AI chats), Advanced £99/mo (20K credits, 10 req/s, 100 AI chats), Professional £299/mo (100K credits, 25 req/s, 1K AI chats, + build cost), Business £999/mo (400K credits, 50 req/s, 4K AI chats, + build cost). Per-credit cost is cheaper than every comparable competitor tier. Sign up at https://propaideals.co.uk/developers.
Data MCP Server: `https://api.propaideals.co.uk/mcp` — connect Claude (claude.ai, Claude Desktop, Claude Code) to query live UK property data in-chat: search, valuations, comparables, area stats, deal scores and full property reports, plus actions in your own account (save properties, add to and move deals in the pipeline, create scanners, update preferences and portfolio rent, build investor packs). OAuth sign-in, free tier included. Setup guide: https://propaideals.co.uk/claude
Docs 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
- [OpenAPI spec & Postman](https://docs.propaideals.co.uk/openapi-postman): Download the OpenAPI 3.1 spec (https://docs.propaideals.co.uk/openapi.json) and the Postman v2.1 collection (https://docs.propaideals.co.uk/postman_collection.json) — generate typed clients or import every public endpoint into Postman with bearer auth pre-wired.

## 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`.
- [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` (Growth plans and above). 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.

## Research and guides

- [News and data research](https://www.propaideals.co.uk/news): UK property market data articles built from HM Land Registry sold prices and the listings we track, with methodology and source attribution
- [Guides](https://www.propaideals.co.uk/guides): Property investment guides for UK investors

## 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