REST API

La REST API

I Suoi sistemi leggono il catalogo di Realton e il Suo CRM, e scrivono clienti, note, attività e fasi delle trattative, a nome della persona che ha creato la chiave.

Piano Agency

Per iniziare

In Realton, un proprietario o un amministratore apre Impostazioni › API e MCP, spunta REST API e sceglie Crea una chiave. La copi subito: viene mostrata una sola volta.
La tenga sul Suo server, in una variabile d’ambiente:
```
export REALTON_API_KEY="rtk_live_…"
```

Faccia la prima chiamata:

curl "https://realton.ai/api/v1/projects?place=Dubai&beds=2&limit=5" \
  -H "Authorization: Bearer $REALTON_API_KEY"

Svilupparla con un’AI

Oggi la maggior parte delle integrazioni la scrive un’AI. Le dia questi due indirizzi e il compito in poche parole; il resto lo legge da sola.

La guida sintetica /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Un prompt da copiare, con le parti tra parentesi compilate:

Voglio collegare [il mio sito / il mio CRM / il mio sistema] alla REST API di Realton.
Leggi prima la guida sintetica: https://realton.ai/docs/api.md
Il documento OpenAPI completo: https://realton.ai/docs/openapi.json
Il mio stack: [ad esempio, Next.js su Vercel].
Cosa voglio: [ad esempio, mostrare sul mio sito i progetti di Realton a Dubai, aggiornati una volta al giorno].
La chiave API è nella variabile d’ambiente REALTON_API_KEY. Non chiedermi mai la chiave e non scriverla mai nel codice.

Non incolli mai la chiave in una chat. Imposti Lei REALTON_API_KEY sul server e all’AI dica solo il nome della variabile.

Le regole

La chiave

Ogni chiamata invia la chiave nell’header Authorization. Una chiave dà accesso alla REST API solo se alla creazione è stato spuntato REST API, e solo finché lo spazio di lavoro ha il piano Agency.

Authorization: Bearer rtk_live_…

A nome di chi agisce una chiamata

Una chiamata agisce come il membro che ha creato la chiave, con ciò che può vedere: un agente i propri clienti, un proprietario o un amministratore quelli dell’agenzia. Quando quel membro lascia lo spazio di lavoro, la chiave smette di funzionare.

Limiti

Fino a 120 chiamate al minuto per chiave. Oltre, la risposta è 429 con RATE_LIMITED e retryAfterSec: attenda quei secondi e chiami di nuovo.

Pagine

GET /projects restituisce fino a 100 progetti alla volta: limit indica quanti, offset da dove partire e total quanti sono in tutto.

Id

La chiave di un progetto arriva da GET /projects, l’id di un cliente da GET /clients e l’id di una trattativa dalla scheda del cliente, GET /clients/{id}, in deals[].id.

Nulla arriva ai clienti

Nessuna chiamata invia qualcosa a un cliente: POST /brochures restituisce un link che l’agente invia. I prezzi sono quelli del costruttore, nella valuta del costruttore.

Richieste rifiutate

Una richiesta rifiutata riceve un JSON con un code stabile. Si basi sul codice, mai sul messaggio.

{ "code": "plan_required" }

Stato	Codice	Cosa significa
401	key_required	Manca l’header Authorization con una chiave.
401	key_invalid	La chiave è sconosciuta o è stata revocata.
403	key_scope	La chiave non dà accesso alla REST API. Ne crei una con REST API spuntato.
403	plan_required	Lo spazio di lavoro non ha più il piano Agency.
403	key_member_gone	La persona che ha creato la chiave ha lasciato lo spazio di lavoro. Crei una nuova chiave.
404	not_found	Non trovato, oppure non visibile a questo membro.
429	RATE_LIMITED	Troppe chiamate in questo minuto. Attenda retryAfterSec secondi.
400	place_unknown, whatsapp_invalid, …	Un campo fuori intervallo o un valore non valido. Il codice lo indica.

Riferimento

Ogni chiamata con i suoi campi e un esempio, come nel documento OpenAPI.

Indirizzo di base

https://realton.ai/api/v1

Catalogo

GET/projectsSearch the catalog

Projects that fit, newest first, with their price from. Up to 100 a page.

Parametri

Nome	Tipo	Cos’è
q nella query	string ≤ 120	Words of a project's or a developer's name.
place nella query	string ≤ 80	A city or an emirate, by name or slug: Dubai, Batumi, Limassol.
area nella query	string ≤ 80	An area, by name or slug: Dubai Islands, JVC.
beds nella query	integer 0–9	Bedrooms: 0 is a studio, 4 is four and more.
maxPrice nella query	number	The most the client would pay, in `currency`.
currency nella query	string	The currency of `maxPrice`.
handoverBy nella query	integer 2025–2045	The latest handover year.
lang nella query	en \| he	The language of place and area names.
limit nella query	integer 1–100	How many projects in this page.
offset nella query	integer	How many to skip: the next page starts at offset + limit.

Risposta 200

Nome	Tipo	Cos’è
totalobbligatorio	integer	How many projects fit, across all pages.
offsetobbligatorio	integer	The offset of this page.
catalogDateobbligatorio	string	The day the catalog was last built, YYYY-MM-DD.
projectsobbligatorio	array

Ciascuno

Nome	Tipo	Cos’è
key	string	The project key, for `GET /projects/{key}` and `POST /brochures`.
name	string	The project's name.
developer	string \| null	The developer's name.
market	ae \| cy \| ge \| om \| sa	ae, cy, ge, om or sa.
place	string \| null	The city or emirate.
area	string \| null	The area.
stage	OFF_PLAN \| UNDER_CONSTRUCTION \| READY	OFF_PLAN, UNDER_CONSTRUCTION or READY.
handover	string \| null	When it is handed over, as the developer says it: Q4 2028.
priceFrom	number \| null	The lowest price, in `currency`.
currency	string	The developer's currency: AED, EUR, USD, OMR, SAR.
bedrooms	array	The bedroom counts it has; 0 is a studio.
commissionPct	number \| null	The agent's commission, in percent.
photo	string \| null	A photo of it.

Esempio

{
  "total": 312,
  "offset": 0,
  "catalogDate": "2026-10-24",
  "projects": [
    {
      "key": "studio:soma-residences",
      "name": "Soma Residences",
      "developer": "Origami Properties",
      "market": "ae",
      "place": "Dubai",
      "area": "Dubai Islands",
      "stage": "OFF_PLAN",
      "handover": "Q4 2028",
      "priceFrom": 1670000,
      "currency": "AED",
      "bedrooms": [
        1,
        2,
        3
      ],
      "commissionPct": 5,
      "photo": "https://…/soma-residences.avif"
    }
  ]
}

curl

curl -X GET "https://realton.ai/api/v1/projects" \
  -H "Authorization: Bearer $REALTON_API_KEY"

GET/projects/{key}One project in full

Unit types with sizes and prices, payment plans, amenities, the gallery and what is nearby.

Parametri

Nome	Tipo	Cos’è
keyobbligatorio nel percorso	string	The project key from `GET /projects`.
lang nella query	en \| he	The language of names, plans and amenities.

Risposta 200

Nome	Tipo	Cos’è
entry	object	Its catalog line: the same figures as `GET /projects`, with `title` for the name and slugs for place and area.
placeName	string \| null	The city or emirate.
areaName	string \| null	The area.
unitTypes	array	Each unit type: label, beds, available (from the inventory), sizeSqft, sizeSqm, priceFrom, currency, pricePerArea, areaUnit.
plans	array	Payment plans: each with its steps (label, timing, percent, phase) and its share before and after handover.
dldPct	number \| null	Dubai's registration fee on booking, in percent; null elsewhere.
amenities	array	What the project offers.
gallery	object	count, and images with their url.
nearby	array	Places near it: category, name, km.

curl

curl -X GET "https://realton.ai/api/v1/projects/{key}" \
  -H "Authorization: Bearer $REALTON_API_KEY"

Clienti

GET/clientsYour clients

An agent's own clients; an owner's or an admin's, the agency's. Last active first.

Parametri

Nome	Tipo	Cos’è
q nella query	string ≤ 80	A name, a number or an email to look for.

Risposta 200

Nome	Tipo	Cos’è
clientsobbligatorio	array

Ciascuno

Nome	Tipo	Cos’è
id	string	The client id.
name	string \| null	Their name.
whatsapp	string \| null	Their number.
email	string \| null	Their email.
language	string \| null	The language they speak.
source	string	Where they came from.
stage	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The stage of their most advanced open deal.
project	string \| null	The project of that deal.
lastActivityAt	string	The last thing that happened with them, ISO date-time.
ownerUserId	string	The member they belong to.
openTasks	integer	Their open tasks.

curl

curl -X GET "https://realton.ai/api/v1/clients" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/clientsA new client

A name and at least one way to reach them is the usual; a name alone is accepted.

Corpo

Nome	Tipo	Cos’è
nameobbligatorio	string ≤ 120	Their full name.
whatsapp	string ≤ 30	A number with its country code, +971 50 555 0147.
email	string ≤ 200	An email address.
language	string ≤ 5	The language they speak, a two-letter code: en, ar, he, ru…

Esempio

{
  "name": "Elena Petrova",
  "whatsapp": "+971505550147",
  "language": "ru"
}

Risposta 201

Nome	Tipo	Cos’è
id	string	The client id.
name	string \| null	Their name.
language	string \| null	The language they speak.
whatsapp	string \| null	Their number, E.164.
email	string \| null	Their email.
ownerUserId	string	The member they belong to.
updatedAt	string	ISO date-time.

curl

curl -X POST "https://realton.ai/api/v1/clients" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Elena Petrova","whatsapp":"+971505550147","language":"ru"}'

GET/clients/{id}A client's card

Their details, what they are looking for, and their deals with each deal's id for PATCH /deals/{id}.

Parametri

Nome	Tipo	Cos’è
idobbligatorio nel percorso	string	The client id from `GET /clients`.
lang nella query	en \| he	The language of place names.

Risposta 200

Nome	Tipo	Cos’è
id	string	The client id.
name	string \| null	Their name.
whatsapp	string \| null	Their number.
email	string \| null	Their email.
language	string \| null	The language they speak.
requirements	object	What they are looking for: places, bedrooms, budget, handover.
ownerName	string \| null	The member they belong to.
deals	array	Their deals: id, stage, projectKey, projectTitle, beds, unitLabel, price, currency, commissionPct, commission, lostReason.

curl

curl -X GET "https://realton.ai/api/v1/clients/{id}" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/clients/{id}/notesA note on a client's card

Free text on the client's timeline, as the member.

Parametri

Nome	Tipo	Cos’è
idobbligatorio nel percorso	string	The client id.

Corpo

Nome	Tipo	Cos’è
textobbligatorio	string ≤ 4000	The note.

Esempio

{
  "text": "Wants a sea view, budget AED 2M, moving in 2028."
}

Risposta 201

Nome	Tipo	Cos’è
idobbligatorio	string	The note id.

curl

curl -X POST "https://realton.ai/api/v1/clients/{id}/notes" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Wants a sea view, budget AED 2M, moving in 2028."}'

Attività

GET/tasksYour tasks

The member's own tasks, with how many there are in each scope.

Parametri

Nome	Tipo	Cos’è
scope nella query	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Risposta 200

Nome	Tipo	Cos’è
tasksobbligatorio	array
countsobbligatorio	object	How many tasks in overdue, today, upcoming, someday and done.

Ciascuno

Nome	Tipo	Cos’è
id	string	The task id.
title	string	What to do.
note	string \| null	More words about it.
dueAt	string \| null	When, ISO date-time.
dueKind	AT \| DAY \| NONE	AT, DAY or NONE.
doneAt	string \| null	When it was done.
scope	overdue \| today \| upcoming \| someday \| done	Where it stands now, in the member's time zone.
contact	object \| null	The client it is for: id and name.
dealId	string \| null	The deal it belongs to.

curl

curl -X GET "https://realton.ai/api/v1/tasks" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/tasksA new task

A task at a time, on a day, or with no date; for a client when clientId is given.

Corpo

Nome	Tipo	Cos’è
titleobbligatorio	string ≤ 200	What to do.
note	string ≤ 2000	More words about it.
dueAt	string ≤ 40	When: an ISO date-time with its offset, 2026-10-25T11:00:00+04:00. With dueKind DAY, any time on that day.
dueKind	AT \| DAY \| NONE	AT for a time, DAY for a whole day, NONE for no date.
clientId	string	The client the task is for.

Esempio

{
  "title": "Call Elena about Soma Residences",
  "dueAt": "2026-10-25T11:00:00+04:00",
  "dueKind": "AT",
  "clientId": "cm2x8k1qz0001abcdeffghijk"
}

Risposta 201

Nome	Tipo	Cos’è
id	string	The task id.
title	string	What to do.
note	string \| null	More words about it.
dueAt	string \| null	When, ISO date-time.
dueKind	AT \| DAY \| NONE	AT, DAY or NONE.
doneAt	string \| null	When it was done.
scope	overdue \| today \| upcoming \| someday \| done	Where it stands now, in the member's time zone.
contact	object \| null	The client it is for: id and name.
dealId	string \| null	The deal it belongs to.

curl

curl -X POST "https://realton.ai/api/v1/tasks" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Elena about Soma Residences","dueAt":"2026-10-25T11:00:00+04:00","dueKind":"AT","clientId":"cm2x8k1qz0001abcdeffghijk"}'

Trattative

PATCH/deals/{id}Move a deal's stage

A deal's id is on its client's card (GET /clients/{id}, deals[].id).

Parametri

Nome	Tipo	Cos’è
idobbligatorio nel percorso	string	The deal id.

Corpo

Nome	Tipo	Cos’è
stageobbligatorio	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Esempio

{
  "stage": "VIEWING"
}

Risposta 200

Nome	Tipo	Cos’è
okobbligatorio	boolean

curl

curl -X PATCH "https://realton.ai/api/v1/deals/{id}" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage":"VIEWING"}'

Brochure

POST/brochuresA brochure link

A brochure of a project in your brand, with open tracking, for the agent to send. Realton does not send it.

Corpo

Nome	Tipo	Cos’è
projectobbligatorio	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langobbligatorio	en \| he	The language of the brochure.

Esempio

{
  "project": "studio:soma-residences",
  "clientId": "cm2x8k1qz0001abcdeffghijk",
  "lang": "en"
}

Risposta 201

Nome	Tipo	Cos’è
idobbligatorio	string	The link id.
urlobbligatorio	string	The address to send: it opens the brochure in the agency's brand.
projectobbligatorio	string	The project name.
langobbligatorio	string	The language of the brochure.
clientobbligatorio	string \| null	The client's name, when it is for one.

Esempio

{
  "id": "cm2x9p0aa0002abcdeffghijk",
  "url": "https://realton.ai/b/Hk3…",
  "project": "Soma Residences",
  "lang": "en",
  "client": "Elena Petrova"
}

curl

curl -X POST "https://realton.ai/api/v1/brochures" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project":"studio:soma-residences","clientId":"cm2x8k1qz0001abcdeffghijk","lang":"en"}'