REST API

La REST API

Sus sistemas leen el catálogo de Realton y su CRM, y registran clientes, notas, tareas y etapas de operaciones, en nombre de quien creó la clave.

Plan Agency

Inicio rápido

En Realton, un propietario o un administrador abre Configuración › API y MCP, marca REST API y elige Crear una clave. Cópiela enseguida: solo se muestra una vez.
Guárdela en su servidor, en una variable de entorno:
```
export REALTON_API_KEY="rtk_live_…"
```

Haga su primera llamada:

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

Construirlo con una IA

Hoy la mayoría de las integraciones las escribe una IA. Dele estas dos direcciones y la tarea en pocas palabras; el resto lo lee por su cuenta.

La guía breve /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Un prompt para copiar, con los corchetes completados:

Quiero conectar [mi sitio web / mi CRM / mi sistema] a la REST API de Realton.
Lea primero la guía breve: https://realton.ai/docs/api.md
El documento OpenAPI completo: https://realton.ai/docs/openapi.json
Mi stack: [por ejemplo, Next.js en Vercel].
Lo que quiero: [por ejemplo, mostrar en mi web los proyectos de Realton en Dubái, actualizados una vez al día].
La clave de la API está en la variable de entorno REALTON_API_KEY. No me pida nunca la clave y no la escriba nunca en el código.

Nunca pegue la clave en un chat. Defina usted REALTON_API_KEY en el servidor y dígale a la IA solo su nombre.

Las reglas

La clave

Cada llamada envía la clave en la cabecera Authorization. Una clave da acceso a la REST API solo si se marcó REST API al crearla, y solo mientras el espacio de trabajo esté en Agency.

Authorization: Bearer rtk_live_…

En nombre de quién actúa una llamada

Una llamada actúa en nombre del miembro que creó la clave, con lo que ese miembro puede ver: un agente, sus propios clientes; un propietario o un administrador, los de la agencia. Cuando ese miembro deja el espacio de trabajo, la clave deja de funcionar.

Límites

Hasta 120 llamadas por minuto y clave. Por encima, la respuesta es 429 con RATE_LIMITED y retryAfterSec: espere esos segundos y vuelva a llamar.

Páginas

GET /projects devuelve hasta 100 proyectos cada vez: limit indica cuántos, offset desde dónde empezar y total cuántos hay en total.

Identificadores

La clave de un proyecto sale de GET /projects, el id de un cliente de GET /clients y el id de una operación de la ficha del cliente, GET /clients/{id}, en deals[].id.

Nada llega a un cliente

Ninguna llamada envía nada a un cliente: POST /brochures devuelve un enlace para que el agente lo envíe. Los precios son los del desarrollador, en su moneda.

Rechazos

Un rechazo es un JSON con un code estable. Decida según el código, nunca según el mensaje.

{ "code": "plan_required" }

Estado	Código	Qué significa
401	key_required	No hay cabecera Authorization con una clave.
401	key_invalid	La clave no existe o se ha revocado.
403	key_scope	La clave no da acceso a la REST API. Cree una con REST API marcado.
403	plan_required	El espacio de trabajo ya no está en Agency.
403	key_member_gone	La persona que creó la clave ha dejado el espacio de trabajo. Cree una clave nueva.
404	not_found	No se ha encontrado, o este miembro no tiene acceso.
429	RATE_LIMITED	Demasiadas llamadas en este minuto. Espere retryAfterSec segundos.
400	place_unknown, whatsapp_invalid, …	Un campo fuera de rango o un valor no válido. El código indica cuál.

Referencia

Cada llamada con sus campos y un ejemplo, como en el documento OpenAPI.

Dirección base

https://realton.ai/api/v1

Catálogo

GET/projectsSearch the catalog

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

Parámetros

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

Respuesta 200

Nombre	Tipo	Qué es
totalobligatorio	integer	How many projects fit, across all pages.
offsetobligatorio	integer	The offset of this page.
catalogDateobligatorio	string	The day the catalog was last built, YYYY-MM-DD.
projectsobligatorio	array

Cada uno

Nombre	Tipo	Qué es
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.

Ejemplo

{
  "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.

Parámetros

Nombre	Tipo	Qué es
keyobligatorio en la ruta	string	The project key from `GET /projects`.
lang en la consulta	en \| he	The language of names, plans and amenities.

Respuesta 200

Nombre	Tipo	Qué es
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"

Clientes

GET/clientsYour clients

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

Parámetros

Nombre	Tipo	Qué es
q en la consulta	string ≤ 80	A name, a number or an email to look for.

Respuesta 200

Nombre	Tipo	Qué es
clientsobligatorio	array

Cada uno

Nombre	Tipo	Qué es
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.

Cuerpo

Nombre	Tipo	Qué es
nameobligatorio	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…

Ejemplo

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

Respuesta 201

Nombre	Tipo	Qué es
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}.

Parámetros

Nombre	Tipo	Qué es
idobligatorio en la ruta	string	The client id from `GET /clients`.
lang en la consulta	en \| he	The language of place names.

Respuesta 200

Nombre	Tipo	Qué es
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.

Parámetros

Nombre	Tipo	Qué es
idobligatorio en la ruta	string	The client id.

Cuerpo

Nombre	Tipo	Qué es
textobligatorio	string ≤ 4000	The note.

Ejemplo

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

Respuesta 201

Nombre	Tipo	Qué es
idobligatorio	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."}'

Tareas

GET/tasksYour tasks

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

Parámetros

Nombre	Tipo	Qué es
scope en la consulta	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Respuesta 200

Nombre	Tipo	Qué es
tasksobligatorio	array
countsobligatorio	object	How many tasks in overdue, today, upcoming, someday and done.

Cada uno

Nombre	Tipo	Qué es
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.

Cuerpo

Nombre	Tipo	Qué es
titleobligatorio	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.

Ejemplo

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

Respuesta 201

Nombre	Tipo	Qué es
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"}'

Operaciones

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

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

Parámetros

Nombre	Tipo	Qué es
idobligatorio en la ruta	string	The deal id.

Cuerpo

Nombre	Tipo	Qué es
stageobligatorio	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Ejemplo

{
  "stage": "VIEWING"
}

Respuesta 200

Nombre	Tipo	Qué es
okobligatorio	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"}'

Folletos

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.

Cuerpo

Nombre	Tipo	Qué es
projectobligatorio	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langobligatorio	en \| he	The language of the brochure.

Ejemplo

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

Respuesta 201

Nombre	Tipo	Qué es
idobligatorio	string	The link id.
urlobligatorio	string	The address to send: it opens the brochure in the agency's brand.
projectobligatorio	string	The project name.
langobligatorio	string	The language of the brochure.
clientobligatorio	string \| null	The client's name, when it is for one.

Ejemplo

{
  "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"}'