API Reference

Rentalot provides a REST API for programmatic access to your account. Use it to sync properties from your PMS, build custom integrations, connect CRM tools, or let AI bots manage your rental operations.

Base URL

The API base URL is the configured server origin with /api/v1 appended:

https://rentalot.ai/api/v1

Free Trial access is available on the production origin while the account trial is active. Use https://rentalot.ai/api/v1 by default; an optional local development server can use http://localhost:3000/api/v1. Keep the same origin for web sign-in, Settings/key issuance, dashboard readback, and API requests.

Authentication

All API requests require an API key passed in the Authorization header:

Authorization: Bearer your_api_key_here

Generate and manage API keys from Settings > API Keys in your dashboard. See Authentication for details.

Optional first CRM job

This is the smallest useful account-scoped integration check: create a private property and contact, read and update them, verify the same IDs in the web CRM, then revoke the key. It does not publish a listing, upload images, send messages, or run a workflow.

1. Choose the server origin before deriving the API base URL. Use https://rentalot.ai for paid or Free Trial accounts. For optional local Free Trial testing, use a development server origin such as http://localhost:3000.

   export RENTALOT_API_ORIGIN=https://rentalot.ai
   # For a Free Trial, use instead:
   # export RENTALOT_API_ORIGIN=http://localhost:3000

   Keep this origin for web sign-in, Settings/key issuance, dashboard readback, and every API request.

2. Create an account, verify the email, and sign in at $RENTALOT_API_ORIGIN.

3. Open Settings > API Keys at $RENTALOT_API_ORIGIN/dash/settings?tab=api-keys, create a key, and save the raw value immediately. It is shown only once. For a local Free Trial, this is http://localhost:3000/dash/settings?tab=api-keys.

4. Derive the API base URL only after selecting the origin:

   export RENTALOT_API_KEY=ra_your_key
   export RENTALOT_API_BASE_URL="$RENTALOT_API_ORIGIN/api/v1"

   If you change RENTALOT_API_ORIGIN, derive RENTALOT_API_BASE_URL again before making requests. Do not mix a local trial key with the production origin, or vice versa.

5. Create a private property with the canonical required fields. Do not include images or the development-only propertyType field in the trial path:

   property_json=$(curl -sS "$RENTALOT_API_BASE_URL/properties" \
     -H "Authorization: Bearer $RENTALOT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "title": "Example Private Studio",
       "address": "123 Example Street",
       "city": "Austin",
       "state": "TX",
       "zip": "78701",
       "monthlyRent": 1800,
       "bedrooms": 0,
       "bathrooms": 1,
       "features": ["hardwood floors"],
       "isPublic": false
     }')
   PROPERTY_ID=$(printf '%s' "$property_json" | jq -r '.data.id')

6. Create a contact with an email or phone, then save its ID:

   contact_json=$(curl -sS "$RENTALOT_API_BASE_URL/contacts" \
     -H "Authorization: Bearer $RENTALOT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Ada Lovelace",
       "email": "ada@example.com",
       "role": "prospect",
       "source": "api"
     }')
   CONTACT_ID=$(printf '%s' "$contact_json" | jq -r '.data.id')

7. Read both records and update only canonical safe fields:

   curl -sS "$RENTALOT_API_BASE_URL/properties/$PROPERTY_ID" \
     -H "Authorization: Bearer $RENTALOT_API_KEY"
   curl -sS "$RENTALOT_API_BASE_URL/contacts/$CONTACT_ID" \
     -H "Authorization: Bearer $RENTALOT_API_KEY"
    
   curl -sS -X PATCH "$RENTALOT_API_BASE_URL/properties/$PROPERTY_ID" \
     -H "Authorization: Bearer $RENTALOT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"title":"Example Private Studio Updated","monthlyRent":1900}'
   curl -sS -X PATCH "$RENTALOT_API_BASE_URL/contacts/$CONTACT_ID" \
     -H "Authorization: Bearer $RENTALOT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"channelPreference":"email"}'

8. While signed in to the same account at $RENTALOT_API_ORIGIN, open $RENTALOT_API_ORIGIN/dash/properties/$PROPERTY_ID and $RENTALOT_API_ORIGIN/dash/contacts/$CONTACT_ID and confirm the dashboard shows the same IDs and updated values. For a local Free Trial, these resolve to http://localhost:3000/dash/properties/$PROPERTY_ID and http://localhost:3000/dash/contacts/$CONTACT_ID.

9. Revoke the key at $RENTALOT_API_ORIGIN/dash/settings?tab=api-keys. A subsequent request with that key must return 401 Unauthorized.

For an MCP-shaped version of this job, use the MCP setup guide. The current CLI can read the same IDs, but its property and contact write flags are drifted from the canonical API fields, so do not use CLI writes for this first job. See the CLI guide.

Endpoints

Properties

Property Images

Contacts

Contacts are also created automatically when prospects interact with your workflows.

Showings

Conversations

Read-only access for CRM sync and reporting.

Events

Read-only view of your full calendar (showings, synced Google Calendar events, Cal.com events).

Workflows

Messages

Drafts

Follow-ups

Sessions (Pre-Screening)

View and manage prospect submissions from public chat workflows.

Webhooks

Settings

Idempotency

POST endpoints that support idempotency accept an optional Idempotency-Key header. If a completed response for the same key and request body exists within 24 hours, you’ll get the cached response back with an X-Idempotent-Replayed: true header. This completion cache does not serialize concurrent first attempts, so it is not an exactly-once guarantee when two requests arrive before either response is stored.

Rate-limit accounting is charge-on-attempt. A failed request can consume quota, and replaying a cached response does not refund quota. Use idempotency keys for sequential retries, and do not rely on them to deduplicate concurrent first attempts.

Idempotency-Key: your-unique-key-here

Access by Plan

The API key determines the account and tier. Do not infer API write authority from a web CRM or management-chat control.

Surface and tier boundaries

Each endpoint page in this reference documents its request fields and responses. For client-specific coverage, see MCP Server and CLI.

Rate Limits

Paid-tier rate limits are per API key and vary by plan. Trial limits are durable and account-wide across all active keys:

For the trial, properties and contacts each allow 10 reads/minute, 5 writes/minute, 20 writes/day, and 50 writes over the trial lifetime. Trial list pages are capped at 20 items. Trial property mutations are private and image-free, and do not trigger geocoding or outbound webhook/notification side effects. Image endpoints, image URL imports, bulk operations, messages, workflows, showings, webhooks, provider integrations, and AI/outbound actions are not part of the trial surface.

Write operations on paid tiers have additional per-resource daily and monthly caps. See your plan details for specifics.

Rate limit headers are included in every response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1707667200
X-RateLimit-Resource: properties
Retry-After: 3                    (429 responses only)

Daily trial total and resource-write exhaustion returns Retry-After seconds until the next UTC midnight. Trial lifetime exhaustion has no timed retry: upgrade to continue, and rotating keys does not reset it. A transient trial usage-store failure fails closed with a finite five-second retry interval.

Pagination

All list endpoints return paginated results:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}

Page size is capped by your plan tier (Free Trial: 20, Starter: 50, Pro: 100, Scale: 200).

Trial signup and account controls

Free Trial API access is a released, bounded entitlement, not a production signup-abuse control. Signup requires email verification. Production Better Auth configuration applies a 5/minute sign-up rule and a 100/minute general rule; development disables Better Auth’s built-in limiter. The current account schema/control plane has no account-suspension authority and no cross-account identity/Sybil prevention guarantee.

Errors

Errors follow RFC 9457 Problem Details . Responses use Content-Type: application/problem+json:

{
  "type": "https://rentalot.ai/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Property not found"
}

Validation errors include a per-field errors array:

{
  "type": "https://rentalot.ai/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request validation failed",
  "errors": [
    { "field": "monthlyRent", "message": "Expected number, received string" }
  ]
}

Developer Tools

MCP Server

Connect an AI assistant with the Rentalot MCP server . The package registers 65 tools, but current API tier restrictions and client contract drift still apply. The MCP setup guide includes the correct RENTALOT_API_KEY and RENTALOT_BASE_URL configuration, the private first CRM job, and current limitations.

The MCP client’s RENTALOT_BASE_URL is the server origin, such as https://rentalot.ai or a local development origin. Do not append /api/v1 to that variable.

claude mcp add rentalot \
  -e RENTALOT_API_KEY=ra_your_key \
  -e RENTALOT_BASE_URL=https://rentalot.ai \
  -- npx -y @rentalot/mcp-server

CLI

Install the Rentalot CLI  for terminal reads and the current partial resource surface:

go install github.com/Rentalot-ai/rentalot-cli/cmd/rentalot@latest
rentalot config set api_key ra_your_key
rentalot config set base_url https://rentalot.ai
rentalot --help

base_url and RENTALOT_BASE_URL also use the server origin, not /api/v1. The CLI guide documents why its current property/contact write flags are not a canonical write path.

OpenAPI Spec

A machine-readable OpenAPI 3.0 spec is available at:

GET /api/v1/openapi.json

Use it to auto-generate client libraries in any language.