# Mainview API

Real estate platform API for agents and agentic LLMs.

Base URL: `https://api.mainview.com`


## What You Can Do

- Find active homes for a buyer by location, price, property type, and features.
- Pull recent closed sales for comps and market research.
- Manage the agent's own custom listings, contacts, sites, and marketing assets.


## Terminology

- `PAT` -- Long-lived, scope-gated personal access token tied to one user and one account membership.
- `account-scoped` -- Data or behavior restricted to the active account.
- `active account` -- The account the current PAT is scoped to. Provides tenant scoping.
- `active user` -- The user the current PAT is scoped to.
- `assignment` -- A record that associates one resource with another.
- `city` -- A city resource, usually the postal city. Resource: `city`
- `custom listing` -- An agent-owned custom-listing record. May extend an mls listing. Resource: `custom-listing`
- `listing` -- An MLS-backed listing record. Resource: `listing`
- `method` -- Uniquely named, callable API operation within a service.
- `model` -- The field definitions for one type of API record.
- `place` -- A named geographic place such as a neighborhood, building, development, or subdivision. Resource: `place`
- `professional` -- Public facing agent or broker profile. Resource: `professional`.
- `property` -- Physical real property carrying a county parcel number: homes, land, condo units, and the like.
- `public-realm` -- Shared platform data not owned by one account.
- `record` -- One instance of a specific resource data object.
- `resource` -- A type of data managed through the API.
- `service` -- A group of API methods that operate within a resource or domain.
- `site` -- A tenant-owned website served by Mainview. Resource: `site`
- `trash` -- A soft-delete, removal of a record from normal use; reversible with `restore`.


## Auth

- Apps like ChatGPT and Claude connect through OAuth. The user signs in on the identity host and taps Approve, and the app never sees a password or a PAT.
- OAuth sign-in and approval happen at `https://accounts.mainview.com`, the authorization server.
- An agent connected through OAuth already holds its credential, so never ask the user to paste a PAT or a password into chat.
- A script or integration the user set up sends a PAT: `X-API-Key: mvx_<rest-of-key>`, or `Authorization: Bearer mvx_<rest-of-key>`.
- PATs are issued by an account owner at Settings > API Tokens (`/settings/api-tokens`).
- A first-party JWT is for browser sessions only.
- Only this page, `/llms.txt`, and `GET /health` are public. All data and deeper docs require a credential.
- A missing, invalid, revoked, or expired key returns HTTP `401` with error code `UNAUTHORIZED`.
- `public-realm` and public IDX describe who owns the data, not anonymous access. Reading it still requires a credential.
- Full guide: `/docs/auth`


## Agent Workflow

For an unfamiliar task:

1. Call `GET /api/auth-service/get-agent-instructions` and follow it: ground rules, and who you are working for.
2. Choose the relevant service from this page or `GET /docs/services`.
3. Read `GET /docs/services/{slug}` for available methods.
4. Read `GET /docs/methods/{name}` before calling an unfamiliar method.
5. Read `GET /docs/models/{name}` only when exact field-level schema is needed.
6. Execute the API call.

Do not guess parameter names, field names, enum values, or method behavior when the relevant docs are available.


## Discovery and Docs

- `GET /docs` -- This overview.
- `GET /api/auth-service/get-agent-instructions` -- How to work for this user, and who they are.
- `GET /api/auth-service/whoami` -- Authenticated identity and account access.
- `GET /docs/services` -- List services.
- `GET /docs/services/{slug}` -- One service's purpose, methods, and model pointer.
- `GET /docs/methods/{name}` -- One method's parameters and examples.
- `GET /docs/models/{name}` -- Full field schema for a model. Read only when field-level detail is needed.
- `GET /docs/filtering` -- Filtering.
- `GET /docs/sorting` -- Sorting.


## Concept Guides

- `GET /docs/concepts/listings` -- MLS listings vs the agent's own custom listings.
- `GET /docs/concepts/contacts-crm` -- How to record what an agent says about a contact. Read before writing contacts.
- `GET /docs/concepts/professional-sites` -- How to build and edit a real estate agent or team's website: settings, pages, page sections, professionals, and more. Read before writing sites or professionals.


## Request Conventions and Standard Methods

URL pattern: `/api/<resource>-service/<verb-noun>[/{id}]`

- `GET get-*` -- Fetch one record by id.
- `GET list-*` -- List records with filters, search, and paging.
- `POST create-*` -- Create a record.
- `PATCH update-*` -- Partial-merge update.
- `PUT replace-*` -- Full replacement.
- `POST trash-*` -- Soft-delete. Reversible.
- `POST restore-*` -- Restore from trash.
- `DELETE delete-*` -- Permanent destroy.


## Request Tips

- Custom reads use `GET`.
- Custom actions use `POST`.
- Account-scoped services are always scoped to the token's account.
- To act on a different account, use a token issued for that account.
- Null values are omitted for PAT/Bearer callers by default. Use `?omitNulls=false` to retain them.


## Guide: MLS listings vs custom listings vs properties

- `listing-service` is for public IDX listings, a read-only mirror of local MLS listings (millions of rows).
- `custom-listing-service` is for the active account's own custom listing rows (dozens to hundreds of rows).
- `property-service` is a read-only surface for the underlying properties, which may or may not be listings.
- Disambiguate when the caller has not made clear which of the three they are asking for.

### `listing-service`

- For published active, pending, and closed MLS listings from all brokers and agents.
- Includes read-only copies of the active account's own MLS-published listings.
- For general "find homes" and "show me listings" requests.
- For sale records, pendings, comps, and other listing market research.

### `custom-listing-service`

- For the active account's own custom listings, which it can write to.
- Custom listings often augment MLS listings where the active account is the listing agent.
- A custom listing may exist before any public MLS listing goes live.
- Custom listings support higher-resolution photos (assets) and full control over their use on the account owner's site and marketing material.
- For "show me my current custom listings".

### `property-service`

- For the underlying properties layer, usually sourced from county assessor data.
- Read-only, and rarely used by real estate agents outside farming and research.
- For "how many properties are there in <neighborhood>".


## Guide: MLS listings search

- `list-listings` does not accept a generic `q` parameter. To search listing remarks text, use `publicRemarksQ`.
- Use `placeNameQ` to search listings by neighborhood, condo complex, building, or development.
- For example: `GET /api/listing-service/list-listings?placeNameQ=Madison Park`
- Do not call `list-places` first unless you need to inspect or disambiguate multiple place matches yourself.
- A resolved place is returned in `meta.resolvedLocation`. Reuse its `id` as `placeId` on later calls to skip name resolution.

### Other listing location filters

- `locationNameQ` -- Any location string. The server resolves place vs city vs county vs ZIP.
- `cityName` -- City.
- `postalCode` -- ZIP code.
- `countyName` -- County.
- `addressQ` -- Street or address fragment.

### Sales status

- Use `salesStatusesAny`, a comma-separated list of the exact `sales_status` tokens you want.
- Casual "for sale" is three statuses: `salesStatusesAny=coming_soon,for_sale,contingent`
- Strictly for sale, excluding coming-soon and contingent, is `salesStatusesAny=for_sale`
- Sold comps are `salesStatusesAny=closed`, narrowed by `closedWithinDays`.
- `pending` is broad and matches every pending sub-status; `coming_soon` covers the pre-market set.
- No token stands for a group of different statuses, so always name each status you want.


## Total Counts

- Pass `includeTotal=true` when a total is needed; it comes back as `meta.totalCount`.
- Do not request a total unless it is truly needed, because counting is slow on large tables.


## Sorting

- Canonical: `sort=<field>_<asc|desc>` with a snake_case field, for example `sort=created_at_desc`.
- Also accepted: `sortBy=created_at&sortDir=desc`.
- Per-resource sort values are listed on `/docs/methods/{name}` for each `list-*` method.


## Response Envelopes

List:

```json
{
  "data": [],
  "meta": {
    "fetchedCount": 0,
    "limit": 0,
    "offset": 0,
    "totalCount": 0
  }
}
```

`meta.totalCount` is absent unless requested with `includeTotal=true`.

Single:

```json
{
  "data": {}
}
```

Error:

```json
{
  "error": {
    "code": "...",
    "message": "..."
  }
}
```


## Services

Service names and descriptions are public here, but their detailed docs and methods require a credential.

- `/docs/services/asset-service` -- Metadata for files uploaded to S3. (account-scoped)
- `/docs/services/asset-tag-assignment-service` -- Links tags to uploaded assets. (account-scoped)
- `/docs/services/asset-tag-service` -- User-defined tags for organizing assets. (account-scoped)
- `/docs/services/auth-service` -- Identity, session, and account discovery for the authenticated caller
- `/docs/services/business-service` -- Home builders and other industry businesses. (account-scoped)
- `/docs/services/city-service` -- Canonical cities with boundaries.
- `/docs/services/contact-service` -- CRM contacts: people, households, and companies. (account-scoped)
- `/docs/services/contact-tag-assignment-service` -- Links contacts to contact tags. (account-scoped)
- `/docs/services/contact-tag-service` -- Hand-curated contact tags. (account-scoped)
- `/docs/services/county-service` -- Canonical counties with boundaries.
- `/docs/services/custom-listing-service` -- An agent's own non-MLS listings. (account-scoped)
- `/docs/services/deal-service` -- Real estate transactions an agent is working. (account-scoped)
- `/docs/services/email-service` -- Transactional email send via SES (account-scoped)
- `/docs/services/listing-service` -- Canonical MLS listing records.
- `/docs/services/open-house-service` -- Scheduled open houses for listings. (account-scoped)
- `/docs/services/page-section-service` -- Content sections that make up a page. (account-scoped)
- `/docs/services/page-service` -- Editable pages within a site. (account-scoped)
- `/docs/services/place-label-assignment-service` -- Platform-defined labels, like favorite, on places. (account-scoped)
- `/docs/services/place-service` -- Neighborhoods, condo buildings, and developments, not cities or ZIPs. (account-scoped)
- `/docs/services/postal-code-service` -- ZIP codes with boundaries.
- `/docs/services/professional-service` -- Public profiles for agents and brokers. (account-scoped)
- `/docs/services/property-sale-service` -- Sale records for properties.
- `/docs/services/property-service` -- Physical parcels with assessor data, the layer beneath listings.
- `/docs/services/real-estate-label-assignment-service` -- Platform-defined labels, like favorite, on listings and homes. (account-scoped)
- `/docs/services/real-estate-tag-assignment-service` -- Links custom tags to listings and homes. (account-scoped)
- `/docs/services/real-estate-tag-service` -- User-defined tags for listings and homes. (account-scoped)
- `/docs/services/redirect-service` -- URL redirects for sites. (account-scoped)
- `/docs/services/saved-search-service` -- Saved listing searches. (account-scoped)
- `/docs/services/school-district-service` -- Public school districts with boundaries.
- `/docs/services/site-asset-assignment-service` -- Site chrome images: logos, favicon, and share image. (account-scoped)
- `/docs/services/site-city-assignment-service` -- A site's stance on one city: whether it covers it and whether it features it on /areas. (account-scoped)
- `/docs/services/site-domain-service` -- Hostnames routed to a site. (account-scoped)
- `/docs/services/site-footer-service` -- Footer config for sites. (account-scoped)
- `/docs/services/site-place-assignment-service` -- A site's stance on one place: whether it covers it and whether it features it on /areas. (account-scoped)
- `/docs/services/site-professional-assignment-service` -- Puts professionals on a site's roster. (account-scoped)
- `/docs/services/site-service` -- Tenant-owned websites. (account-scoped)
- `/docs/services/site-testimonial-assignment-service` -- Places testimonials on sites and pages. (account-scoped)
- `/docs/services/state-service` -- US states and territories.
- `/docs/services/submission-service` -- Form submissions from site visitors. (account-scoped)
- `/docs/services/testimonial-service` -- Client testimonials for agents. (account-scoped)

`/docs/services` -- Full service list and methods.


## Models

Do not load model schemas unless exact field-level detail is needed.

- `/docs/models` -- Full model list.
- `/docs/models/{name}` -- Individual model schema.


## Liveness

`GET /health`

No auth required.

Response:

```json
{
  "data": {
    "status": "ok",
    "platform": "api"
  }
}
```


## MCP

`https://mcp.mainview.com/docs` -- The same API surface, available over JSON-RPC.