canonical: https://jentic.com/apis/ruuster.com/ruuster

# Ruuster API

The Ruuster API reports engagement on a real estate brokerage's Ruuster-powered sites: who viewed which listings, which leads are active, how agents and emails perform, and how much traffic each site gets. Listings can be looked up by MLS number with their engagement and viewers, leads can be found by email, phone, or CRM id with their activity and emails, and a brokerage summary rolls it up by period. Beyond the read-only reporting, webhook subscriptions push lead events, an event feed can be polled, and a CMA endpoint runs comparative market analyses from a listing or address.

## For AI agents

Read listing engagement, lead activity, agent, email, and traffic stats for a brokerage's Ruuster sites, subscribe to lead-event webhooks, and run CMAs on a property.

## Scope

Does not edit MLS listings, send marketing emails, or act as the brokerage's CRM. Use for reading engagement on Ruuster-powered brokerage sites, lead-event webhooks, and CMAs only.

## Capabilities

- Look up a listing by mlsRecordId and read its engagement and the viewers who looked at it
- Find a lead by email, phone, or crmExternalId and pull its activity timeline and emails
- List the most active leads in a date range with a minActions threshold
- Report new-lead stats, email stats, and website traffic grouped by period or hostname
- Run a comparative market analysis with POST /cma using a propertyId, mlsRecordId, or address
- Subscribe to lead events with webhooks, list deliveries, and replay failed ones
- Poll the event feed by kinds and since for systems that cannot receive webhooks

## Use cases

### Agent follow-up assistant through Jentic

A brokerage wants an AI assistant that tells agents who to call today. Through Jentic the assistant searches for 'list active leads', receives the Ruuster operation with its input schema, and calls GET `/leads/activity` with from, to, and minActions. For each hot lead it calls GET `/leads/{leadId}/activity` to see which listings they viewed, then drafts a follow-up note for the assigned agent.

Example prompt: Call GET `/leads/activity` with from '2026-11-12', to '2026-11-19', and minActions 5, then call GET `/leads/{leadId}/activity` for the top five leads and summarise the listings each one viewed

### Listing engagement reports for sellers

Listing agents send sellers proof that the listing is getting attention. GET `/properties/lookup` finds the listing by mlsRecordId, GET `/properties/{propertyId}/engagement` returns engagement over a period with a granularity setting, and GET `/properties/{propertyId}/viewers` lists who viewed it. GET `/properties/engagement` compares engagement across all listings.

Example prompt: Call GET `/properties/lookup` with mlsRecordId '24-118842', then GET `/properties/{propertyId}/engagement` with from and to for the last 14 days and granularity 'day', and write a short seller update

### Comparative market analysis

Before a listing appointment an agent needs comps. POST /cma takes the subject as subject.propertyId, subject.mlsRecordId, or subject.address, accepts overrides for facts like bedrooms, livingArea, and condition, and options such as options.radiusMiles and options.soldWithinMonths. GET `/cma/{cmaId}` retrieves the finished analysis and GET /cma lists past ones.

Example prompt: Call POST /cma with subject.mlsRecordId '24-118842', overrides bedrooms 4, and options.radiusMiles 1, then call GET `/cma/{cmaId}` and summarise the comparable sales it returns

### Lead-event sync into a CRM

Brokerages push Ruuster lead events into their CRM. POST /webhooks creates a subscription with a url and the events to send, from the kinds listed by GET `/webhooks/events.` GET `/webhooks/{webhookId}/deliveries` shows delivery status and POST `/webhooks/{webhookId}/replay` resends events between from and to, optionally onlyFailed. GET /events offers a polling alternative.

Example prompt: Call GET `/webhooks/events`, then POST /webhooks with url 'https://example.com/ruuster' and the lead event kinds, and later call POST `/webhooks/{webhookId}/replay` with from, to, and onlyFailed true

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/leads/activity` | List active leads |
| GET | `/leads/{leadId}/activity` | Get a lead's activity |
| GET | `/leads/lookup` | Find a lead |
| GET | `/properties/{propertyId}/engagement` | Get listing engagement |
| GET | `/properties/{propertyId}/viewers` | List a listing's viewers |
| GET | `/summary` | Get the brokerage summary |
| POST | `/cma` | Run a CMA |
| POST | `/webhooks` | Create a webhook subscription |

## Key resources

- **Listings** — List and look up listings by MLS number, with per-listing and bulk engagement and viewer lists
- **Leads** — List, find, and rank active leads, with activity timelines, emails, and new-lead stats
- **Agents and summary** — Brokerage agents and a summary of engagement by period
- **Email and traffic** — Email stats and website traffic grouped by period or hostname
- **Webhooks and events** — Subscriptions with test, secret rotation, deliveries, and replay, plus a pollable event feed
- **CMA and rates** — Comparative market analyses on a subject property and mortgage rate series

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 57 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 89 / 100
  - Developer Experience & Jentic Compatibility: 71 / 100
  - AI-Readiness & Agent Experience: 33 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 78 / 100
- **View full report:** https://jentic.com/apis/ruuster.com/ruuster/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Ruuster by hand means sending two headers together, x-api-key and x-email, from a server, and paging cursor-based lead and listing lists. Through Jentic you install once, import Ruuster from the API Directory, store the key and email once, and your agent calls it.
- **Permission scoping:** Ruuster puts the listing, lead, and webhook ids in the URL path (`/properties/{propertyId}`, `/leads/{leadId}`, `/webhooks/{webhookId}`), so a rule can bound your agent to the operations and ids you pick. You choose the operations it may call, so ones like deleting a webhook or rotating its signing secret are not included unless you add them.
- **Credential handling:** Your Ruuster key and login email are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list active leads' or 'get listing engagement', and Jentic returns the matching Ruuster operation with its input schema so the agent calls the right endpoint without reading the docs.

## Related APIs

- **Lofty Service Open APIs** — Real estate CRM with leads, contacts, and transactions
- **ATTOM Property API** — Property records, sales history, and valuation data
- **RentCast API** — Property records, rent estimates, and value estimates
- **Plausible API** — Privacy-focused website traffic analytics

## FAQ

### What authentication does the Ruuster API use?

The Ruuster API declares two apiKey schemes in its OpenAPI spec that are required together: apiKey, sent in the `x-api-key` header, and email, sent in the `x-email` header with the Ruuster login email the key belongs to. The key must belong to a brokerage owner or admin and is meant for server use. GET /status needs no auth. Through Jentic both values are held by your own Jentic One instance and attached at call time.

### Can I run a comparative market analysis with the Ruuster API?

Yes. POST /cma runs a CMA for a subject given as subject.propertyId, subject.mlsRecordId, or subject.address. You can pass overrides for facts such as bedrooms, bathrooms, livingArea, and condition, and options such as options.radiusMiles and options.soldWithinMonths. GET `/cma/{cmaId}` returns the result and GET /cma lists past analyses.

### What are the rate limits for the Ruuster API?

The OpenAPI spec does not specify rate limits. Check the Ruuster API documentation at https://help.ruuster.com/api for current limits.

### How do I find a lead's recent activity through Jentic?

Search Jentic for 'find a lead', load GET `/leads/lookup`, and execute it with the lead's email, phone, or crmExternalId. Then call GET `/leads/{leadId}/activity` with from and to to see the listings and emails they engaged with. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a Ruuster MCP server?

You don't need an MCP server to give your agent Ruuster. Jentic connects it directly from the API Directory: import it, store your key and login email once, and your agent finds the lead, listing, and CMA operations it needs on demand, without loading extra tool definitions into its context.

### Can I limit what my agent is allowed to do with the Ruuster API?

Yes. For a reporting assistant, write a rule that allows only GET `/leads/activity`, GET `/leads/{leadId}/activity`, and GET /summary. The agent can rank leads and read the brokerage summary but cannot create or delete webhooks, rotate signing secrets, or run CMAs, and each call it makes is logged.
