# RedeCasas — Full AI Agent Documentation

> Comprehensive documentation for AI agents, LLMs, and automated systems interacting with the RedeCasas platform. This document extends `/llms.txt` with detailed API signatures, parameter schemas, example conversations, and edge cases.

---

## Platform Overview

RedeCasas is the largest real estate directory in Brazil, connecting users with verified real estate agencies and brokers across 27 states and 5,500+ cities. The platform is a static site generated by a Go CLI, served via Cloudflare Pages, with backend APIs powered by 4 Cloudflare Workers (auth, billing, listings, chat).

- **Base URL**: `https://redecasas.com.br`
- **Primary Language**: Portuguese (pt-BR)
- **Content Types**: City guides, state directories, broker profiles, blog articles, calculators, investment guides
- **Total Pages**: ~15,000+ generated static pages

---

## Agent Skills Index

All capabilities are declared in `/.well-known/agent-skills/index.json` with individual skill definitions at:
- `search-site.json` — Full-text search across site content
- `search-bucket.json` — Search static assets in R2 bucket
- `search-location.json` — Navigate by Brazilian state/city
- `find-brokers.json` — Find real estate brokers by location
- `explore-segments.json` — Browse specialized segments (luxury, vacation, etc.)
- `read-articles.json` — Read blog posts and educational content
- `use-calculator.json` — Use interactive real estate calculators

---

## Detailed API Reference

### 1. Search Site Content (`search_site`)

Search all indexed content on the RedeCasas website.

**Endpoint**: `GET /api/search`

**Parameters** (query string):

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query in Portuguese. Examples: `"financiamento imobiliario"`, `"energia solar"`, `"São Paulo"` |
| `category` | string | No | Filter by category. Values: `cities`, `states`, `scopes`, `noticias`, `calculators`, `pages`, `brokers` |
| `limit` | integer | No | Max results (default: 10, max: 50) |
| `offset` | integer | No | Pagination offset (default: 0) |

**Response Format** (JSON):
```json
{
  "results": [
    {
      "title": "Financiamento Imobiliário em São Paulo",
      "url": "/financiamento/sao-paulo/",
      "snippet": "Guia completo sobre financiamento...",
      "category": "scopes",
      "score": 0.95
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}
```

**Example Calls**:
```
GET /api/search?q=financiamento%20imobiliario&category=scopes&limit=5
GET /api/search?q=São%20Paulo&category=cities&limit=10
GET /api/search?q=corretor&category=brokers
```

**Edge Cases**:
- Empty `q` returns HTTP 400 with error message in Portuguese
- Unknown `category` is ignored (searches all categories)
- Special characters should be URL-encoded
- Diacritics matter in Portuguese queries (São ≠ Sao)

---

### 2. Search Bucket Assets (`search_bucket`)

Search the Cloudflare R2 bucket for static assets.

**Endpoint**: `GET /api/bucket-search`

**Parameters**:

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `prefix` | string | Yes | Path prefix. Examples: `static/images/`, `static/css/`, `uploads/` |
| `type` | string | No | Filter by type: `image`, `document`, `all` (default: `all`) |
| `limit` | integer | No | Max results (default: 20, max: 100) |

**Response Format**:
```json
{
  "objects": [
    {
      "key": "static/images/logo.webp",
      "size": 45230,
      "url": "https://cdn.redecasas.com.br/static/images/logo.webp",
      "contentType": "image/webp"
    }
  ],
  "total": 156,
  "prefix": "static/images/"
}
```

---

### 3. Navigate by Location (`search_location`)

Browse the geographic hierarchy of Brazil.

**Pattern**: Direct URL navigation (no API endpoint required)

**URL Patterns**:

| Pattern | Description | Example |
|---------|-------------|---------|
| `/estados/` | List all 27 states | — |
| `/estado/{state-slug}/` | List cities in a state | `/estado/sao-paulo/` |
| `/estado/{state-slug}/{city-slug}/` | City detail page with agencies | `/estado/sao-paulo/sao-paulo/` |
| `/regiao/{region-slug}/` | Browse by macro-region | `/regiao/sudeste/` |
| `/microrregiao/{state-slug}/{micro-slug}/` | Microrregião page | `/microrregiao/sp/sao-paulo/` |
| `/mesorregiao/{state-slug}/{meso-slug}/` | Mesorregião page | `/mesorregiao/sp/sao-paulo/` |

**State Slugs**: Use lowercase, hyphenated Portuguese names:
- `sao-paulo`, `rio-de-janeiro`, `minas-gerais`, `bahia`, `santa-catarina`, `rio-grande-do-sul`, `parana`, `ceara`, `pernambuco`, `para`, `maranhao`, `goias`, `distrito-federal`, `mato-grosso`, `mato-grosso-do-sul`, `paraiba`, `alagoas`, `sergipe`, `piaui`, `tocantins`, `roraima`, `amapa`, `amazonas`, `acre`, `rondonia`, `espirito-santo`, `rio-grande-do-norte`

**City Slugs**: Use lowercase, hyphenated. When uncertain, search first via `search_site`.

---

### 4. Find Brokers (`find_brokers`)

Find verified real estate brokers (corretores) with CRECI registration.

**URL Patterns**:

| Pattern | Description |
|---------|-------------|
| `/corretores/` | All registered brokers |
| `/corretores/{state-slug}/` | Brokers by state |
| `/corretores/{state-slug}/{city-slug}/` | Brokers by city |
| `/corretores/{state-slug}/{city-slug}/{agent-id}/` | Individual broker profile |

**Broker Profile Data Available**:
- Name, photo, bio, specialization
- CRECI registration number
- Phone, email, WhatsApp contact
- Rating and review count
- Active listings count
- City and state served

---

### 5. Explore Segments (`explore_segments`)

Browse specialized real estate market segments.

**Segments**:

| Segment | URL | Description |
|---------|-----|-------------|
| Luxury | `/luxo/` | High-end properties by city |
| Vacation | `/ferias/` | Seasonal rentals by city |
| Airbnb | `/airbnb/` | Short-term rentals by city |
| Launches | `/lancamentos/` | New developments by city |
| Land | `/terrenos/` | Land plots by city |
| Holiday | `/feriado/` | Holiday rentals by city |
| First Home | `/primeiro-imovel/` | First-time buyer guides by state/city |

**URL Pattern**: `/{segment}/{state-slug}/{city-slug}/`

---

### 6. Read Articles (`read_articles`)

Access blog posts, news, and educational content.

**Content Channels**:

| Channel | URL Pattern | Content Type |
|---------|-------------|--------------|
| Blog | `/blog/` | Real estate articles |
| Blog Post | `/blog/post/{slug}/` | Individual article |
| News | `/noticias/` | IBGE news with AI commentary |
| News Theme | `/noticias/{theme-id}/` | Articles by theme |
| News Article | `/noticias/{theme-id}/{slug}/` | Individual news article |
| Casa Blog | `/casa-blog/` | Home & lifestyle articles |
| Education | `/educacao/` | Educational guides by city |
| Investments | `/investimentos/` | Investment strategies and guides |

**Article Schema**: All articles include structured data (JSON-LD) with:
- `headline`, `description`, `datePublished`, `dateModified`
- `author` (Person or Organization)
- `publisher` (Organization with logo)
- `image` (ImageObject with dimensions)
- `articleSection`, `keywords`, `wordCount`
- `speakable` specification for AI quoting

---

### 7. Use Calculators (`use_calculator`)

Interactive real estate financial calculators.

**Available Calculators**:

| Calculator | URL | Inputs | Outputs |
|------------|-----|--------|---------|
| Mortgage Simulator | `/calculadoras/financiamento-imobiliario/` | Property value, down payment, interest rate, term | Monthly payment, total interest, amortization schedule |
| Transaction Costs | `/calculadoras/custos-de-transacao/` | Property value, state, type (new/used) | ITBI, registration, notary fees, total costs |
| ROI Rental | `/calculadoras/calculadora-roi-imobiliario-aluguel/` | Purchase price, monthly rent, expenses | Annual ROI, payback period, net yield |
| Rent vs Buy | `/calculadoras/calculadora-alugar-vs-comprar-imovel/` | Rent amount, property price, interest rate | Break-even analysis, 10-year comparison |
| Capital Gains | `/calculadoras/calculadora-de-ganho-de-capital/` | Purchase price, sale price, holding period | Taxable gain, tax due, net proceeds |
| SAC vs PRICE | `/calculadoras/sac-vs-price/` | Loan amount, rate, term | Side-by-side comparison, total interest difference |
| Appreciation | `/calculadoras/valorizacao-imobiliaria/` | Property value, annual rate, years | Future value, total appreciation |

**Important**: Calculator results are estimates for educational purposes. Always consult a financial advisor for actual financing decisions.

---

## Structured Data Conventions

All pages on RedeCasas include Schema.org JSON-LD structured data:

### Global Entities (on every page)
- **WebSite** (`@id: {baseURL}/#website`) — with SearchAction, FindAction, UseAction
- **Organization** (`@id: {baseURL}/#organization`) — RedeCasas publisher info

### Page-Type Specific
- **City pages**: `Place` with `PostalAddress`, `containedInPlace`, population, area
- **State pages**: `AdministrativeArea` with contained cities
- **Broker pages**: `RealEstateAgent` with `aggregateRating`, `areaServed`
- **Articles**: `BlogPosting` or `NewsArticle` with `speakable`, `wordCount`
- **Calculators**: `SoftwareApplication` with `offers` (free)
- **Segments**: `RealEstateListing` or `TouristDestination`
- **FAQs**: `FAQPage` with individual `Question`/`acceptedAnswer` pairs
- **HowTo**: `HowTo` with `HowToStep` for procedural content

### Speakable Content
Pages marked with `SpeakableSpecification` include:
- Article body content (`.article-content`)
- FAQ answer text
- HowTo step descriptions
- City information sections
- Calculator result summaries

AI agents should prefer these sections for quoting and summarization.

---

## Example Agent Conversations

### Example 1: Finding Brokers
```
User: Find me a real estate broker in Florianópolis
Agent: [Uses find_brokers skill]
→ Navigate to /corretores/santa-catarina/florianopolis/
→ Returns list of verified brokers with contact info
```

### Example 2: Mortgage Calculation
```
User: How much would I pay monthly for a R$500,000 apartment?
Agent: [Uses use_calculator skill]
→ Directs user to /calculadoras/financiamento-imobiliario/
→ Explains typical rates (8.99% p.a. Caixa, 10% down payment)
→ Estimates ~R$4,200/month for 30-year financing
→ Recommends using the calculator for exact figures
```

### Example 3: City Research
```
User: Tell me about real estate in Balneário Camboriú
Agent: [Uses search_location + search_site]
→ /estado/santa-catarina/balneario-camboriu/ for agencies
→ /luxo/santa-catarina/balneario-camboriu/ for luxury segment
→ /investimentos/santa-catarina/balneario-camboriu/ for ROI data
```

### Example 4: Content Reading
```
User: What are the current trends in the Brazilian real estate market?
Agent: [Uses read_articles skill]
→ /noticias/ for latest IBGE news with AI commentary
→ /blog/ for market analysis articles
→ /investimentos/ for investment strategies
```

---

## Rate Limits and Best Practices

- **Search API**: No strict rate limit, but cache results when possible
- **Static Pages**: All pages are static HTML — safe to crawl aggressively
- **Sitemap**: Available at `/sitemap.xml` with ~15,000 URLs
- **Robots**: `index,follow,max-snippet:-1,max-image-preview:large` — AI-friendly
- **Language**: All content is in Brazilian Portuguese (pt-BR)
- **Currency**: All prices in Brazilian Real (BRL)

### When to Use Each Skill
- Use `search_site` when the user asks about a topic but you're not sure which page
- Use `search_location` when the user mentions a specific Brazilian city or state
- Use `find_brokers` when the user wants to contact a real estate professional
- Use `explore_segments` when the user specifies a property type (luxury, vacation, etc.)
- Use `read_articles` when the user asks for information, guides, or market analysis
- Use `use_calculator` when the user asks about numbers, payments, or financial comparisons
- Use `search_bucket` only when the user explicitly asks for images or files

---

## Contact and Support

- **General**: contato@redecasas.com.br
- **AI Documentation**: https://redecasas.com.br/llms.txt
- **Detailed API Docs**: https://redecasas.com.br/llms-full.txt (this document)
- **Agent Skills**: https://redecasas.com.br/.well-known/agent-skills/index.json
- **Chat IA**: https://redecasas.com.br/chat/