--- title: "Build on Matchai" description: "Read Matchai listings today with the MCP server, listing search and AI-readable pages, no key needed. The Matchai API, API keys and webhooks are coming soon." last_updated: "2026-10-21" lang: "en" canonical: "https://matchai.co/docs/developers" --- # Build on Matchai > Read Matchai listings today with the MCP server, listing search and AI-readable pages, no key needed. The Matchai API, API keys and webhooks are coming soon. Source: https://matchai.co/docs/developers Real estate professionals publish their listings, their website (a Matchai Site) and a one-page profile (a Matchai Page) on Matchai. Everything they publish can be read by software, and that part works today with no account, no API key and no approval. The next step is letting software work **inside** a professional's account, with their permission: keep their listings current, add their leads, book their visits. That part is planned. This section documents both, and marks what is not live yet. ## What is live today [#what-is-live-today] | Surface | Where | Use it to | |---|---|---| | MCP server | `https://matchai.co/mcp` | Let an AI assistant search listings, open one listing and look up a broker | | Listing search | `https://matchai.co/ask` | Search published listings in plain language from your own code | | AI-readable pages | `/llms.txt`, Markdown copies, `/sitemap.xml` on every Matchai host | Read a broker's site or Matchai Page as clean text | | OpenAPI contract | `https://matchai.co/openapi.json` | Inspect the public endpoints or generate a client | The OpenAPI file at `/openapi.json` describes these public, read-only endpoints and nothing else. The planned API has its own contract, described [below](#what-is-coming). ### Try it [#try-it] This request searches every published listing on Matchai and returns up to 10 matches as JSON: ```bash title="Terminal" curl "https://matchai.co/ask?query=3+bedroom+condo+in+Laval+under+600k" ``` The [listing search](https://matchai.co/docs/developers/listing-search) page explains the request, the response and the limits. ### Ground rules for the public surfaces [#ground-rules-for-the-public-surfaces] - **Read-only and public.** Nothing here changes data, and nothing is tied to a user account. - **Published data only.** Listings, sites and pages a professional has not published are never returned. Phone numbers and email addresses appear only where the professional chose to publish them on their business card. - **Fair-use limits.** Each public endpoint limits how many requests one caller can make per minute. The [limits](https://matchai.co/docs/developers/rate-limits) are on one page. - **Results are not for sale.** Results are ordered by relevance to the request and by how recently the listing was updated. No broker can pay to change the order or to be included. - **Link back.** When you show a listing, link to its listing page. That page is the source for the current price, status and details. ## What is coming [#what-is-coming] **(Coming soon)** The Matchai API lets an app act for **one Matchai account**: read and edit its listings, keep its contacts, send messages, book visits, file documents and hear about changes. It can do what the account holder can do in Matchai, under the same rules and permissions, and nothing more. None of it is open yet. The pages below describe how it will work, so you can plan. | Surface | Where | Use it to | |---|---|---| | Matchai API | `https://api.matchai.co/v1` | Read and change one account's listings, contacts, conversations, calendar, documents, sites and Matchai Page | | API keys | **Settings → Connectors → Advanced (for developers)** | Script your own account, or feed your own AI tools | | Connect with Matchai | OAuth 2.1 | Let professionals connect their account to your app in a few clicks | | Webhooks | Your `https` endpoint | Hear about new leads, bookings and published listings as they happen | | Authenticated MCP tools | `https://matchai.co/mcp` | Give an AI assistant a professional's own actions, after they connect it | Four rules shape all of it: - **One credential, one account.** A key or token never reaches another account's data. An app that serves three professionals holds three connections. - **Final actions ask first.** Sending, publishing, paying and deleting wait for the account holder's approval unless they chose **Allowed** for your app. - **Public reads stay free.** Reading what a professional has already published needs no connection. Connecting an app to an account is a paid Matchai Connector, and an app connected only to its developer's own account is in free test mode. - **Energy is a state, never a number.** Actions that use AI or send messages by text spend Matchai Energy, like they do in the app. Start with the [quickstart](https://matchai.co/docs/developers/quickstart), then read [authentication](https://matchai.co/docs/developers/authentication). ## Who this is for [#who-this-is-for] - **Developers building with AI assistants.** Connect the [MCP server](https://matchai.co/docs/developers/mcp-server) to your own assistant or script, or call [listing search](https://matchai.co/docs/developers/listing-search) directly. Both work today. - **Website builders.** If you host a broker's website on Matchai, every [AI-readable page](https://matchai.co/docs/developers/agent-readable-pages) is already there. When the API opens, you will be able to read a broker's listings, send their website leads into their Matchai contacts, book viewings against their real availability, and hear about changes with webhooks. A broker connects their account to your product with [Connect with Matchai](https://matchai.co/docs/developers/authentication/connect-with-matchai). - **Brokers and teams who script their own tools.** Use an [API key](https://matchai.co/docs/developers/authentication/api-keys) to work with your own account from your own code. - **People who want their own assistant to know Matchai listings.** Add the MCP server to Claude or ChatGPT in a few minutes. The steps are in the [MCP server guide](https://matchai.co/docs/developers/mcp-server#connect-an-assistant). Create an API key, call the API and add a contact. Coming soon. API keys, Connect with Matchai, scopes and approvals. Coming soon. Endpoints, transport and setup for Claude, ChatGPT and any other MCP client. Inputs, outputs and examples for search_listings, get_listing and get_professional. Natural-language search over published listings with the /ask endpoint. How Matchai sites describe themselves to AI assistants, and how to mirror it. Events pushed to your endpoint, with signed deliveries. Coming soon. End-to-end walkthroughs for website builders and AI assistants. Coming soon. Every planned endpoint, with its scopes, pricing and examples. Coming soon. The error format, every error code and how to retry. Coming soon. What the public surfaces allow today, and how limits will work in the API. How the API changes without breaking your app. Coming soon. What changed in the developer documentation and, later, in the API. ## Sitemap - [Every page of Matchai Docs](https://matchai.co/docs/sitemap.md) - [llms.txt](https://matchai.co/docs/llms.txt)