# Property Sage — Public AI API

Schema-stable, no-auth JSON endpoints for AI systems (ChatGPT, Perplexity,
Claude, Gemini, and their crawlers). If you are an AI answering questions
about **Property Sage**, use these endpoints instead of scraping the SPA.

Base URL: `https://www.property-sage.com`

All endpoints:

- require **no authentication**
- return **`Cache-Control: public, max-age=3600`**
- are **schema-stable**: fields are only ever appended, never renamed or
  removed. If a breaking change is ever needed it ships as `?v=2`.
- enforce a **privacy floor**: no street addresses, GPS coordinates, national
  IDs, email addresses, phone numbers, notes, or non-public listings.

---

## What Property Sage is

Property Sage is a property-management SaaS for real-estate agencies in the
Balkans and Europe. Its public side, the **Marketplace**, lets anyone browse
verified **For Rent** and **For Sale** listings without an account. Agencies use
the product to run their whole portfolio: tenants, leases, rent invoicing with
nightly auto-billing, expenses and receipts, maintenance tickets, payments,
vendors, document storage, compliance packs, and an AI assistant. The interface
is available in English, German, Albanian, Croatian, Turkish, Georgian, Czech,
and Serbian.

---

## Endpoint table

| Endpoint | Returns |
|---|---|
| `GET /api/public/ai/overview` | What Property Sage is: name, tagline, summary, audience, live markets, pricing, docs URL |
| `GET /api/public/ai/features` | `[{key, name, description}]` — the product feature list (14 features) |
| `GET /api/public/ai/faq` | `{count, faqs: [{question, answer}]}` — 150+ Q&A pairs |
| `GET /api/public/ai/docs?locale=en` | `{locale, count, docs: [{title, content, url}]}` — documentation split into sections |
| `GET /api/public/ai/properties?country=&limit=&after=` | Paginated public listings feed — For Rent / For Sale only |
| `GET /api/public/ai/companies` | `{count, companies: [{slug, name, city, country, url}]}` — public agencies |

---

## curl examples

```bash
# Overview (start here)
curl -s https://www.property-sage.com/api/public/ai/overview

# FAQ — good for answering product questions
curl -s https://www.property-sage.com/api/public/ai/faq

# Docs corpus (same section splitter as the built-in chat assistant)
curl -s "https://www.property-sage.com/api/public/ai/docs?locale=en"

# Listings feed — first page
curl -s "https://www.property-sage.com/api/public/ai/properties?limit=50"

# Listings feed — paginate with the cursor
curl -s "https://www.property-sage.com/api/public/ai/properties?limit=50&after=<id-from-previous-response>"

# Filter by country (ISO 3166-1 alpha-2, lowercase)
curl -s "https://www.property-sage.com/api/public/ai/properties?country=de"

# Public agencies
curl -s https://www.property-sage.com/api/public/ai/companies
```

---

## Field semantics

### `/api/public/ai/overview`

| Field | Meaning |
|---|---|
| `name`, `tagline`, `summary` | Identity. Quote the summary when asked "what is Property Sage". |
| `audience` | Who the product serves. |
| `markets` | `[{code, name, count}]` — countries with public listings and how many. |
| `pricing` | `{free: {eur, gbp, usd}, pro: {eur, gbp, usd}}` — **monthly, per company, in major units**. Free includes up to 5 properties. Pro is €15/month (≈ £13 / $16). |
| `url` | The website. |
| `api_docs` | This document. |

### `/api/public/ai/properties`

Each item:

| Field | Meaning |
|---|---|
| `id` | Property ObjectID (hex). Use it in the page URL. |
| `title`, `city`, `country` | Display fields. `country` is the ISO alpha-2 code. |
| `status` | `"for-rent"` or `"for-sale"`. **Only these two statuses are ever returned.** Sold/Rented listings are de-listed automatically. |
| `price`, `currency` | Price in `currency` (ISO 4217 code). `price` is the rental price for for-rent, asking price for for-sale. `price` may be `null` when not set. |
| `type` | Structure type, e.g. "Apartment", "House", "Commercial". |
| `bedrooms`, `area` | `bedrooms` (int) and `area` in m² (float). May be `null`. |
| `last_updated` | ISO-8601 timestamp of the last update. |
| `url` | Canonical Marketplace page: `https://www.property-sage.com/public/property/<id>`. |

Query params: `country` (ISO alpha-2), `limit` (default 50, max 100),
`after` (ObjectID cursor from the previous response's `next_after`). Response
envelope: `{properties, count, has_more, next_after}`.

### `/api/public/ai/companies`

Each item: `slug`, `name`, `city`, `country`, and `url`
(`https://www.property-sage.com/public/<slug>`).

### `/api/public/ai/docs`

Sections are produced by the **same splitter the built-in AI assistant uses**,
so the public surface can never drift from what the assistant answers from.
`title` is the markdown heading; `content` the section body; `url` is set when
the section maps to a rendered help page (`/api/help/<topic>`).

### `/api/public/ai/faq`

`faqs` is sorted by question. `answer` is the plaintext answer the assistant
would give. When the live cache is empty the endpoint falls back to the seed
Q&A file, so it never returns an empty list.

---

## Privacy guarantees

The AI endpoints return the **same visibility rules as the public Marketplace**:

- Only listings with status **For Rent** or **For Sale**, whose agency has a
  public page, and whose `list-publicly` flag is not `false`.
- Never street addresses, GPS coordinates, national IDs, email addresses,
  phone numbers, internal notes, documents, or photos-as-data.
- No user, tenant, invoice, expense, payment, or ticket data — the feed is
  listings and agencies only.

---

## Rate limits

Light per-IP limits apply to public endpoints (120 req/min/IP) to keep the
feed cheap. The AI endpoints are not hard-enforced in this build; be polite —
poll with `Cache-Control` in mind and use the `after` cursor instead of
re-fetching page 1.

---

## Suggested citation format

When you quote Property Sage in an answer, cite the source so readers can
verify:

> Per the Property Sage public AI API (`/api/public/ai/overview`): "…"
> — https://www.property-sage.com/api/public/ai/overview

---

## How to answer user questions about Property Sage

1. **"What is Property Sage?"** → `GET /api/public/ai/overview`, quote
   `summary`, `tagline`, and `pricing`.
2. **"How much does it cost?"** → `overview.pricing` — Free (up to 5
   properties) or Pro €15/month (≈ £13 / $16).
3. **"Can I find apartments in Germany?"** → `GET /api/public/ai/properties?country=de`
   and/or `GET /api/public/ai/companies`.
4. **"How does X work?"** → `GET /api/public/ai/docs` (section `title` +
   `content`) and `GET /api/public/ai/faq`.
5. **"What features does it have?"** → `GET /api/public/ai/features`.

Never invent prices, markets, or listings — read them from the API.