# BestProp.ai public API and connector consumer guide

Read published BestProp.ai property reports, news, blogs and articles through
REST or an MCP connector. Public reads need no BestProp account or API key.

See [API docs](https://www.bestprop.ai/api-docs) for the configured endpoint and
service availability, and [MCP & connectors](https://www.bestprop.ai/connectors)
for assistant setup and platform availability. Documentation alone does not
connect an application or grant an assistant access.

## 1. Choose an interface

| Consumer | Interface |
| --- | --- |
| Website, mobile app, backend, script | REST JSON over HTTPS. |
| ChatGPT, Claude, Codex, other MCP-aware client | Streamable HTTP MCP. |
| Client-code generation and API exploration | Generated OpenAPI and consumer reference. |

Example base origin: `https://api.bestprop.ai`. The example hostname is not a
claim of a live deployment. Use the configured origin shown in
[API docs](https://www.bestprop.ai/api-docs) for actual requests.

- REST: `/v1`.
- Research MCP: `/mcp` (five tools, one research resource).
- GST MCP: `/mcp/gst` (twelve tools, one GST resource; separate connection).
- Bhoomi MCP: `/mcp/bhoomi` (six tools, one private RTC workspace; separate connection).
- Claude GST/Bhoomi connections select `?ui_host=claude`; OpenAI uses the query-free URL.
- Reference: `/docs` and `/openapi.json`.

An application must implement the chosen client protocol. A public MCP endpoint
does not automatically connect every application.

## 2. Authentication

Published content reads require no BestProp account, cookie, or consumer API key.
An assistant user still enables the integration under the host's account and
workspace permissions. BestProp database credentials are server-only and are
never supplied to consumers.

Public browser REST calls allow noncredentialed CORS. Do not send website session
cookies. Saved lists, personal history, private research and account actions are
outside v1 and require a separately implemented OAuth extension.

## 3. Content coverage

| Public kind | Coverage |
| --- | --- |
| `project` | Published property reports backed by the website's approved public facts. |
| `news` | Published editorial news with its public author/date/source disclosures. |
| `blog` | Published editorial blogs with their admitted prose and attribution. |
| `article` | Admitted published investment, buyer-guide, FAQ, area-guide, persona and saved comparison pages, retaining their subtype. |

News and blogs are also articles in everyday language; their API kind remains
explicit. `article` is a public grouping, not a claim that the database has an
`article` page type. Only admitted source/type combinations are included.
Unrecognized page types do not become public by default.

Each response contains only eligible public data. It does not expose draft
payloads, raw research, internal metadata, prompts, private source packets,
database IDs used as access credentials, or arbitrary database tables.

## 4. Endpoints

| Path | Method | Purpose |
| --- | --- | --- |
| `/v1/content` | GET | List/search by public kind and bounded query. |
| `/v1/content/recent` | GET | Fresh newest-first feed with bounded cursor pagination. |
| `/v1/content/by-slug?slug=…` | GET | Exact public content and bounded sections. |
| `/v1/projects` | GET | Project discovery with approved geographic/builder filters. |
| `/v1/projects/compare?slugs=a,b` | GET | Ordered comparison of exactly two or three distinct projects. |

Use slugs returned by the API, not a guessed title or a full external URL.
Slugs may contain multiple segments, for example an editorial prefix. Pass the
exact slug as a URL-encoded query value to `by-slug`; do not treat it as a single
path segment or encode the whole API URL. Follow the returned canonical website
URL; do not infer public routes from a content kind.

### Request examples

These requests use the example origin above. Replace it with the configured
origin and replace slug placeholders with actual published slugs from a response.

```bash
curl --get 'https://api.bestprop.ai/v1/content' \
  --data-urlencode 'kind=news' \
  --data-urlencode 'sort=newest' \
  --data-urlencode 'pageSize=12'

curl --get 'https://api.bestprop.ai/v1/projects' \
  --data-urlencode 'city=Bengaluru' \
  --data-urlencode 'pageSize=12'

curl --get 'https://api.bestprop.ai/v1/content/by-slug' \
  --data-urlencode 'slug=<published-slug>'

curl --get 'https://api.bestprop.ai/v1/projects/compare' \
  --data-urlencode 'slugs=<first-published-project>,<second-published-project>'
```

Example browser client:

```javascript
const url = new URL('https://api.bestprop.ai/v1/content');
url.searchParams.set('kind', 'blog');
url.searchParams.set('pageSize', '12');
const response = await fetch(url, { credentials: 'omit' });
const payload = await response.json();
if (!response.ok) throw new Error(payload.code ?? 'public_api_failed');
// Validate the deployed response schema before rendering payload.data.
```

### Inputs and pagination

- Project filters: `q`, `city`, `area`, `builder`, `zone`, `sort`, `page`, `pageSize`.
- Catalog defaults: `sort=relevance`, `page=1`, `pageSize=24`.
- Catalog page sizes: 12/24; page ceiling: 500.
- `q` searches public title, description, location and builder text; raw article
  bodies and internal comments are not search inputs.
- Query maximum: 160 characters and 640 UTF-8 bytes; facets: 80 characters and
  320 UTF-8 bytes.
- Budget, BHK and possession/status filtering are unsupported public capabilities.
- Project-specific filters are invalid for other content kinds.
- Recent feed accepts `kind`, `limit` (1–24, default 12) and opaque `cursor`.
  Detail accepts `slug`, `sectionOffset` (0–1000) and `sectionLimit` (1–6, default 3).
- Cursors are opaque, bounded and bound to their filters. Use the returned next
  cursor unchanged; do not treat it as a durable notification/change-stream token.
- Long pages are delivered in bounded sections with pagination, or read through
  their canonical website link. Response size is not unlimited.

Unknown keys, malformed pagination, duplicate comparison slugs and unsupported
filters produce explicit validation errors.

## 5. Response meaning

The response envelope has `schemaVersion: "bestprop-public/v1"`, `servedAt`,
typed `data` and structured `disclosures`; pagination fields belong inside `data`.
Public items contain kind/subtype, slug, title, canonical URL, actual public dates,
and admitted images/author/excerpt/facts.
Detail includes public sections and source links according to the content kind.

`servedAt` is the API retrieval time. It does not establish that a research fact,
price, construction status or source document was updated then. Preserve original
dates, evidence labels, snapshot limitations, units and conceptual-image labels
when displaying results. A property report does not promise live inventory or a
guaranteed price. Missing facts remain unavailable; do not invent placeholder facts.

Only associate sources with claims when the public provenance supports that link.
Link back to the canonical BestProp report and retain public attribution.

## 6. How new data becomes available

1. BestProp saves a draft through its existing private workflow.
2. The existing publication decision admits the content for public use.
3. The publication repository commits the public version and its search entry
   atomically, including updates and removal/deactivation.
4. REST and MCP read those shared committed records on the next request.

Supported publication and revision operations own this transaction. Related
media and builder mutations refresh their affected publications in their own
transactions; separate API calls and bulk item loops are separate commits.

New supported publications need no deployment, tool registration or separate
import. The service initially avoids result caching and sends `Cache-Control:
no-store`. Concurrent reads obey database isolation. Unsupported content types
and private records remain excluded; adding a new category requires a contract
release.

A failed publication/index transaction must roll back consistently. External
website cache revalidation happens after commit and has separate observability.
An existing assistant answer will not rewrite itself when new content arrives;
the next connector call retrieves current data. No push subscription or database
change stream is part of v1.

## 7. MCP clients and assistant connection

Use the configured API origin plus `/mcp` for published property research.
Use a separate connection to `/mcp/gst` for GST calculation and review. Both are
anonymous Streamable HTTP endpoints; neither exposes the other surface's tools
or resource.
Initialize an MCP client, discover tools and call them using their advertised
input schemas. The public research tools share the REST content and disclosure contracts:

| MCP tool | Purpose |
| --- | --- |
| `search_content` | Search admitted categories; project filters require `kind=project`. |
| `get_content` | Read an exact returned public slug and paginate its sections. |
| `list_recent_content` | Retrieve newest published content with an opaque continuation cursor. |
| `compare_projects` | Compare two or three distinct project slugs in their requested order. |

Do not treat `/mcp` as an ordinary JSON GET route. Follow the MCP transport's
negotiated protocol and Accept headers. Useful text and structured results remain
available when a host does not support interactive cards or tables.

[Connect ChatGPT, Claude, Codex or another MCP client](https://www.bestprop.ai/connectors).
Each host has separate connection settings, account policies and qualification.
A public ChatGPT listing requires OpenAI review and publication; deploying an
endpoint alone does not create a directory listing.

### GST review tools and private files

The separate `/mcp/gst` connection exposes deterministic GST calculator/calendar
tools and spreadsheet review operations. It has eleven calculation/review tools
plus the app-only `open_gst_workspace` launcher and one GST resource. The research
connection has four public data tools plus `open_research_workspace` and one
research resource. Discover `inspect_gst_spreadsheet`,
`map_gst_spreadsheet`, `inspect_gst_portal_evidence`, `reconcile_gst_books`,
`calculate_gst_liability`, `prepare_gst_return` and `map_gst_return_errors`
in the GST server; they are not available through `/mcp` or REST. They
use the supplied books/evidence/context, retain source rows, and return bounded
summaries/findings with explicit pagination. They do not read or persist books
in the BestProp database.

The `bestprop-gst` package includes six GST skills and a manually invoked Node
CLI for explicitly authorised local files. The `bestprop-ai` research package
has no GST skills or CLI. Install each separately when both are needed; local
package installation and actual host qualification are distinct from public
directory approval. Never turn a local path into a remote download URL.

For [OpenAI host file inputs](https://developers.openai.com/plugins/reference#file-apis),
the required fields are `download_url` and `file_id`; `mime_type` and `file_name`
are optional. Treat the temporary URL as a private capability, never a public
invoice link. The server permits downloads only from exact operator-configured
trusted HTTPS origins and denies redirects, unsafe ports/credentials and
private/special resolved IPs. Remote downloads default to disabled. Inline
CSV/base64 XLSX/JSON remains available within the 32 KiB MCP body ceiling;
larger authorised local files can use the browser or packaged local CLI.

Supported file input is bounded to 4 MiB, with separate XLSX expansion/row/cell
limits. Remote download has a 10-second deadline and observes request
cancellation. Results retain the 64 KiB ceiling: request further pages rather
than assuming a preview is the complete book. Sharing data with a remote
connector processes it through the assistant host and BestProp server, not
only your device. The server retains no file store, public artifact URLs or
payload logs; host-specific retention remains governed by that host.

Matching does not prove ITC eligibility. Liability requires supplied reviewed
decisions/ledgers, and generated return artifacts remain review workings or
explicitly unqualified offline-tool input. There is no GST portal login,
upload, filing, payment, OTP/DSC or IRN tool. Government-format acceptance and
an authorised GSP connection need their own current-schema, provider,
taxpayer-consent and independent processing evidence. Do not supply portal
credentials to the conversation or label a local export as uploaded/filed.

## 8. Errors, limits and versioning

REST errors use RFC 9457 problem details, with stable `code` and safe request ID.
Error categories include invalid input (400), unavailable public content (404),
oversized request (413), response-size excess (422), rate limits (429), and
upstream/service failure (5xx).
Private, missing and unpublished slugs share the same unavailable outcome.
MCP uses its native protocol/tool error contract.

Default budgets: 32 KiB MCP request, 24 list items, 64 KiB serialized
response, two/three comparison projects, and a 10-second operation target.
Request abandonment is supported by AbortSignal checks before/after repository
work. Running PostgreSQL statements remain bounded by statement timeouts, rather
than being instantly cancelled on disconnect. Admission remains occupied until
that work settles, preventing deadline-based over-admission.

Follow documented rate-limit guidance and Retry-After when returned; do not loop
on invalid input. Large content uses section pagination.

REST contracts use `/v1` and an envelope schema version. OpenAPI is generated
from the deployed validation schemas, with anonymous security requirements.
The envelope schema version is `bestprop-public/v1`. Consumers validate schemas
and handle disclosures/errors explicitly. Retrieve `/openapi.json` from the
configured service origin for its machine-readable endpoint and response schemas.

## 9. Reference for applications and agents

- [Public API documentation](https://www.bestprop.ai/api-docs).
- [REST consumer reference as Markdown](https://www.bestprop.ai/api-reference.md).
- [MCP and assistant connectors](https://www.bestprop.ai/connectors).
- [Connector reference as Markdown](https://www.bestprop.ai/connector-reference.md).
- [MCP client documentation](https://modelcontextprotocol.io/docs/develop/connect-remote-servers).

Read the configured endpoint's OpenAPI contract before building an integration.
For MCP, tool discovery provides the input and output schemas at connection time.
Human-readable and Markdown guides explain authentication, content eligibility,
source attribution and freshness; an AI client still needs HTTP or MCP tool access
to call the service.


## Bhoomi RTC guide and private reader

The dedicated Bhoomi connection exposes `open_bhoomi_rtc_workspace`,
`get_rtc_service_guide`, `start_rtc_read`, `get_rtc_read_status`,
`discard_rtc_read` and `prepare_rtc_checklist`. Private status/discard and the
workspace launcher are app-only. Research and GST calls are unavailable here.

The official-service guide and context-only checklist work without a file.
Reading is disabled by default and requires qualified internal extraction,
explicit user permission and a real attachment reference from an admitted host
origin. Unsupported hosts receive an honest unavailable result. Never place raw
file bytes/base64, capabilities or private source values in chat text. Private
results and handles use UI metadata; consume every bounded result chunk.

The website reader uses a same-origin private relay at `/tools/bhoomi-rtc`.
Its job status/discard require the matching bearer capability, are no-store and
are not public content routes or wildcard CORS APIs. The transient job manager
requires one API process/replica. Expiry and restart can lose the session;
discard does not erase host attachments or downloaded exports.

Keep original evidence, unknown/uncertain fields and separate user corrections.
Exports are redacted by default. No government lookup/login/payment, record
mutation, authenticity/title certification or legal clearance is provided.
Actual deployment, owned widget origin and installed-host qualification must be
verified separately before claiming reader availability.