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".
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
Query Parameters
limitlocationmaxPrice4.3 Tour & 4.4 Inquiry (Authenticated)
⚠️ Auth Required: Pass Firebase ID Token in the Authorization: Bearer <TOKEN> header.
Body Parameters
actionpropertyIdmessage5. Data Schemas
{
"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
UniversitiesYou 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 integration built for Claude Desktop and other MCP clients. Hosted at /api/mcp. Both Atlas and Nova capabilities are exposed as MCP tools.
search_properties(query, location, maxPrice)- Open capabilitycheck_availability(propertyId)- Open capabilityrequest_tour(propertyId)- Requires Auth Tokenchat_with_atlas(propertyId, message)- Requires Auth Token
Context Injection Strategy: MCP queries automatically hydrate the LLM's context window with minimized JSON listing data to save tokens.
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.
- 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.
12. Examples & SDK
curl -X GET "https://atlasandnova.ai/api/public/listings?location=ucla&maxPrice=2500" \ -H "Accept: application/json"
const requestTour = async (propertyId, token) => {
const res = await fetch('https://atlasandnova.ai/api/public/agent/interact', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${token}`
},
body: JSON.stringify({ action: 'tour', propertyId })
});
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.