# EasyRealty

> Town & Country Property — agent-readable index of public APIs, schemas, and content.

## Discovery

- [API catalog (linkset)](https://easyrealty.app/.well-known/api-catalog)
- [OpenAPI spec (YAML)](https://easyrealty.app/.well-known/openapi.yaml)
- [API documentation (HTML)](https://easyrealty.app/docs/api)
- [Pre-built example search URLs (markdown)](https://easyrealty.app/docs/api/examples) — concrete links for every type/location combo with `limit=200`, useful when your fetcher cannot mutate query strings.
- [Public MCP server card](https://easyrealty.app/.well-known/mcp/server-card.json)
- [Public MCP endpoint (JSON-RPC over HTTP POST)](https://easyrealty.app/mcp)
- [Admin MCP server card](https://easyrealty.app/.well-known/mcp/admin-server-card.json)
- [Admin MCP endpoint (OAuth-protected, JSON-RPC POST)](https://easyrealty.app/mcp/private)
- [OAuth Authorization Server metadata](https://easyrealty.app/.well-known/oauth-authorization-server)
- [OAuth Protected Resource metadata](https://easyrealty.app/.well-known/oauth-protected-resource)
- [OAuth token endpoint](https://easyrealty.app/oauth/token)
- [Agent skills index](https://easyrealty.app/.well-known/agent-skills/index.json)
- [robots.txt](https://easyrealty.app/robots.txt)
- [Sitemap](https://easyrealty.app/sitemap.xml)

## Public REST API endpoints

- `GET https://easyrealty.app/api/v1/public/properties/search` — search properties. Params: `q`, `availability`, `type_id`, `location_id`, `min_price`, `max_price`, `bedrooms`, `bathrooms`, `limit`, `page`.
- `GET https://easyrealty.app/api/v1/public/properties/{id}` — get a single property.
- `GET https://easyrealty.app/api/v1/public/articles/search` — search articles. Params: `q`, `category_id`, `tag`, `limit`, `page`.
- `GET https://easyrealty.app/api/v1/public/articles/{slug}` — get a single article (full content).
- `POST https://easyrealty.app/api/v1/public/enquiries` — submit a contact enquiry. Body: `first_name`, `email`, `message`, optional `phone`, `inquiry_type`, `property_id`, `development_id`.
- `GET https://easyrealty.app/api/v1/public/options/property-types` — reference list of property types (use `id` for `type_id` filter).
- `GET https://easyrealty.app/api/v1/public/options/locations` — reference list of locations (use `id` for `location_id` filter).
- `GET https://easyrealty.app/api/v1/public/options/features` — reference list of public-searchable features.
- `GET https://easyrealty.app/api/v1/public/options/blog-categories` — reference list of blog categories.
- `GET https://easyrealty.app/api/v1/public/options/blog-tags` — reference list of blog tags.
- `GET https://easyrealty.app/api/v1/public/options/enums` — enum filter values (availability, bedrooms, etc.).

## Common pre-built search URLs

> Concrete URLs you can follow without query-string manipulation. For every type x location combination see `/docs/api/examples`.

- All properties: [https://easyrealty.app/api/v1/public/properties/search?limit=200](https://easyrealty.app/api/v1/public/properties/search?limit=200)
- For sale: [https://easyrealty.app/api/v1/public/properties/search?availability=sale&limit=200](https://easyrealty.app/api/v1/public/properties/search?availability=sale&limit=200)
- For rent: [https://easyrealty.app/api/v1/public/properties/search?availability=rent&limit=200](https://easyrealty.app/api/v1/public/properties/search?availability=rent&limit=200)
- Commercial: [https://easyrealty.app/api/v1/public/properties/search?type_id=4&limit=200](https://easyrealty.app/api/v1/public/properties/search?type_id=4&limit=200)
- Condo: [https://easyrealty.app/api/v1/public/properties/search?type_id=2&limit=200](https://easyrealty.app/api/v1/public/properties/search?type_id=2&limit=200)
- House: [https://easyrealty.app/api/v1/public/properties/search?type_id=1&limit=200](https://easyrealty.app/api/v1/public/properties/search?type_id=1&limit=200)
- Land: [https://easyrealty.app/api/v1/public/properties/search?type_id=3&limit=200](https://easyrealty.app/api/v1/public/properties/search?type_id=3&limit=200)

## Markdown content

Most HTML pages on this site honour `Accept: text/markdown` and respond with `Content-Type: text/markdown`. Examples:

- [Home (HTML)](https://easyrealty.app/) — request with `Accept: text/markdown` for markdown.
- [Properties for sale](https://easyrealty.app/properties/for-sale)
- [Properties for rent](https://easyrealty.app/properties/for-rent)
- [News index](https://easyrealty.app/news)

## Authenticated MCP (admin tools)

The admin MCP endpoint exposes the same tools the admin AI assistant uses (database queries, property edits, calendar, gmail, analytics). Tools available depend on the authenticated user.

Auth flow:

1. POST `https://easyrealty.app/oauth/token` with `grant_type=password&username=...&password=...&scope=mcp.read mcp.write` (form-encoded).
2. Receive `access_token` in JSON response.
3. Call `https://easyrealty.app/mcp/private` with `Authorization: Bearer <access_token>` and a JSON-RPC 2.0 body (`tools/list`, `tools/call`).

Discovery: see `https://easyrealty.app/.well-known/oauth-protected-resource` and `https://easyrealty.app/.well-known/oauth-authorization-server`.

## Rate limits

- Search endpoints: 60 requests / minute / IP.
- Enquiry submission: 5 / hour / IP.
- Public MCP endpoint: 60 requests / minute / IP.
- Admin MCP endpoint: 60 requests / minute / user.
- OAuth token endpoint: 10 requests / minute / IP.

## Content signals

- Search indexing: allowed.
- AI input (real-time agent retrieval to answer user queries): allowed.
- AI training (use of content to train models): not allowed without prior agreement.