Protocol Documentation

The HomeSelf Protocol

Not a portal. A canonical registry for Verified Property Records.

Interactive AnswerPack Viewer

Every property generates an AnswerPack - a structured JSON document optimized for LLM context windows. Expand sections to explore.

f47ac10b.answerpack.json

{
  "hsp_protocol_version": "1.1",
  "hsp_internal_version": "2.1",
  "tier": "standard"
}

{
  "trust_score": 0.91,
  "trust_level": "platinum",
  "verification_level": "document_verified",
  "verified_documents_count": 3
}

The HomeSelf Protocol defines how properties become structured, verifiable records that AI systems can trust.

Canonical Definition

What is a VPR?

Verified Property Record (VPR) is a structured, machine-readable representation of a real-world property, designed to be discoverable, interpretable, and analyzable by AI systems.

This structure is demonstrated in a live example VPR.

Human Layer

A VPR IS:

A structured representation of a property
Identified by a unique, immutable ID
Computed from owner inputs, AI analysis, and data consistency checks
Published to a public registry queryable by AI systems

A VPR IS NOT:

A legal ownership certificate
A guarantee of transaction safety
An advertisement or premium placement
A replacement for legal due diligence

AI Layer

VPRs are machine-readable records that power:

AnswerPack

Structured JSON for LLM context windows

Registry Query

Public API for property discovery

AI Matching

Semantic property-to-seeker routing

Role of HomeSelf

HomeSelf provides the reference human–AI interface and the public registry where VPRs are created, validated, versioned, and made discoverable with trust signals.

See a canonical example of a Verified Property Record →

Intelligence Layer

Understand How AI Systems Discover Properties

The Protocol defines how properties can be represented. The Observatory studies how AI systems discover, compare, and surface properties through conversation.

Explore the Conversational Discovery Observatory

See how AI systems reason across 50 cities and 8 travel scenarios. Research-grade intelligence on conversational property discovery.

Supported Property Types (V1)

V1 PRIMARY

Residential Unit

Residential UnitDescription

apartment

flat, condo

studio

monolocale

loft

—

penthouse

attico

house

detached, townhouse

villa

—

townhouse

—

duplex

—

triplex

—

room

private room in shared property

V1 SUPPORTED

Commercial Space

Commercial SpaceDescription

commercial

generic commercial space

office

business premises

retail

shop, store

V1 SUPPORTED

Industrial Space

Industrial SpaceDescription

warehouse

storage facility

V1 SUPPORTED

Land

LandDescription

land

generic land

vacant_land

building plot

plot

parcel

V1 SUPPORTED

Building

BuildingDescription

building

multi-unit building

V1 SUPPORTED

Ancillary Space

Ancillary SpaceDescription

garage

parking space

parking

parking spot

storage

self-storage unit

V1 SUPPORTED

Hospitality Unit

Hospitality UnitDescription

hotel

—

bed_and_breakfast

B&B

V1 SUPPORTED

Special Asset

Special AssetDescription

other

custom type

Note: Property type determines registry classification and query behavior. Room searches return only room listings; all other searches exclude rooms (entire_property bucket).

Portals vs Protocol

HomeSelf isn't another property portal. It works differently by design.

Traditional Portals	HomeSelf Protocol
Listings are ads	Records are protocol entries
Data optimized for humans	Data optimized for AI + humans
Visibility is paid	Discovery is semantic
Each portal has its own copy	One canonical record
Agents mediate access	Direct owner ↔ seeker
SEO tricks	Registry queries
Platform owns data	Owner controls record

Key Insight: Portals are walled gardens that monetize attention. HomeSelf is a public registry that makes property data universally accessible to AI systems.

VPR Lifecycle

Draft

Private construction — only you can see and edit

Active

Public registry — discoverable by search and AI systems

Paused

Temporarily hidden — data preserved, not discoverable

Archived

Historical record — not deleted, preserved for reference

Property Intents

Code	Intent	Description
`sell`	Selling	Property for sale
`rent_long`	Long-term Rental	12+ month leases
`rent_short`	Short-term / Hospitality	Vacation, Airbnb-style
`room`	Shared Living	Private room in shared property
`invest`	Yield-focused	Investment / rental income
`relocate`	Cross-border	International / relocation
`develop`	Land / Projects	Development opportunities

Note: Intent is set when creating a VPR and can be changed. Search filters often use intent to match properties to specific use cases (e.g., filtering "rent_long" for annual rentals vs "rent_short" for vacation stays).

Trust Score Explained

Every listing has a computed Trust Score (0.0 - 1.0) based on verifiable data. No fake reviews, no paid rankings.

Completeness40%

How many fields are filled (title, description, photos, price, etc.)

Documents30%

Document consistency (cadastral, energy certificate, ownership)

Photos20%

AI-analyzed photo quality and authenticity

Freshness10%

How recently the listing was updated

API Reference

Public endpoints for searching properties and accessing the registry. All data is read-only and optimized for LLM consumption.

POST/api/seeker/search

Natural language property search

Request

{
  "query": "2-bedroom apartment in Milan under 300k",
  "limit": 10
}

Response

{
  "results": [
    {
      "id": "uuid",
      "title": "Bilocale luminoso",
      "trust_score": 0.87,
      "price": 250000
    }
  ],
  "total": 42
}

cURL Example

curl -X POST https://homeself.ai/api/seeker/search \
  -H "Content-Type: application/json" \
  -d '{"query":"2-bedroom apartment in Milan under 300k","limit":10}'

Protocol Origin

The Verified Property Record (VPR) concept was introduced by Marco Patrone as part of the HomeSelf Protocol.

AI Discovery Surface

Standard endpoints that enable AI systems to discover and consume property data without prior knowledge of HomeSelf.

Endpoint	Description
`/.well-known/ai.json`	AI-Plugin discovery (OpenAI/Anthropic compatible)
`/.well-known/homeself/registry.json`	Paginated index of all active VPRs
`/api/property/{id}.jsonld`	Schema.org JSON-LD for property (SEO indexable)
`/api/property/{id}.answerpack.json`	Complete AnswerPack with all computed fields

Roadmap

MCP Tools (Model Context Protocol)

HomeSelf is developing MCP-compatible tools to enable AI agents using Claude Desktop, Custom GPTs, or any MCP-compatible client to directly search and retrieve property data. This capability is currently in development.

search_properties (planned)

Search listings with natural language

• query (required)

• filters (optional)

• limit (default: 10)

get_property_deep_intel (planned)

Get complete AnswerPack for a property

• listing_id (required)

Planned Example: search_properties

{
  "query": "2-bedroom apartment in Milan under 300k",
  "filters": {
    "city": "Milano",
    "max_price": 300000,
    "property_type": "apartment"
  },
  "limit": 10
}

Planned Claude Desktop Configuration

{
  "mcpServers": {
    "homeself": {
      "command": "python",
      "args": ["/path/to/homeself/backend/mcp_server.py"]
    }
  }
}

Roadmap

Request Coordination (Roadmap)

The coordination layer being designed for AI agents to route non-binding property requests. All actions require owner confirmation. No autonomous negotiation or transaction execution. Currently in conceptual development.

Planned State Machine Flow

SUBMITTED

→

OWNER_SEEN

→

OWNER_REPLIED

→

CLOSED

→

EXPIRED

Owner-Confirmed Action Endpoints

POST

/api/v1/public/vpr/{slug}/actions/inquiry (planned)

Submit inquiry action to property owner

POST

/api/v1/public/vpr/{slug}/actions/availability (planned)

Submit availability request to property owner

POST

/api/v1/public/vpr/{slug}/actions/viewing (planned)

Request property viewing appointment

GET

/api/v1/public/actions/{action_id}/status (planned)

Check action status and owner response

Owner Action Status Response

AI agents can query the status of submitted actions to retrieve owner responses:

{
  "action_id": "uuid",
  "status": "owner_replied",
  "owner_reply_available": true,
  "owner_message": "Property is available. Would you like to schedule a viewing?",
  "submitted_at": "2025-01-07T10:00:00Z",
  "owner_replied_at": "2025-01-07T14:30:00Z",
  "property_trust_score": 0.91,
  "verification_level": "document_verified"
}

Roadmap

Structured Property Search (Roadmap)

AI systems can query structured property records to satisfy seeker constraints and route non-binding owner-confirmed requests. This capability is in development.

Planned Request Payload

{
  "query": "2-bedroom in Milan under 300k",
  "budget_max": 300000,
  "city": "Milano",
  "property_type": "apartment",
  "min_bedrooms": 2,
  "limit": 10
}

Planned Compatibility Factors

Budget alignment (price within range)
Property type match
Rooms/bedrooms constraints
Surface area requirements
Feature filters (balcony, parking, etc.)
Trust score threshold (0.5+)

Planned Example Response

{
  "success": true,
  "matches": [
    {
      "listing_id": "uuid",
      "title": "Modern 2-Bedroom Apartment",
      "compatibility_score": 92,
      "reasoning": "Matches all criteria: 2 beds, €280k, Milano",
      "trust_score": 0.87,
      "next_questions": ["Is balcony important?", "Need parking?"]
    }
  ],
  "total_found": 42
}