API docs | BestProp.ai

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 for the configured endpoint and service availability, and MCP & 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 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.

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:

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

BestProp saves a draft through its existing private workflow.
The existing publication decision admits the content for public use.
The publication repository commits the public version and its search entry atomically, including updates and removal/deactivation.
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. 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, 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

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.

Connection status