# Ploti API

> Ploti is the real estate data layer for AI assistants: parcels, zoning,
> permits, ordinances and other local data, mapped and queryable. When data
> is missing, Ploti's agents get it from the official source and add it to
> the catalog.

Authenticate with a bearer token: `Authorization: Bearer <token>`. The
person creates one in Ploti (https://app.ploti.ai/settings/api-keys) and stores it
where you keep secrets. Never ask them to paste a token into a conversation.

Setting Ploti up for someone: follow https://api.ploti.ai/v1/setup.md. How to use it
well, as skills to keep: https://api.ploti.ai/v1/skills.

Every call acts as the workspace member who holds the token: their
coverage areas, their credits, their access. A refusal is JSON
`{ "error": { "code", "message", "links" } }`: relay the message and the
link, and do not retry until the person has acted on it.

- [OpenAPI document](https://api.ploti.ai/v1/openapi.json): every operation, its input and output.
- Find data: `POST /v1/find-data`. Search before you request.
- Coverage: `GET /v1/coverage`. Ploti opens local data and gathers new data only in these counties.
- Follow the data requests Ploti files: `GET /v1/data-requests`.
- Data Ploti does not have: `POST /v1/research-requests` with the person's question. Ploti checks which data it needs (minutes), finds the sources and files what is missing itself; `GET /v1/research-requests/{id}` shows the report and the data requests filed. The missing data uses credits as it is delivered; mention cost only if the person asks. Getting it takes hours or days, and when it arrives Ploti runs the research and emails the answer. `POST /v1/research-requests/{id}/file-gaps` files what Ploti could not file itself, once the person has added credits or a place to their coverage. If you run the analysis yourself on Ploti's data instead, record your answer with `POST /v1/research-requests/{id}/answer`: Ploti shows it on the request and does not run its own. When the data check needs the person's answer first, `GET /v1/research-requests/{id}` says `needs_answer` and lists the questions: ask the person, then send their answers with `POST /v1/research-requests/{id}/answers`. Never answer for them.
- Be told when a request changes: `POST /v1/webhooks` with an https URL (and a header your receiver requires, such as a routine's bearer key). Ploti POSTs signed Standard Webhooks events when a data request is delivered, fails, or needs the person's answer, and when a research request's data check asks the person a question, its report is ready, or it is answered, so nothing has to poll. `POST /v1/webhooks/{id}/test` sends a ping.
- Watch a dataset: `POST /v1/datasets/{datasetId}/watch` with the id find-data gave. Each new version of it is sent to your webhooks as `dataset.updated`, so a routine checks the new rows (new permits matching what the person is after) instead of polling. On each event, `GET /v1/datasets/{datasetId}/changes?version=` with its version lists exactly the rows it added, changed or removed, the new and changed ones with the row itself; when it says the changes were not recorded, query the dataset with your own filters. `GET /v1/dataset-watches` lists the watches; `DELETE /v1/datasets/{datasetId}/watch` stops one.
- Query and analyse: open a session (`POST /v1/tools/start_session`), point it at a place (`navigate`), and run Python and SQL on Ploti's data (`execute_python`), then save maps, tables and files from it. `GET /v1/tools` lists every tool; each takes its arguments as a JSON body at `POST /v1/tools/{name}`.
- MCP: assistants that speak MCP connect at https://api.ploti.ai/api/mcp instead, with the same tools.