Build on recorded condo sales

One REST API and one MCP server over CURVE's registry-verified condominium record: every recorded sale, each unit's resale chain, owners of record, condo documents, analytics and your own MLS. Connect an AI assistant in a minute, or call it directly.

Your first call
curl -s "https://curvereports.com/api/v1/markets" \
  -H "Authorization: Bearer $CURVE_TOKEN"
92REST endpoints
11Scopes
MCPClaude · ChatGPT · Cursor
v3.1OpenAPI spec

Quickstart

From a CURVE account to your first call.

  1. Have a paid CURVE plan
    The API authenticates as you, so it carries your account's market entitlements. Personal access tokens and the REST API work on Data and Data + Social and on a team seat. An account without a paid plan gets 403 api_requires_paid_plan on every route. The Claude and ChatGPT connector (MCP over OAuth) also works on CURVE Free.
  2. Create a personal access token
    Account → API & Connections → Personal access tokens. Pick the scopes you need, pick an expiry, and copy the secret — it starts with curve_pat_ and is shown exactly once.
  3. Make your first call
    Every response is an envelope: a data payload plus meta. List endpoints add next_cursor. This one returns the markets your account is entitled to — the ids you substitute for {market} everywhere else.
    Terminal
    curl -s "https://curvereports.com/api/v1/markets" \
      -H "Authorization: Bearer $CURVE_TOKEN"
  4. Read the machine-readable spec
    The full OpenAPI 3.1 document is served at https://curvereports.com/api/v1/openapi.json. Point a client generator at it rather than hand-writing types — it is generated from the same route registry this page is, and it declares every operation's path and query parameters, error codes, and — for every write operation — its JSON request body.

What comes back

200 OK
{
  "data": [
    {
      "id": "boston",
      "name": "Boston",
      "live": true,
      "capabilities": { ... },
      "building_count": ...,
      "dataset_version": "...",
      "completed_at": "..."
    }
  ],
  "meta": {}
}

Every success is an envelope: data plus meta. List endpoints add next_cursor — pass it back as ?cursor= to page forward, and size pages with ?limit= (default 100, max 500). A next_cursor of null means you have the whole set.

Base URL https://curvereports.com/api/v1. Full specification: https://curvereports.com/api/v1/openapi.json. Every route is documented there with the same summaries you see below, because both are generated from one registry.

Authentication

Two ways in, one verifier behind them. Both produce a bearer token that carries YOUR account’s market entitlements and plan limits — the API never sees data your account cannot. Paid CURVE Data and Data + Social plans include API, MCP, and webhooks. The /me response returns your plan identifier, for example data or data_social.

Personal access tokens

For your own scripts, notebooks and back-office jobs. Create one at Account → API & Connections.

  • Created at Account → API & Connections → Personal access tokens. The secret starts with curve_pat_ and is displayed exactly once.
  • Scopes are chosen per token. Every scope is pre-selected EXCEPT owners:export, connected:read, admin:read, admin:write — bulk owner export and connected account reads require explicit selection even on a token you mint for yourself, and the admin portal scopes are offered only to CURVE admin and partner accounts.
  • Expiry is your choice: never, 30, 90 or 365 days. Revoking a token kills it immediately.
  • Send it as Authorization: Bearer curve_pat_.... Never put it in a query string, a client bundle, or a public repository.

OAuth 2.1 with PKCE

For an application connecting on a user’s behalf — including every MCP client. Nobody copies a token: the client discovers CURVE from the metadata documents below, the user reviews every requested permission before approving, and the grant is revocable at any time from Account → API & Connections → Connected apps.

Dynamic client registration (RFC 7591)https://curvereports.com/api/oauth/register
Grant typesauthorization_code, refresh_token
PKCERequired. S256 only — plain is absent, not merely discouraged.
Client authenticationnone — every client is public. A client_id may be an HTTPS URL serving its own metadata document (CIMD); dynamic registration is the fallback.
Access token lifetime1 hour.
Refresh tokenRequest offline_access (advertised in authorization-server metadata). Tokens use a 30-day sliding window and rotate on every use; reuse revokes the whole grant.
Issuer identificationRFC 9207 — the authorization response carries iss.
Scope defaults are asymmetric, on purposeAn OAuth client that names NO scope in its authorization request receives only data:read, docs:read, ai:ask, workflow:read, reports:generate. That is deliberately narrower than a personal token: owners:read, owners:export, connected:read, workflow:write, admin:read, admin:write must be requested BY NAME and are shown on the consent screen before approval. Anything that hands over personal data, writes on the user's behalf, or carries a third-party licence obligation is never granted by omission.

Scopes

A token carries the scopes it was granted and nothing more. A call missing one answers 403 insufficient_scope, and the WWW-Authenticate header repeats the scopes the route required.

ScopeGrantsPersonal tokenOAuth, no scope requested
data:read
Market data
Read market data: buildings, sales, units, registry events, analytics, developer intelligence, and dataset downloads for your entitled markets.Pre-selectedGranted
docs:read
Condo documents
Read condo documents (master deeds, amendments, plans) and their OCR'd page text for your entitled markets.Pre-selectedGranted
owners:read
Owner lists
View owner-of-record lists and intelligence briefs; unlock full lists using your account's permanent included-building allowance.Pre-selectedMust be requested by name
owners:export
Owner exports
Export or publish full owner lists, and retrieve/email their public bearer links. Publishing counts against your account's rolling export quota.Off by defaultMust be requested by name
ai:ask
Curve AI
Ask Curve AI questions and receive grounded, cited answers.Pre-selectedGranted
connected:read
Connected account reads
Let Curve AI read your connected Microsoft email, calendar, and OneDrive files when you explicitly ask for them.Off by defaultMust be requested by name
workflow:read
Workflow read
Read your shares, QR artifacts, reusable colleague invite, embeds, trackers, follows, pins, CMA sheets, engagement data and webhook metadata/history. Owner-list bearer links additionally require owners:export. Webhook destination URLs and signing secrets are omitted.Pre-selectedGranted
workflow:write
Workflow write
Create and manage shares, QR artifacts, reusable colleague invites, embeds, trackers, follows, pins, CMA sheets and webhooks; send share emails, schedule tracker emails, rotate webhook secrets and replay failed deliveries. Publishing owner lists additionally requires owners:export; document shares require docs:read.Pre-selectedMust be requested by name
reports:generate
Report PDFs
Generate branded building report PDFs.Pre-selectedGranted
admin:read
Admin portal (read)
CURVE admin and partner accounts only: read the admin portal (accounts, plans, promos, signup links, teams, funnel and activity). A partner reads only their own customers.Off by defaultMust be requested by name
admin:write
Admin portal (changes)
CURVE admin and partner accounts only: run admin portal changes (provision and edit accounts, plans, promos, signup links, teams, billing links and customer emails). A partner changes only their own customers.Off by defaultMust be requested by name

Connect an AI assistant

CURVE runs an MCP server, so an assistant can query the record directly rather than being pasted screenshots of it.

  • Every authenticated MCP request consumes the general request budget, including invalid or refused tool calls. Expensive tools additionally consume their named quota class; tools invoked inside ask_curve retain those quotas.
  • Read-only MCP building searches and lookups never submit building-addition requests. A missing result means no matching catalog entry was found.
  • AI conversation history is isolated to the API connection and its granted permissions. OAuth refresh preserves the connection; reduced permissions, a new token, or product-created history require a new conversation.
  • Disconnect and permission reductions apply to previously issued OAuth access tokens on their next verification. Consent displays the requested capabilities and validated callback destination before approval.
  • Endpoint: https://curvereports.com/api/mcp
  • Transport: Streamable HTTP, MCP specification revision 2026-07-28.
  • The MCP tools and the REST endpoints run behind the same verifier, the same scopes and the same quota classes — anything a tool can do, a token with that scope can do over REST. REST is the wider surface: datasets, the Daily Bulletin, market-wide events, /v1/me and /v1/usage have no tool.
  • CORS is open, and MCP-Protocol-Version, Mcp-Method and Mcp-Name are all allowed on preflight, so a browser-hosted client can connect.
  • Every tool carries all four MCP annotations — readOnlyHint, destructiveHint, idempotentHint and openWorldHint — so a client can confirm only what genuinely needs confirming. The reads are annotated read-only; a write that only adds something declares destructiveHint false; and the handful that take something away, send real email, replace stored rows or spend a permanent allowance are the ones that ask. In particular, get_owner_list is a pure read and unlock_owner_list is the separate tool that spends an included-building slot.

One click

These editors install an MCP server from a link. The link carries the CURVE address; the editor runs the OAuth approval. There is nothing to paste and no token to mint.

This is a shortcut CURVE has not been able to test end to end — try it, and if nothing happens use the Claude steps below, which are the supported path either way. ChatGPT has no one-click install; its steps are below too.

Or have an assistant do it

Paste this into an assistant that can run shell commands — Claude Code, Codex CLI, Cursor's agent. It names both add commands, so the assistant runs the one that matches itself and then tells you how to authorize. An assistant that cannot register a server says so rather than improvising.

Paste into your assistant
Connect me to CURVE, a real-estate market-data MCP server at https://curvereports.com/api/mcp.

Run the commands for your client. The second one opens the CURVE approval page in my browser:
- Claude Code: claude mcp add --transport http --scope user curve https://curvereports.com/api/mcp && claude mcp login curve
- Codex CLI: codex mcp add curve --url https://curvereports.com/api/mcp && codex mcp login curve

Then tell me to click Approve. Never ask for a token or password.

If you cannot run commands, tell me where to add the URL manually instead of trying to sign in for me.

Or add it by hand

Every client, including the ones with no one-click install.

claude.ai

  1. Settings → Connectors → Add custom connector.
  2. Paste the CURVE MCP URL: https://curvereports.com/api/mcp
  3. Click Connect. Claude discovers CURVE's authorization server, registers itself, and sends you to CURVE's authorization screen.
  4. Sign in to CURVE if you are not already and click Approve. No token is copied by hand.
  5. The connection appears under Account → API & Connections → Connected apps, where you can revoke it at any time.

Claude Code

  1. Run both commands below in any terminal.
  2. The second one opens the CURVE approval page in your browser; click Approve once. CURVE is then available in every project.
  3. Ask something like "what did units at Millennium Tower sell for last year?" to confirm the tools are live.
Terminal
claude mcp add --transport http --scope user curve https://curvereports.com/api/mcp
claude mcp login curve

Codex CLI

  1. Run both commands below in any terminal.
  2. The second one opens the CURVE authorization screen in your browser; approve it once. Codex then holds an OAuth grant, so there is no token to mint and no environment variable to keep in sync.
  3. The connection appears under Account → API & Connections → Connected apps, where you can revoke it at any time.
Terminal
codex mcp add curve --url https://curvereports.com/api/mcp
codex mcp login curve

ChatGPT

  1. Click your name → Settings → Plugins (under Integrations), then Add → Add custom MCP server.
  2. Name: CURVE. Connection: Server URL https://curvereports.com/api/mcp (https://curvereports.com/mcp also works). Authentication: OAuth. Leave Advanced OAuth settings alone: ChatGPT discovers CURVE's authorization server and registers itself from its published client metadata.
  3. Tick “I understand and want to continue”, click Create as a plugin, then Connect CURVE. Sign in to CURVE and click Approve; ChatGPT returns to its Plugins page.
  4. In a chat, choose CURVE from the + menu. The connection appears under Account → API & Connections → Connected apps, where you can revoke it at any time.
  5. Verified end to end on ChatGPT Pro (November 2026). On a Business or Enterprise workspace an admin may have to allow custom MCP servers before members see Add custom MCP server.

Any other MCP client

  1. Transport is Streamable HTTP at https://curvereports.com/api/mcp — one endpoint, POST for every request. The server is stateless, so there is no GET server stream to open (GET answers 405), no stdio binary to install and no SSE-only fallback.
  2. Authentication is a bearer token: either an OAuth 2.1 access token obtained through the discovery documents listed under Authentication, or a personal access token sent as Authorization: Bearer curve_pat_....
  3. An unauthenticated request answers 401 with a WWW-Authenticate header naming the protected-resource metadata document, which is where a compliant client starts discovery.
  4. Call tools/list for the live tool catalogue: it is the authoritative list, and each tool's description names the scope it needs, its caps and its refusals.
Discovery, if you are writing the clientAn unauthenticated request to https://curvereports.com/api/mcp answers 401 with a WWW-Authenticate header naming https://curvereports.com/.well-known/oauth-protected-resource. That document names the authorization server, whose metadata is at https://curvereports.com/.well-known/oauth-authorization-server. The RFC 9728 resource-suffixed https://curvereports.com/.well-known/oauth-protected-resource/api/mcp is served too, identically, for clients that derive that path from the resource URL instead of following the header.

Endpoint reference

All 92 REST endpoints, with the scopes and quota class each one requires. This table and the OpenAPI document are generated from the same route registry, so they cannot disagree.

Webhooks

13 endpoints

Signed outbound events, destination and trigger controls, delivery history and explicit replay. Read access omits URLs and signing secrets.

GET
/v1/webhooks
workflow:readgeneral
List all owned webhook destinations and triggers. Read responses contain hostname metadata, never destination URLs or signing secrets.
GET
/v1/webhooks/events
workflow:readgeneral
Discover the nine supported webhook event types and their building-scope requirements.
POST
/v1/webhooks
workflow:writeworkflow_write
Atomically create a destination and initial trigger. The signing secret is returned once. Public HTTPS only; maximum 10 destinations per user.
GET
/v1/webhooks/{id}
workflow:readgeneral
Get an owned destination and its triggers, with URL and secret omitted.
PATCH
/v1/webhooks/{id}
workflow:writeworkflow_write
Update name, public HTTPS URL or active/paused status. Resuming resets consecutive failures.
DELETE
/v1/webhooks/{id}
workflow:writeworkflow_write
Delete an owned destination and its triggers, events and delivery history.
POST
/v1/webhooks/{id}/test
workflow:writeworkflow_write
Send a signed webhook.test immediately, including for a paused destination. This test is not queued or automatically retried.
POST
/v1/webhooks/{id}/rotate
workflow:writeworkflow_write
Replace the signing secret and return the new value once. In-flight requests may still carry the previous signature.
POST
/v1/webhooks/{id}/triggers
workflow:writeworkflow_write
Create another trigger on an owned destination, with a fresh baseline. Maximum 30 triggers per destination.
PATCH
/v1/webhooks/{id}/triggers/{triggerId}
workflow:writeworkflow_write
Replace a trigger's full event, scope and condition configuration and optional status. Establishes a new baseline; omitted fields use defaults.
DELETE
/v1/webhooks/{id}/triggers/{triggerId}
workflow:writeworkflow_write
Delete an owned trigger and its queued events and history.
GET
/v1/webhooks/{id}/deliveries
workflow:readgeneral
Page through owned delivery status and retry history, newest first. Event payloads and destination secrets are omitted.
POST
/v1/webhooks/{id}/deliveries/{deliveryId}/retry
workflow:writeworkflow_write
Replay a failed or dead owned delivery with its original event id and a new six-attempt budget. Paused destinations must be resumed separately.

Admin portal

2 endpoints

CURVE admin and partner portal accounts only: every admin portal screen and action as named operations. A partner reaches only the customers they brought in.

GET
/v1/admin/operations
admin:readgeneral
CURVE admin and partner portal accounts only. List every admin portal operation this account can run (users, plans, promos, signup links, teams, billing links, email, funnel and activity reads), each with its kind (read or write), flags (destructive, sends_email, stripe) and input JSON Schema. An owner admin gets every operation; a partner gets their partner portal's operations, scoped to the customers they brought in. An admin account without a plan of its own still reaches this admin surface.
POST
/v1/admin/operations/{operation}
any valid tokengeneral
CURVE admin and partner portal accounts only. Run one admin portal operation from GET /v1/admin/operations as this account, with exactly the portal's rules: a partner reads and changes only their own customers. The body is the operation's input (or {"input": {...}}). Reads need admin:read and changes need admin:write. Operations flagged destructive, sends_email or stripe act on real customers and money; reuse operation_id to retry a change safely.

Account & usage

2 endpoints

Who this token is, what it may see, and how much of its quota is left.

GET
/v1/me
any valid tokengeneral
Get the authenticated caller's account, plan, and token info.
GET
/v1/usage
any valid tokengeneral
Get current quota usage for the authenticated caller.

Condo documents

4 endpoints

Master deeds, amendments, plans and their OCR'd page text, plus short-lived signed PDF URLs.

GET
/v1/markets/{market}/buildings/{slug}/documents
docs:readgeneral
List condo document metadata (master deeds, amendments, plans, exhibits) for a building. Buildings with no condo docs return an empty list.
GET
/v1/markets/{market}/buildings/{slug}/documents/{docKey}
docs:readgeneral
Get a single condo document's metadata plus an extraction quality summary (whether its OCR corpus is ready, pages with text, low-text page count).
GET
/v1/markets/{market}/buildings/{slug}/documents/{docKey}/pages
docs:readgeneral
Get OCR'd page text for a condo document. Query param range=<start>-<end> (1-indexed, inclusive; default 1-20, max 50 pages per request).
GET
/v1/markets/{market}/buildings/{slug}/documents/{docKey}/pdf
docs:readgeneral
Mint a short-lived (<=10 minute) signed download URL for a condo document's PDF. Never redirects and never streams bytes; the caller fetches download_url itself.

Owners & entity resolution

3 endpoints

Owner-of-record lists, ownership chains, beneficial owners and CSV export — behind the platform's fail-closed owner-list access.

GET
/v1/markets/{market}/buildings/{slug}/owners
owners:readowners_read
Get the owner-of-record list for a building, under the account's fail-closed owner-list access. access:"full" returns every unit's owner row; access:"preview" returns the platform's 7-row preview (with an allowance + claim_hint when a claim slot remains). 403 owner_list_access_required when the caller's plan/allowance denies this building. Query param claim=true permanently unlocks this building against the account's included-building allowance (default: does not spend a slot).
GET
/v1/markets/{market}/units/{unitId}/owner
owners:readowners_read
Get a unit's current owner of record, ownership chain, entity resolution, beneficial owners, portfolio, and a typical-hold verdict. Under the same fail-closed owner-list access gate as the building owners route below; 403 owner_list_access_required when denied. Unresolvable owner returns {owner: null} — never a guess. Never spends a building-unlock slot.
POST
/v1/owners/export
owners:exportowners_export
Export a building's full owner-of-record list as a CSV attachment. Request body {market, building_slug}. Spends the account's real, shared, rolling-24h owner-export ledger (12 exports / 2,500 rows) — a building that does not fit is denied whole, never truncated. 429 owner_export_quota_exceeded when exhausted, carrying resets_at plus the same retry_after_seconds and Retry-After every 429 on this API carries. 403 owner_list_access_required when the caller's plan/allowance denies this building. GET/PUT/PATCH/DELETE return 405 (POST-only by design, so an export can never be triggered by prefetch).

MLS & TAN (retired)

7 endpoints

Retired on October 22, 2026. CURVE no longer connects to MLS PIN or Top Agent Network; every route here returns 410 mls_connection_retired.

GET
/v1/mls/connection
mls:readgeneral
Retired on October 22, 2026: CURVE no longer connects to MLS PIN or Top Agent Network, and this route returns 410 mls_connection_retired.
GET
/v1/mls/listings
mls:readgeneral
Retired on October 22, 2026: CURVE no longer connects to MLS PIN or Top Agent Network, and this route returns 410 mls_connection_retired.
POST
/v1/mls/search
mls:readmls_live
Retired on October 22, 2026: CURVE no longer connects to MLS PIN or Top Agent Network, and this route returns 410 mls_connection_retired.
POST
/v1/mls/refresh
mls:readgeneral
Retired on October 22, 2026: CURVE no longer connects to MLS PIN or Top Agent Network, and this route returns 410 mls_connection_retired.
GET
/v1/tan/workspace
mls:readgeneral
Retired on October 22, 2026: CURVE no longer connects to MLS PIN or Top Agent Network, and this route returns 410 mls_connection_retired.
POST
/v1/tan/search
mls:readmls_live
Retired on October 22, 2026: CURVE no longer connects to MLS PIN or Top Agent Network, and this route returns 410 mls_connection_retired.
GET
/v1/mls/jobs/{id}
mls:readgeneral
Retired on October 22, 2026: CURVE no longer connects to MLS PIN or Top Agent Network, and this route returns 410 mls_connection_retired.

Curve AI

1 endpoint

The grounded, cited answer pipeline the CURVE product runs, over HTTP.

POST
/v1/ask
ai:askask
Ask Curve AI a question and get a grounded, cited answer: request body {question} (plain words, <=6000 chars) plus optional thread_id to continue an earlier conversation. Runs the SAME pipeline the CURVE product runs, non-streaming. Response {answer, answer_outcome, blocks, claims, sources, grounding_status, thread_id}: answer_outcome is answered | partial | clarification | refused | failed | unknown and describes fulfillment separately from evidence grounding; grounding_status is the pipeline's own verdict (supported | needs_review) reported verbatim — needs_review still carries the answer the pipeline chose to serve. DATA BOUNDARY: your own MLS PIN and Top Agent Network listings never enter the turn: those connections were retired on October 22, 2026, and meta.mls_evidence reports reason retired. Connected Microsoft mail, calendar, and files require the separate connected:read scope and an explicit user request. Costs one ask unit; the class is fail-closed, so an exhausted quota returns 429 rate_limited with retry_after_seconds and no partial answer. Each answer also counts against the account's monthly CURVE AI allowance, the same one the product's Ask AI uses: when it is used up the call returns 429 ai_allowance_exhausted with reset_at (the next billing date); a turn that fails is not counted. CURVE also runs a platform-wide daily AI spend cap: when it is reached every Curve AI surface refuses alike, here as 429 rate_limited whose message names the cap and whose retry_after_seconds counts to the 00:00 UTC reset.

Report PDFs

2 endpoints

Branded building report rendering — a two-phase start-then-poll contract.

POST
/v1/markets/{market}/buildings/{slug}/report/pdf
reports:generatereports_generate
Start (or collect) a branded building report PDF: request body is a subset of the report studio's config (title/preparedFor/brandName/brandEmail/brandPhone/accent/brandNote, bioName/bioText/bioLinks/bioPhotoUrl/bioLogoUrl, unitFocus, criteria incl. modules — all optional; unset fields use the report's own defaults; accent must be a hex color). Reuses the SAME Chromium renderer and storage cache the platform's report PDF routes use, under a market-scoped cache key of its own (the API and web lanes encode their config differently and never share a cache entry). Two-phase: 202 {status:"preparing", cache_key, status_token, retry_after_ms} while warming; 200 {status:"ready", cache_key, download_url, filename, bytes} once cached, where download_url is a short-lived signed storage URL. POLL WITH GET on this path, passing BOTH cache_key and status_token — every POST costs a reports_generate unit and re-triggers a render. POST is also the retry: if a previous background render for this key failed, POST clears that failure and starts a fresh render in the SAME request (the failure reason is reported by GET's 409 render_failed, never by POST). canDownload enforced (403 download_not_permitted otherwise). 400 with a specific code (e.g. unknown_module_id, invalid_criteria, invalid_accent) on an invalid config.
GET
/v1/markets/{market}/buildings/{slug}/report/pdf
reports:generategeneral
Poll a report PDF's status: query params cache_key AND status_token (both returned by POST). status_token is an HMAC binding the cache key to the calling token's user, market and slug — a bare cache key names an object in the shared report PDF bucket and is never accepted on its own. Status only — it never starts or re-triggers a render, which is why polling is on the cheap general quota class. 202 {status:"preparing", cache_key, status_token, retry_after_ms} while warming; 200 {status:"ready", cache_key, download_url, filename, bytes} once the render is cached; 409 render_failed {cache_key, failed_at} with the reason if the background render failed (POST again on this path to clear it and retry); 400 invalid_cache_key if cache_key is missing or malformed; 400 invalid_status_token if status_token is missing or does not match.

Analytics

6 endpoints

The analytics query engine and saved views: one computed value per requested compute key.

POST
/v1/markets/{market}/analytics/query
data:readgeneral
Run the analytics query engine: request body {filters?, compute: string[] (1-16 of snapshot_kpis, building_matrix, cash_vs_mortgage, hold_periods, sale_cycle, sales_over_time, price_over_time, volume_over_time, seasonality, gain_loss_by_year, segments_beds, segments_sqft, segments_price, segments_psf, sell_cadence, unit_layouts), cadence?: week|month|quarter|year, seasonality?: month|quarter}. Returns one computed value per requested key.
GET
/v1/analytics/views
workflow:readgeneral
List the authenticated caller's saved analytics views (pinned first, then most recently opened).
POST
/v1/analytics/views
workflow:writeworkflow_write
Create a saved analytics view: request body {name, summary?, snapshot, marketId?}.
PATCH
/v1/analytics/views/{id}
workflow:writeworkflow_write
Update a saved analytics view's name/summary/snapshot/pin state. Seeded default views cannot be changed.
DELETE
/v1/analytics/views/{id}
workflow:writeworkflow_write
Delete a saved analytics view. Seeded default views cannot be deleted.
POST
/v1/analytics/views/{id}/run
workflow:readdata:readgeneral
Stamp a saved view as opened and run the analytics query engine over its stored snapshot: request body {compute, cadence?, seasonality?, market? (default boston)}.

Developer intelligence

3 endpoints

Sellout, absorption, pricing trajectory, floor premium and resale cohorts, per building and market-wide.

GET
/v1/markets/{market}/buildings/{slug}/developer
data:readgeneral
Get developer intelligence (sellout summary, absorption curve, pricing trajectory, unit-type/floor breakdowns, floor premium, resale cohort) for a single building. 404 on markets without the developer capability.
GET
/v1/markets/{market}/developer/compare
data:readgeneral
Compare developer intelligence for 2-5 buildings side by side: query param slugs=CSV. All buildings share one floor-band set (the union of their floors). 404 on markets without the developer capability.
GET
/v1/markets/{market}/developer/benchmark
data:readgeneral
Get the market-wide developer peer benchmark board (every building's sellout/pricing/resale stats). Optional ?target=<buildingId> adds a ranked board against that building. 404 on markets without a published benchmark model.

Datasets & bulk download

2 endpoints

Version-addressed, content-hashed dataset chunks for pulling a market's corpus down whole.

GET
/v1/markets/{market}/dataset
data:readgeneral
Get the latest published dataset artifact manifest for a market. meta.bulk_servable_categories lists which chunk categories are downloadable via the chunk route below.
GET
/v1/markets/{market}/dataset/{version}/{chunk}
data:readdataset_chunks
Download an immutable, version-addressed dataset chunk by exact chunk name. Serves latest published version only; chunk names must be percent-encoded (encodeURIComponent).

CMA & comparables

3 endpoints

The CMA Builder pipeline: ranked comparable sales and persisted comp sheets.

GET
/v1/markets/{market}/units/{unitId}/comps
data:readgeneral
Get CMA comparable-sale suggestions for a unit: mirrors the platform's CMA Builder pipeline (rankComparableSales -> composeComparableSet, 12-month window, 6 auto-selected). Query param mode=within_building|across_buildings (default across_buildings for single-family homes, within_building for condos); an unrecognized mode 400s invalid_mode. Response envelope is snake_case (algorithm_version, as_of_date, cutoff_date, eligible_count, verified_pool_count, generated_at) and carries selected + alternatives; the comparable ROWS inside them keep the CMA pipeline's own fitScore/matchBand/reasonCodes. Supports Boston, Miami and New York; unsupported markets return 404.
GET
/v1/cma/sheets
workflow:readgeneral
List the authenticated caller's CMA sheets (past comp-sheet shares), newest first, capped at 20.
POST
/v1/cma/sheets
workflow:writeworkflow_write
Compose and persist a new CMA sheet: request body {entries: [{unitSlug, role: "subject"|"comp", saleId (required for comp entries), matchReasonCodes?, selectionMode?}]}. Exactly one subject, at most 12 total units, every comp's sale re-verified server-side inside the live 12-month window. 400 with a specific code (e.g. cma_subject_required, cma_too_many_units, cma_sale_outside_window) on an invalid deck.

Shares, QR artifacts & invites

17 endpoints

Share links, document/conversation artifacts, PNG/PDF QR downloads, reusable colleague invites, email and engagement, plus embedded widgets.

GET
/v1/invites
workflow:readgeneral
Get an existing reusable colleague invite with exact market URL and branded PNG/PDF QR artifacts. Does not mint or send email. No automatic expiry; disabled codes refuse invite_disabled.
POST
/v1/invites
workflow:writeworkflow_write
Get or create the account's stable, reusable colleague invite for the selected entitled market. Repeated calls reuse the same code. Returns matching PNG/download/PDF QR artifacts. Sends no email; referral_program_enabled states whether rewards are enabled.
GET
/v1/share-artifacts
workflow:readgeneral
Get an owned master_deed, curve_ai or condo_docs share and matching QR artifacts by kind and token. Document families additionally require docs:read. These families have no automatic expiry or shared_reports revocation support.
POST
/v1/share-artifacts
workflow:writeworkflow_write
Publish an owned saved document or conversation using the platform share pipeline. master_deed and condo_docs additionally require docs:read and an entitled market; all require active report access. Exact document keys are validated. curve_ai can require a persisted message count or latest message id. Returns public bearer URL and matching PNG/download/PDF QR artifacts, expires_at:null and revocation_supported:false.
GET
/v1/shares/{token}
workflow:readgeneral
Get one owned share with exact URL, QR artifacts, expiry and active/expired/revoked status. By default refuses expired/revoked links with 410; include_inactive=true retrieves their owned metadata. Owner-list bearer links require owners:export in addition to workflow:read.
GET
/v1/share-recipients
workflow:readgeneral
Autocomplete the caller's past share recipients: query param q= (optional prefix/substring filter). Suppression-filtered (unsubscribed/bounced addresses never appear), ranked prefix-match first then most-recently-shared, capped at 8 results.
GET
/v1/shares
workflow:readgeneral
List the authenticated caller's share links, newest first. Owner-list token, URL and QR artifacts are null without owners:export consent; required_scope names the missing permission. Status is active, expired or revoked. Fields: token, url, kind (building_report|unit|analysis|developer|cma|owner_list|daily_bulletin), slug, title, created_at, expires_at, revoked_at, view_count, last_viewed_at, and recipient state as booleans only (recipient_email_present, signed_up).
POST
/v1/shares
workflow:writeworkflow_write
Create a share link: request body {kind, ...typed payload}. Supported kinds: building_report {market, slug, buildingName, reportConfig?}, unit {market, buildingSlug, unitRouteParam, buildingName, unitLabel}, analysis {market, title, snapshot, summary?, sections?, scopeLabel?}, developer {market, snapshot, title}, cma {entries: [...]} (same pipeline as POST /v1/cma/sheets), owner_list {buildingSlug, market?}, daily_bulletin {}. building_report/unit mint through the public-market path (with the market's required entitlement gate) for miami/atlanta/losangeles/newyork/sanfrancisco, or the Boston path for market:"boston". Owner-list publishing additionally requires explicit owners:export consent, a full building unlock and an atomic rolling export reservation. Every successful result includes branded PNG/download/PDF QR URLs. Unknown kind returns 400 unsupported_share_kind; each kind 400s with a specific missing-field code.
DELETE
/v1/shares/{token}
workflow:writeworkflow_write
Revoke a share link the caller owns (shared_by = caller). The revoked link's /shared/{token} page renders identically to an expired link. Not found, not owned, or already revoked all return the identical 404 not_found.
POST
/v1/shares/{token}/email
workflow:writeshare_email
Email a share link to 1-10 recipients: request body {recipients: string[], include_referral_offer?} (include_referral_offer:true refuses unsupported_referral_offer for other kinds; owner-list sends require owners:export consent). Dispatches to the same per-kind sender + fan-out (one email per recipient, each unsubscribable) and the platform's 40/hr owner rate limit the UI uses. Not owned, not found, revoked, or expired all return the identical 404 not_found (a dead link cannot be emailed). 429 share_email_rate_limited with Retry-After and retry_after_seconds when the owner's hourly ceiling is hit. Response {sent, failed: [{email, error}]}.
GET
/v1/shares/{token}/engagement
workflow:readgeneral
Get a share link's engagement: view_count, last_viewed_at, created_at, expires_at, revoked_at, email_sent_at, recipient_email_present (boolean), signed_up (boolean), cta_clicks, and views (bounded, cursor-paginated via views_cursor/views_limit query params, next cursor in meta.views_next_cursor). Owner-only; not found or not owned both return 404 not_found. Unlike the email route, a revoked/expired share still reports its history here.
GET
/v1/embeds
workflow:readgeneral
List the authenticated caller's embedded widgets with their live counters: embed_id, slug, building_name, widget_type, accent_color, embed_label, impression_count, click_count, last_seen_at, created_at.
POST
/v1/embeds
workflow:writeworkflow_write
Create an embedded widget: request body {slug, buildingName, widgetType?, accentColor?, showPrice?, showPsf?, reportConfig?, market?, embedLabel?}. widgetType is one of snapshot|feed|report|analytics|developer|daily_bulletin (default snapshot); daily_bulletin needs no slug/buildingName. canEmbed entitlement enforced; a gated caller gets 403 embed_upgrade_required with reason no_access|upgrade_to_data_social (upgrade_to_plus, its earlier name, means the same). Over this API, embeds come with Data + Social and legacy Plus and Pro; a CURVE Data caller moves to Data + Social, which costs the same. Response includes the ready-to-paste embed_code snippet.
GET
/v1/embeds/{embedId}
workflow:readgeneral
Get a single embedded widget's full record (including its stored report_config and the embed_code snippet) plus counters. Owner-only; not found or not owned both return 404 not_found.
PATCH
/v1/embeds/{embedId}
workflow:writeworkflow_write
Update a live embed's config in place (same embed_id, so the customer's already-pasted snippet is unaffected): request body {reportConfig?, accentColor?, embedLabel?} (at least one required). Re-asserts canEmbed the same way POST does. Owner-only, no-oracle 404.
DELETE
/v1/embeds/{embedId}
workflow:writeworkflow_write
Delete an embedded widget the caller owns. Not found or not owned both return the identical 404 not_found.
GET
/v1/embeds/{embedId}/engagement
workflow:readgeneral
Get an embed's engagement: impressions, clicks, status (live|idle|unplaced, a 30-day impression window), placements (per-domain impression counts aggregated from embed_events.referrer_domain, CURVE's own hosts excluded), and referral_tokens (token, expires_at, page_loads, signups_attributed). Owner-only, no-oracle 404; never returns another user's identity.

Trackers, follows & pins

16 endpoints

Saved client searches, followed units and pinned buildings.

GET
/v1/trackers/clients
workflow:readgeneral
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
POST
/v1/trackers/clients
workflow:writeworkflow_write
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
GET
/v1/trackers/clients/{clientId}
workflow:readgeneral
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
PATCH
/v1/trackers/clients/{clientId}
workflow:writeworkflow_write
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
DELETE
/v1/trackers/clients/{clientId}
workflow:writeworkflow_write
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
GET
/v1/trackers/searches
workflow:readgeneral
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
POST
/v1/trackers/searches
workflow:writeworkflow_write
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
PATCH
/v1/trackers/searches/{searchId}
workflow:writeworkflow_write
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
DELETE
/v1/trackers/searches/{searchId}
workflow:writeworkflow_write
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
GET
/v1/trackers/engagement
workflow:readgeneral
Retired on October 22, 2026 with the Tracker tab: client tracking moved to CURVE Email, and this route returns 410 tracker_retired.
GET
/v1/unit-follows
workflow:readgeneral
List the authenticated caller's unit follows (unit_id, building_id, building_slug, building_name, unit_label, market_id, created_at), newest first.
POST
/v1/unit-follows
workflow:writeworkflow_write
Follow a unit: request body {unitId}. Requires access to the selected market (403 market_access_required otherwise); capped at 200 follows per caller.
DELETE
/v1/unit-follows
workflow:writeworkflow_write
Unfollow a unit: query param unitId. No entitlement gate on the way out — always available once signed in.
GET
/v1/building-pins
workflow:readgeneral
List the authenticated caller's pinned buildings for a market (query param market, default boston): {slug, primary}[].
POST
/v1/building-pins
workflow:writeworkflow_write
Pin a building: request body {slug, market?}. Response {slugs, primary_building_slug}.
DELETE
/v1/building-pins
workflow:writeworkflow_write
Unpin a building: query params slug, market?. Response {slugs, primary_building_slug}.

Rankings & Daily Bulletin

2 endpoints

Registry-backed building superlatives and the day-keyed recorded-sales bundle.

GET
/v1/markets/{market}/rankings/{metric}
data:readgeneral
Get registry-backed building superlative rankings (most-expensive, price-per-sqft, most-sales, largest) for boston/miami/newyork. medianSalePrice, medianPsf and the two price rankings are medians of non-affordable sales in the last five years, described by the response's medianScope; a building needs at least three such sales for a price figure. saleCount and units are all-time; recentSaleCount counts the window's qualifying sales.
GET
/v1/markets/{market}/daily-bulletin
data:readgeneral
Get the Daily Bulletin's day-keyed bundle: a paginated list of recently recorded public closed sales (meta.day_key). meta.buildings (the fixed public building catalog, also served by /v1/markets/{market}/buildings) rides along on the FIRST page only — it is omitted once a cursor is supplied. Boston-only (capabilities.dailyBulletin); every other market 404s not_found.

Markets, buildings, sales & units

9 endpoints

The core corpus: every market you are entitled to, its buildings, and the recorded sales, units and registry events beneath them.

GET
/v1/markets
data:readgeneral
List markets the authenticated caller is entitled to access.
GET
/v1/markets/{market}/buildings
data:readgeneral
List buildings in a market, with district/type/q/min_sales filtering and sorting.
GET
/v1/markets/{market}/buildings/{slug}
data:readgeneral
Get a single building's record and metrics.
GET
/v1/markets/{market}/buildings/{slug}/sales
data:readgeneral
List closed sales for a building, newest-first.
GET
/v1/markets/{market}/buildings/{slug}/units
data:readgeneral
List units for a building.
GET
/v1/markets/{market}/buildings/{slug}/events
data:readgeneral
List recorded events for a building, newest-first.
GET
/v1/markets/{market}/sales
data:readgeneral
List closed sales market-wide, newest-first, with the full analytics filter vocabulary.
GET
/v1/markets/{market}/events
data:readgeneral
List recorded events market-wide, newest-first, with date_from/date_to filtering (inclusive). miami and newyork store events as per-building fragments and cannot serve a market-wide corpus: they require ?buildings=<id>[,<id>] (max 25, see /v1/markets/{market}/buildings for ids) and 400 building_filter_required without it.
GET
/v1/markets/{market}/units/{unitId}
data:readgeneral
Get a single unit's detail bundle.

Field semantics

The definitions behind the numbers. Recomputing a CURVE figure from raw rows without these will produce a number that is close, wrong, and hard to explain.

Share links, QR downloads and colleague invites

Use create_share_link for the seven report/workflow share kinds and get_share_link for an exact owned token. Each returns qr_code.image_url, qr_code.download_url and qr_code.pdf_url. Links expire after 14 days and can be killed with revoke_share; get_share_link refuses expired/revoked links unless includeInactive:true is requested. Owner-list bearer material additionally requires owners:export consent; publishing reserves the full row count against the rolling export allowance. Use create_share_artifact/get_share_artifact for master_deed, curve_ai and condo_docs, whose existing share stores have no automatic expiry or revoke_share support. Document publication requires docs:read and an entitled market; Curve AI history must belong to the current API connection with no broader saved permissions. Use create_colleague_invite({market}) for a signup-enabled entitled market (Boston, Miami or New York) to get the stable reusable colleague URL and matching market-specific QR downloads; get_colleague_invite reads it without minting. list_markets returns artifacts.colleague_invite.available so agents can check support; demo markets return false and no invitation QR formats. Creating an invite sends no email; referral_program_enabled states whether rewards are active. REST twins are listed below. Share-email bodies accept recipients and the boolean include_referral_offer only; true is supported only for building reports.

Read each published schema for its field names

Field names on the core market-data, owners and documents payloads are snake_case on both surfaces — REST bodies and MCP tool results alike. Several of those payloads are CURVE's own internal records, and some of those are camelCase inside the product; the API renames them at its serialization boundary, which is why get_market_stats answers avg_price and not avgPrice, an owner row carries unit_id / held_years, a condo document carries doc_key / book_page, and a combo sale carries combo_display. The CMA comparables envelope joined them: get_comps and the comps route answer algorithm_version, as_of_date, cutoff_date, eligible_count, verified_pool_count and generated_at. Two places do NOT follow that rule yet and are being converged: the computed ANALYTICS shapes — developer intelligence, the peer benchmark board, saved views, and the comparable ROWS nested inside a comps response (fitScore, matchBand, reasonCodes) — still publish their internal camelCase field names, and a handful of MCP tool ARGUMENTS are camelCase (docKey, unitId, widgetType). For those, read the schema: the OpenAPI document for a REST shape, each tool's own input schema for an argument.

Medians are trailing-12-month, and separate from all-time counts

A building's or market's headline medianPrice / medianPsf is computed over the trailing 12 months of qualifying sales, while sale counts and totals in the same payload are all-time. They answer different questions on purpose: "what is this trading at now" versus "how much has ever traded here". A median over a window with too few sales is still reported — check the accompanying count before quoting it.

Gain, loss and flat are three buckets, not two

gain_loss_pct is a sale's price against the same unit's prior recorded sale. Every gain/loss computation across CURVE buckets it three ways: gain is > +1%, loss is < −1%, and anything within ±1% inclusive is FLAT — neither. If you re-bucket on the raw field with a simple > 0 test your gain rate will not match CURVE's, and the gap is exactly the flat band. gain_loss_pct is null when there is no prior sale to compare against.

Affordable-restricted sales are excluded from market-rate analytics

A sale carrying is_affordable_sale: true is under an affordable-housing price restriction (affordable_restriction_source says how that was inferred). Those rows are excluded from every market-rate calculation — averages, medians, gain/loss rates and any gain basis — because a restricted price is not a market price. They are still RETURNED on the sales endpoints: the flag is on the row so you can include or exclude them deliberately, and the default analytics answer excludes them.

Financing coverage is per-market, and absence is stated rather than guessed

financing_status / has_mortgage describe whether a purchase was cash-like or mortgage-financed, derived from the recorded instruments. Coverage exists today in Boston, Austin. In Miami, Atlanta, New York, San Francisco, Los Angeles the registry feed does not support it, so financing filters are suppressed and the cash_vs_mortgage compute key answers {"error":"not_available_for_market"} rather than returning an empty or half-populated breakdown. A sale whose instruments are ambiguous is classed "Unknown", and the Unknown group is always returned — including at zero count — so absence is never inferred from a missing key.

Not-found and not-entitled are the same answer

An unknown market id and a real market your account is not entitled to both return an identical 404 not_found. The same holds for another user's share, embed, tracker or MLS job. This is deliberate: an error that distinguishes the two is an existence oracle. Do not branch on 404 to infer that something exists.

Every price is a recorded price

CURVE publishes no automated valuations, asking prices or listing estimates. A sale_price is a price a unit actually recorded at in the public registry, reconciled to the building and unit. Nominal and non-arm's-length transfers are classified and separated so a $1 family transfer never lands in a median.

MLS & TAN (retired)

  • CURVE retired its MLS PIN and Top Agent Network connections on October 22, 2026. Every /v1/mls/* and /v1/tan/* route returns 410 mls_connection_retired, the MLS and TAN MCP tools were removed, and /v1/ask never reads listing data. The mls:read scope is no longer offered; older tokens that carry it still work for every other scope they hold.

Signed webhooks

Connect recorded property activity and your CURVE workflows to your own systems. Start with one destination and a precise trigger, verify the raw-body signature, then accept work durably before responding.

Create a destination · workflow:write
curl -s "https://curvereports.com/api/v1/webhooks" \
  -H "Authorization: Bearer $CURVE_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"name":"My receiver","url":"https://hooks.example.com/curve","trigger":{"eventType":"share.viewed","conditions":{"shareKinds":["report","cma"]}}}'
EventScope and filtersEvent data
sale.recorded

A qualifying sale is added to selected buildings.

Selected market and canonical buildings.

minPrice, maxPrice, minPsf, maxPsf, bedrooms, unitContains, developerOnly, cashOnly

market, canonical building, sale (id, unit, sale_date, price, price_per_sqft, sale_type, developer_sale, financing_status), curve_url
record.recorded

A sale, transfer, financing or other registry record is added.

Selected market and canonical buildings.

minPrice, maxPrice, unitContains, recordFamilies

market, canonical building, record (id, unit, event_date, family, type, label, recorded_price, financing_status), curve_url
mortgage.recorded

A qualifying mortgage or financing record is added.

Selected market and canonical buildings.

minPrice, maxPrice, unitContains

Same record shape; mortgage/financing records only. Requires verified financing coverage.
building.metric.changed

A selected building crosses a pricing or activity threshold.

Selected market and canonical buildings.

metric, direction, minChangePercent, minValue, maxValue

market, canonical building, metric, previous, current, dataset_version, curve_url
share.viewed

Someone opens a report, Market Analysis, Developer Analysis or CMA you shared.

Your own activity.

shareKinds

share (type, title, recipient_email), curve_url. View identities and destination URLs are omitted.
building.request.completed

A building you requested is marked complete.

Your own activity.

No condition filters.

request (id, market, query, status), curve_url. Internal resolution notes are omitted.

Verify the original request bytes

Curve-Signature uses t=timestamp,v1=hex_digest. The HMAC-SHA256 input is the timestamp, a period and the unmodified raw body. Reject signatures older than five minutes, verify with constant-time comparison, and deduplicate the stable event ID.

Node.js · raw-body signature verification
import { createHmac, timingSafeEqual } from "node:crypto";

// Pass the original raw request bytes, before any JSON parsing.
export function verifyCurveSignature(rawBody, signatureHeader, secret) {
  if (typeof signatureHeader !== "string") return false;
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/i.exec(signatureHeader);
  if (!match) return false;
  const timestamp = Number(match[1]);
  if (!Number.isSafeInteger(timestamp) ||
      Math.abs(Date.now() / 1000 - timestamp) > 300) return false;
  const expected = createHmac("sha256", secret)
    .update(match[1] + ".").update(rawBody).digest();
  const supplied = Buffer.from(match[2], "hex");
  return supplied.length === expected.length &&
    timingSafeEqual(supplied, expected);
}
// Reject invalid signatures. Atomically deduplicate event.id and persist
// accepted work before returning 2xx; perform slow work asynchronously.

Delivery, recovery and access

  • Create destinations in Account → API & Connections, or POST /v1/webhooks with workflow:write. GET /v1/webhooks and delivery history require workflow:read and never return destination URLs or signing secrets. The signing secret is shown once at creation and rotation; store it securely.
  • A paid subscription or paid team seat is required. Suspended accounts and accounts requiring a password reset cannot operate webhooks. Current paid and event-market access is rechecked at dispatch; queued events with revoked access become dead with access_revoked and are never sent. A transient access lookup failure remains retryable.
  • Destinations must be publicly reachable HTTPS. CURVE rejects private and mixed public/private DNS answers, pins a validated address while retaining normal TLS hostname verification, and does not follow redirects. DNS resolution is bounded to 3 seconds; resolution plus sending shares an 8-second budget. Return a 2xx after durably accepting the event; process it asynchronously.
  • Delivery is at least once. Deduplicate on body.id or Curve-Event-Id in your own durable store. Global ordering and exactly-once side effects are not guaranteed. A response lost after your server accepted an event can cause a retry. Curve-Event-Type matches body.type; api_version is 2026-08-27.
  • The scheduler runs every 5 minutes, with up to 30 active rules and 20 due deliveries claimed per pass. Failed sends retry after 1, 5, 30, 120 and 480 minutes, plus scheduling and queue lag. Six failed attempts make the delivery dead; 20 consecutive destination failures pause the destination. Destination tests affect health but are immediate and are not automatically retried.
  • GET /v1/webhooks/{id}/deliveries exposes pending, delivering, succeeded, failed and dead status, attempt counts, response codes and next attempt times. POST .../deliveries/{deliveryId}/retry explicitly requeues a failed or dead delivery with its original event id and a fresh six-attempt budget; resume a paused destination separately. Replay can repeat work at the receiver, so keep deduplication enabled.
  • New rules begin at creation; replacing a trigger establishes a fresh baseline. Existing listings and metrics become the baseline and are not backfilled. Sales and records created after the baseline are checked against a durable event ledger, including facts published after an earlier poll. Facts created before the baseline are not historical backfill. Snapshot events describe observed changes; multiple changes between polls may collapse into one observed transition.
  • Pausing a destination stops evaluation and dispatch while preserving rules and queued history. Resume preserves the baseline. Replacing a trigger, including a full configuration update with status, establishes a new baseline. Deleting a destination or trigger cascades to its events and delivery history.
  • Scoped rules select up to 25 buildings by matching catalog id and slug; CURVE supplies the canonical name. Cash filters and mortgage events require verified financing coverage. Unrecognized or inapplicable filters are refused rather than ignored. Missing bedroom/price data does not match a requested numerical filter.
  • Rotation replaces the stored secret immediately. Requests already in flight may still carry the previous signature; subsequent attempts use the new secret. Coordinate rotation with your receiver, retain both secrets briefly for in-flight verification, then retire the old secret. Service-role encryption-key rotation requires an operator re-encryption procedure.

Errors

Every non-2xx body is {error, message?}. Branch on error — it is the stable machine-readable code; message is human-facing prose and may change. Per-endpoint codes (owner_list_access_required, owner_export_quota_exceeded, embed_upgrade_required, market_access_required, building_filter_required, render_failed and the rest) are documented on the endpoint that raises them, in the endpoint reference and in the OpenAPI document. Every 429 carries retry_after_seconds in the body and a Retry-After header, whichever ledger it came from — so you can back off uniformly without branching on the code first.

  • Authenticated REST responses carry a server-generated X-Request-Id, including refusals and errors. Keep it when reporting a problem; an incoming request id is not trusted. Browser clients can read it through CORS.
  • POST, PATCH and PUT JSON bodies are limited to 1,048,576 UTF-8 bytes and 10 seconds. Nonempty bodies must be objects. Operations marked requestBodyOptional also accept an absent or empty body.
  • Use the operation's x-curve-scopes and x-curve-quota-class in OpenAPI to discover authorization and metering. Request the minimum scopes you need; workflow:write is not granted by an omitted OAuth scope.
StatusCodeWhat it means
400invalid_requestThe JSON body is malformed, is not an object, or does not match this operation's configuration.
408request_timeoutThe JSON write body did not finish within 10 seconds.
413payload_too_largeThe JSON write body exceeds 1,048,576 UTF-8 bytes (1 MiB), including streamed bytes regardless of Content-Length.
401invalid_tokenMissing, malformed, revoked, expired, or audience-mismatched bearer token. The WWW-Authenticate header carries the RFC 9728 resource_metadata pointer that starts OAuth discovery.
403api_requires_paid_planThe token is valid but the account has no paid CURVE plan or team seat. Personal access tokens need a paid plan; the Claude and ChatGPT connector also works on CURVE Free.
403plan_upgrade_requiredThe account's plan does not include API and MCP access (CURVE Social). The API comes with CURVE Data and Data + Social.
403insufficient_scopeThe token is missing a required scope. The message names the missing ones and WWW-Authenticate repeats the required set.
403account_suspendedThe account is suspended. Tokens stop working immediately.
403password_reset_requiredThe account must reset its password in the web app before its tokens work again.
404not_foundThe resource does not exist, or exists and is not yours / not entitled. Identical either way, deliberately.
410mls_connection_retiredThe MLS PIN and Top Agent Network connections were retired on October 22, 2026. Nothing to retry.
429ai_allowance_exhaustedOn /v1/ask and ask_curve only: this month's CURVE AI answers are used up. Each answer counts against the same monthly allowance the product's Ask AI uses; the body carries reset_at, the next billing date.
429rate_limitedA quota class is exhausted, or — on /v1/ask and ask_curve only — CURVE's platform-wide daily AI spend cap has been reached, which the message names and which resets at 00:00 UTC. Either way the body carries retry_after_seconds and the Retry-After header repeats it. No partial result is returned.

Quotas

Metered per account, per quota class, in UTC windows. Owner accounts are unmetered. These are the launch defaults for each plan.

Quota classData / dayData / minData + Social / dayData + Social / minOn counter failureEndpoints
general10,0006050,000300serves (fail-open)53
ask25—200—refuses (fail-closed)1
mls_live10—40—refuses (fail-closed)2
dataset_chunks200—2,000—refuses (fail-closed)1
workflow_write120—600—refuses (fail-closed)30
owners_read300—1,500—refuses (fail-closed)2
owners_export30—120—refuses (fail-closed)1
share_email1,000—2,000—refuses (fail-closed)1
reports_generate30—120—refuses (fail-closed)1
  • Windows are UTC. Every metered response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (epoch seconds) for the day window; a 429 adds Retry-After.
  • fail mode closed means that if CURVE cannot count your usage, the request is refused rather than served. general is the only fail-open class — a read that is very occasionally over-served is a better failure than a platform outage. Everything that touches personal data, writes, spends money or calls a third party fails closed.
  • GET /v1/usage reports your live counters and your plan's limits, including any environment override in effect. Read it rather than hardcoding the numbers on this page.
  • Some endpoints sit behind a SECOND, tighter ledger that is the real binding limit — owner exports against the account's rolling 24h export ledger, share emails against the platform's hourly send limiter. The quota class above those is an outer circuit breaker, not the number you will hit first.

Changelog

v1 is stable: fields are added, never removed or repurposed, and a breaking change would ship as a new version prefix.

2026-09-29
Share artifacts, exact QR targets and reusable colleague invites
  • Added get_share_link with active/expired/revoked status, create_colleague_invite and get_colleague_invite with market-specific reusable links, plus create_share_artifact/get_share_artifact for recorded documents and saved Curve AI/Condo Docs conversations. REST twins are published in OpenAPI.
  • Every supported share creation returns branded PNG, PNG download and printable PDF QR URLs. Invite QR downloads preserve the selected market; QR targets preserve navigation fragments. QR generation validates actual streamed body size and malformed inputs.
  • Owner-list URLs are full-data bearer credentials: publishing requires explicit owners:export consent, a full building unlock and an atomic rolling export reservation. List responses redact owner-list tokens/URLs/QR artifacts without that consent; exact lookup and email refuse insufficient_scope.
  • Curve AI publication and lookup preserve connection and permission-history isolation. Product chats, another connection's chats and broader-scope histories cannot be published through a narrower API connection.
  • Report/unit/analysis/developer/CMA/owner-list/Daily Bulletin links expire exactly 14 days after the persisted creation timestamp and support revoke_share. Share creation and lookup return the same expires_at, including when publication takes time. Document and saved-conversation share families currently have no automatic expiry or revoke_share support; their responses explicitly return expires_at:null and revocation_supported:false. Colleague invites stay reusable until disabled and never send email when created.
  • Share email inputs are closed: custom message fields are refused. Referral offers are supported only for building-report emails; requesting an offer for another kind is refused before sending.
2026-09-28
Webhook management API and integration reliability
  • Published destination, trigger, test, rotation, delivery-history and replay operations under existing workflow scopes.
  • Added server request IDs and bounded JSON request bodies, with documented 408 and 413 refusals.
  • Added fenced evaluation and delivery claims, durable fact replay, listing revisions and complete listing pagination.
  • Published event/filter contracts, signature verification, retry schedule, access revocation, baseline and rotation behavior.
2026-09-27
MCP security and reliability
  • OAuth disconnect and permission reductions are enforced against the current grant on every request. Approval shows the requested access and callback destination, with a Cancel action.
  • Nested AI tools retain API quotas. Rejected MCP dispatches consume the base request budget, and tool failures are recorded separately from HTTP status.
  • Owner export reservations are atomic across web, REST and MCP. Read-only MCP lookups no longer create building-addition requests.
  • API conversations are isolated by connection and permission history. OAuth refresh preserves continuation; older or broader conversations require a new thread.
2026-08-14
MCP tools ask for confirmation only where it is warranted
  • Every tool now advertises all four MCP annotations rather than readOnlyHint alone. destructiveHint defaults to true in the spec whenever readOnlyHint is false, so every write was being presented to clients as destructive — including the ones that only add a row. Adding a share link, an embed, a tracker search, a saved view, a CMA sheet, a unit follow or a building pin now declares destructiveHint false; revoke_share, send_share_email and refresh_mls keep the destructive stance.
  • search_mls, generate_report and export_owner_list are annotated read-only: they read (the MLS, a cached render, a building already unlocked) and change nothing in the account's data. Their quota classes are unchanged — an expensive call is rationed by its ledger, not by a confirmation prompt.
  • MCP only: get_owner_list no longer takes a claim argument and can never spend an included-building slot, so it is a pure read; a preview result now carries unlock_hint (in place of claim_hint) naming the tool that unlocks. The new unlock_owner_list tool is where the permanent unlock lives, and it returns the full list for the building it unlocks. The REST route is unchanged — GET /v1/markets/{market}/buildings/{slug}/owners still takes ?claim=true and still answers claim_hint.
  • No scope or entitlement changed. owners:read, owners:export and the fail-closed owner-list gate behave exactly as before.
2026-08-14
Field names are snake_case everywhere (breaking)
  • Core market-data, owners and documents fields that still carried CURVE's internal camelCase are now snake_case on REST and MCP alike: get_market_stats (avg_price, avg_ppsf, cash_share, prior_coverage, latest_sale, comparable_count, financing_known_count, same_owner, non_arms), the owner list and unit owner payloads (building_name, total_rows, portfolio_available, typical_hold, hold_verdict, deed_chain, beneficial_owners, entity_resolution and every owner row field), condo documents (doc_key, book_page, document_type, page_count, page_number and the extraction summary), building completeness (sales_complete, closed_sale_row_count, expected_sale_count), the owner CSV export result, and a sale's combo_display / timeline_display.
  • Report polling now advertises a realistic retry_after_ms: a cold render measured 115 seconds, so the previous 1.8s hint invited about 64 pointless polls.
  • Conditional requests are evaluated after request validation, so a malformed request answers 400 with the code that names the problem instead of an empty 304.
  • The two 429s that were missing it — owner_export_quota_exceeded and share_email_rate_limited — now carry retry_after_seconds like every other rate-limit body.
2026-08-13
MLS, Curve AI, and public documentation
  • Added /v1/mls/* — connection status, saved workspace, live search, refresh and job polling — behind the new mls:read scope and the account's live-MLS lock.
  • Added POST /v1/ask: the CURVE product's grounded, cited answer pipeline over HTTP, behind ai:ask. It obeys the same platform-wide daily AI spend cap the product's own chat does.
  • Added the matching MCP tools, this documentation page, and /llms.txt.
2026-08-13
OAuth 2.1 and one-click connect
  • Added OAuth 2.1 with PKCE, dynamic client registration, client ID metadata documents, and the RFC 8414 / RFC 9728 discovery documents, so an MCP client can connect without a token being copied by hand.
  • Added the consent screen and the Connected apps panel, where any authorization can be revoked.
  • Rate-limit responses now carry retry_after_seconds in the body, not only in the Retry-After header.
2026-08-13
MCP server
  • Added the Streamable HTTP MCP server at /api/mcp, on the same verifier, scopes and quota classes as REST.
2026-08-12
Documents, owners, CMA, workflow
  • Added condo documents and their OCR'd page text, owner-of-record lists and CSV export, CMA comparables and sheets.
  • Added shares, share emails and engagement, embeds, trackers, unit follows, building pins and branded report PDFs.
2026-08-12
Data, analytics and developer intelligence
  • Added buildings, sales, units, registry events, rankings, the Daily Bulletin, dataset manifests and chunk downloads.
  • Added the analytics query engine and saved views, and per-building / market-wide developer intelligence.
2026-08-11
v1 foundations
  • Personal access tokens, the single bearer verifier, scopes, per-plan quota classes, the response envelope and the OpenAPI document at /api/v1/openapi.json.

Machine-readable index for agents: /llms.txt. Data sourcing and reconciliation: how CURVE sources condo data.

Get a token

API access comes with CURVE Data and Data + Social, your own plan or a team seat on one. Mint a personal access token in Account → API & Connections, or connect an AI assistant with one click.

Open API & Connections