REST API & MCP

1. Introduction

Welcome to the Atlas & Nova Developer Docs. Build powerful housing AI experiences on top of the Atlas & Nova platform — the only marketplace with dedicated AI agents on both sides of the lease.

What Is Atlas & Nova

Atlas & Nova is the AI-native housing marketplace connecting tenants and landlords through intelligent agents. Nova guides tenants — searching listings, matching preferences, booking tours, and handling applications automatically. Atlas serves landlords — qualifying leads, filling vacancies, managing availability, and automating responses 24/7. Together they power the full lease lifecycle.

Who It Serves

Landlords & Property Managers: Atlas AI handles touring, lead qualification, omni-channel auto-responses, and vacancy filling automatically.
Tenants: Nova AI provides semantic search, intelligent matching, instant tour booking, and application management.
External AI Agents (You!): REST + MCP APIs for real-time inventory access, availability checks, and tour requests on behalf of users.

2. Core Concepts

Atlas — Landlord AI

Your autonomous landlord agent. Qualifies leads, schedules tours, fills vacancies, and manages availability on autopilot.

Nova — Tenant AI

Your personal housing agent. Searches listings, matches preferences, books tours, and handles applications for tenants.

Listing Object

The fundamental entity. Represents a physical space available for rent.

Unit vs Property

A Property is a building. A Unit is a specific leasable space within it (applicable to multi-family).

Availability Model

Real-time calendar blocks defining when a unit can be toured or leased.

Inquiry Lifecycle

The state machine governing a tenant's journey from "interested" to "leased".

AI Agent Role: As an external AI Agent, you act as a secure broker. Ingest natural language requests, call our APIs to find matching `Listings` via Nova's search engine, and execute high-trust actions (touring, applying) using `Tenant Authentication`.

3. System Architecture

Atlas & Nova operates as an API-First infrastructure with a dual-agent automation layer.

Unified Source of Truth: All real estate pricing, availability, and descriptions are hosted centrally in Firestore. No duplicated CRM records.
Data Flow: Tenant → Nova Chat Interface → AI Router → Atlas & Nova API → Firestore → Atlas Landlord Dashboard.
Agent Gateway: An enforcement perimeter ensuring external AI tools have strictly governed access based on Landlord opt-in rules.
Nova Agent: Executes tenant-side flows — search, match, tour booking, application submission.
Atlas Agent: Executes landlord-side flows — lead intake, qualification, availability sync, auto-reply.

4. API Reference

Base URL: https://atlasandnova.ai/api/public
All endpoints return JSON. Successful requests return 200/201. Errors return 4xx/5xx with an error key.

4.1 Listings & 4.2 Availability

GET/listings

Query Parameters

limit

integer

Max results to return (Default 20).

location

string

Fuzzy search query for city/neighborhood.

maxPrice

number

Maximum monthly rent ceiling.

4.3 Tour & 4.4 Inquiry (Authenticated)

POST/agent/interact

⚠️ Auth Required: Pass Firebase ID Token in the Authorization: Bearer <TOKEN> header.

Body Parameters

action

enum

'chat', 'tour', or 'apply'

propertyId

string

Firestore Listing ID

message

string

Optional human context for Landlord

5. Data Schemas

Listing Schema (Simplified)

{
  "id": "string",
  "title": "string",
  "price": "number",
  "location": "string",
  "description": "string",
  "amenities": ["string"],
  "image": "string (url)",
  "link": "string (url)"
}

6. AI Agent Usage Guide

Mapping Natural Language: Always extract explicit numeric constraints (like "under $2000" to `maxPrice=2000`) before calling the API. For fuzzy geographic regions, use the generic `location` parameter and let the backend perform semantic search mapping.

Structured Output: Present properties back to the user in a scannable format highlighting Price, Location, and Amenity differentiators.

Nova Search Example

Universities

You are Nova, an expert AI housing agent for Atlas & Nova.
Whenever a user asks for housing near a university (e.g., "Find me a place near UCLA under $1500"), call the Atlas & Nova API with location="UCLA" and maxPrice=1500.
Present results clearly with price, location, and a direct link to the listing.

7. Model Context Protocol (MCP)

Native MCP integration built for Claude Desktop and any MCP-compatible client. Endpoint: POST /api/mcp. Supports stateless HTTP-RPC — no SSE connection required.

Public Tools (no auth)

search_properties

querystring?Keywords like 'modern', 'quiet', 'pet-friendly'

locationstring?Area or university name, e.g. 'UCLA', 'Downtown LA'

maxPricenumber?Maximum monthly rent in USD

Returns: JSON array of matching listings from live Firestore inventory.

get_listing_detail

propertyIdstringThe Firestore listing ID

Returns: Full listing object including amenities, pricing, images, and landlord-set rules.

check_availability

propertyIdstringThe listing to check

datestring?Start date to check from (YYYY-MM-DD). Defaults to today.

Returns: Real availability slots pulled from the landlord's calendar (Google Cal, iCal, and Firestore events). Returns up to 5 next open slots with timezone.

Authenticated Tools

Require a valid tenant Bearer token via Authorization: Bearer <TOKEN>. Obtain one via the OAuth 2.0 flow at /oauth/authorize.

submit_inquiryAuth Required

propertyIdstringThe listing to inquire about

messagestringThe tenant's question or message

Returns: Atlas agent's reply after processing the inquiry through the A2A landlord inbox. The response is generated by the landlord's Atlas AI in real time.

book_tourAuth Required

propertyIdstringThe listing to book a tour for

slotstringISO datetime for desired tour slot, e.g. 2026-09-01T14:00:00Z

Returns: Tour request ID, status ('pending'), and confirmation message. The landlord is notified automatically. Record is written to Firestore.

submit_applicationAuth Required

propertyIdstringThe listing to apply for

moveInDatestringDesired move-in date (YYYY-MM-DD)

stayLengthstring?e.g. '12 months'. Defaults to 12 months.

messagestring?Personal note to the landlord

isStudentboolean?Whether the tenant is a student

schoolstring?School or university name

Returns: Application request ID, status ('pending'), and confirmation message. Written to Firestore and visible on the landlord's Atlas dashboard.

Tenant Identity & State Tools

Read and write the tenant's persistent Nova profile. All three require a valid tenant Bearer token.

get_tenant_profileAuth Required

Returns: Full Nova profile: preferences (locations, budget, roomType, moveInFrom, mustHaves, dealbreakers), persona (school, workplace, occupation, about), shortlist of saved listing IDs, and onboarding status.

update_preferencesAuth Required

locationsstring[]?Preferred areas or neighbourhoods

budgetMinnumber?Minimum monthly rent in USD

budgetMaxnumber?Maximum monthly rent in USD

roomTypeenum[]?'private_room' | 'studio' | 'shared' | '1br' | '2br' | 'any'

moveInFromstring?Earliest move-in date (ISO, e.g. 2026-09-01)

mustHavesstring[]?Required amenities, e.g. ['gym', 'parking']

dealbreakersstring[]?Conditions to exclude

Returns: { success: true, updated: string[] } — list of preference fields that were written. Only supplied fields are touched; others remain unchanged.

get_application_statusAuth Required

propertyIdstring?Optional: filter results to a single listing

Returns: Array of up to 20 tour requests and applications with id, type, propertyName, status (pending / confirmed / approved / declined), slot or moveInDate, and createdAt.

Landlord-Side Tools

Expose Atlas capabilities to external landlord agents. get_landlord_availability is public; the other two require a landlord Bearer token.

get_landlord_availability

landlordIdstringThe landlord's user ID

datestring?Start date (YYYY-MM-DD). Defaults to today.

Returns: timezone, workingHours, workingDays, and up to 10 next open tour slots from the landlord's real calendar (Google Cal + iCal + Firestore events).

respond_to_inquiryAuth Required

tenantIdstringThe tenant to reply to

listingIdstringThe listing the inquiry is about

messagestringReply text from Atlas or the landlord

statusenum?'accepted' | 'declined' | 'pending_review'. Defaults to 'accepted'.

confirmedSlotstring?ISO datetime of the confirmed tour slot, if applicable

Returns: Writes an interaction log to the landlord's agent_interactions subcollection and delivers a landlord_reply notification to the tenant's Nova inbox. Returns { success, status, confirmedSlot }.

publish_listingAuth Required

titlestringListing title (min 5 chars)

descriptionstringFull description (min 20 chars)

citystringCity

rent_monthlynumberMonthly rent in USD

state / countrystring?Optional location fields

address_line1string?Street address — used for geocoding

propertyTypeenum?'apartment' | 'house' | 'studio' | 'co-living'

bedrooms / bathroomsnumber?Room counts

amenitiesstring[]?e.g. ['gym', 'parking', 'laundry']

availableFromstring?Move-in date (YYYY-MM-DD)

furnished / utilities_includedboolean?Booleans

agent_instructionsstring?Private instructions for the Atlas AI on this listing

Returns: { success, propertyId, isPublished: true }. Geocodes the address via Google Maps. Listing is immediately live in the marketplace with aiExposure enabled.

MCP RPC — check_availability

POST /api/mcp
Content-Type: application/json

{
  "method": "tools/call",
  "params": {
    "name": "check_availability",
    "arguments": {
      "propertyId": "abc123",
      "date": "2026-09-01"
    }
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": {
      "propertyId": "abc123",
      "title": "Modern Studio near UCLA",
      "available": true,
      "timezone": "America/Los_Angeles",
      "nextAvailableSlots": [
        { "start": "2026-09-02T16:00:00.000Z", "end": "2026-09-02T17:00:00.000Z" },
        { "start": "2026-09-03T17:00:00.000Z", "end": "2026-09-03T18:00:00.000Z" }
      ]
    }
  }]
}

8. Integration Guide

We designed this API to slot directly into your existing third-party pipelines.

PMS/CRM Integration: For Enterprise Landlords, upcoming webhooks will dispatch events directly to systems like AppFolio or Buildium when a tour is booked via AI.
Third-Party Assistants: Use our Atlas & Nova endpoints within custom ChatGPT Plugins, Voice Assistants (e.g. BlandAI), or WhatsApp Bots to deliver instant housing capabilities.

Connecting to ChatGPT Custom GPTs

To give your ChatGPT custom agent the ability to securely book tours on behalf of users without asking them to manually copy/paste any API keys, we utilize the standard OAuth 2.0 Authorization Code flow.

ChatGPT OAuth 2.0 Configuration

Authentication Type: OAuth
Client ID: chatgpt-atlasandnova-agent
Client Secret: (Any arbitrary secure string)
Authorization URL: https://atlasandnova.ai/oauth/authorize
Token URL: https://atlasandnova.ai/api/oauth/token
Scope: (Leave Blank)

9. Public Data Feed

The /listings endpoint acts as a general public feed. It is heavily cached using Next.js caching layers to ensure extreme speed and low database load.

Update Frequency: Landlord updates to pricing or availability clear the cache within seconds (On-Demand Revalidation). You do not need to poll aggressively.

10. Security & Compliance

Tenant Authentication (OAuth 2.0): We no longer require users to manually copy or paste API tokens. External agents must configure a standard OAuth 2.0 redirect flow through /oauth/authorize. When a user approves access, the backend securely exchanges the code for a custom JWT signed by the Atlas & Nova platform.

Landlord Data Protection: The Agent Gateway framework allows landlords to explicitly toggle if external algorithms can view or interact with their inventory. Properties marked `aiExposure: disabled` silently disappear from API feeds to protect the asset.

Compliance: Designed with CCPA boundaries in mind. We do not export tenant PII through public endpoints. Tour requests executed by agents are tied to the user's verified Nova identity token.

11. Versioning & Change Log

Strategy: Public APIs currently fall under the `v1` (un-versioned route mapping `/api/public`). In future breaking updates, paths will migrate to `/api/v2/`.

Deprecation Policy: 90-day warning minimum before sunsetting any active schema field.

LatestMCP Tier 3 tools shipped: get_landlord_availability, respond_to_inquiry, and publish_listing — external landlord agents can now read real calendar slots, reply to tenant inquiries via the A2A protocol, and push listings directly into the marketplace.

PriorMCP Tier 2 tools shipped: get_tenant_profile, update_preferences, and get_application_status — agents can now read and write the tenant's persistent Nova profile and query live request/application records from Firestore.

PriorMCP Tier 1 tools shipped: get_listing_detail, submit_inquiry, book_tour, and submit_application now write real records to Firestore. check_availability upgraded to pull live landlord calendar slots (Google Cal + iCal + Firestore events) instead of mock data.

PriorReleased the Agent Gateway Enforcement protocol & Stateful Tenant Authentication for external REST calls.

12. Examples & SDK

cURL — Search listings

curl -X GET "https://atlasandnova.ai/api/public/listings?location=ucla&maxPrice=2500" \
  -H "Accept: application/json"

JavaScript — MCP: check real availability

const checkAvailability = async (propertyId, date) => {
  const res = await fetch('https://atlasandnova.ai/api/mcp', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      method: 'tools/call',
      params: { name: 'check_availability', arguments: { propertyId, date } }
    })
  });
  return await res.json(); // returns nextAvailableSlots[]
};

JavaScript — MCP: book a tour (auth required)

const bookTour = async (propertyId, slot, token) => {
  const res = await fetch('https://atlasandnova.ai/api/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      method: 'tools/call',
      params: {
        name: 'book_tour',
        arguments: { propertyId, slot }
      }
    })
  });
  return await res.json(); // { requestId, status: 'pending', message }
};

JavaScript — MCP: submit inquiry to Atlas (A2A)

const submitInquiry = async (propertyId, message, token) => {
  const res = await fetch('https://atlasandnova.ai/api/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify({
      method: 'tools/call',
      params: {
        name: 'submit_inquiry',
        arguments: { propertyId, message }
      }
    })
  });
  // Atlas agent replies in real time via the A2A inbox
  return await res.json();
};

13. Rate Limits & Usage Policy

Global Limit: Public unauthenticated calls are restricted to 100 requests per IP per minute. We employ strict abuse detection to halt generalized scraping.

Commercial Usage: Integration of Atlas & Nova endpoints into paid platforms, large-scale custom GPTs, and commercial AI routing engines is currently free under the Fair Usage Policy, provided users execute standard Tenant flows.

14. Glossary

Agent Gateway: The enforcement mechanism that determines if a specific LLM channel (OpenAI, Claude) is allowed to interact with a listing on the Atlas & Nova platform.

MCP (Model Context Protocol): The stateless RPC specification for Claude and local intelligent clients to access Atlas & Nova tools natively.

Tenant Auth Token: A Firebase JWT generated by Atlas & Nova upon user login via Nova, cryptographically signed to ensure action non-repudiation.

Nova Identity: The tenant-side auth context linking a verified user to their Nova profile, preferences, and tour history.

Atlas Dashboard: The landlord-facing portal where property managers configure Atlas AI, manage listings, and view lead activity.