REST API & MCP

1. Introduction

Welcome to the YouthInn AI Integration Docs. Build seamlessly powerful AI experiences directly into the California housing network.

What Is YouthInn

YouthInn is the Housing Intelligence Layer for modern transient tenants. We directly connect young professionals, travel nurses, founders, creatives, and university students with curated, fully-furnished, and flexible housing options across California. Powered by Large Language Models (LLMs), our platform deeply understands unique user needs—from budget constraints to commute preferences.

Who It Serves

Landlords & Property Managers: Automated touring, omni-channel auto-responses, AI lead qualification.
Tenants: Seamless semantic search, intelligent AI matching, immediate tour bookings.
AI Agents (You!): External APIs to access real-time inventory on behalf of end users.

2. Core Concepts

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, your role is to act as a secure broker. You ingest natural language requests, call our APIs to find matching `Listings`, and execute high-trust actions (touring) using `Tenant Authentication`.

3. System Architecture

YouthInn operates as an API-First infrastructure with an integrated Agent-Based 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 -> Chat Interface -> AI Agent Router -> YouthInn API -> Database -> Landlord Dashboard.
Agent Gateway: An enforcement perimeter ensuring external AI tools have strictly governed access based on Landlord opt-in rules.

4. API Reference

Base URL: https://youthinn.co/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 Ammenity differentiators.

Student Housing Persona Example

Universities

You are an expert student housing assistant for off-campus housing.
Whenever a user asks for housing near a university (e.g., "Find me a place near UCLA under $1500"), you MUST call the YouthInn API with location="UCLA" and maxPrice=1500.
Present results cleanly with the absolute SEO link.

7. Model Context Protocol (MCP)

Native integration built for Claude Desktop and other MCP clients. Hosted at /api/mcp using stateless HTTP POST architecture.

search_properties(query, location, maxPrice) - Open capability
check_availability(propertyId) - Open capability
chat_with_landlord(propertyId, message) - Requires Auth Token
request_tour(propertyId) - Requires Auth Token

Context Injection Strategy: MCP queries automatically hydrate the LLM's context window with the minimized JSON representation of the properties to save LLM 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 REST 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-youthinn-agent
Client Secret: (Any arbitrary secure string)
Authorization URL: https://youthinn.co/oauth/authorize
Token URL: https://youthinn.co/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 YouthInn admin environment.

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 the public endpoints. Tour requests executed by agents are intrinsically tied to the user's verified token identity.

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.

Latest: Released the Agent Gateway Enforcement protocol & Stateful Tenant Authentication for external REST calls.

12. Examples & SDK

cURL Example - Fetching Listings

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

JavaScript Example - Authenticated Tour Request

const requestTour = async (propertyId, token) => {
  const res = await fetch('https://youthinn.co/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 the YouthInn 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.

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

Tenant Auth Token: A Firebase JWT generated by YouthInn upon user login, heavily cryptographically signed, ensuring action non-repudiation.