API REST

L’API REST

Vos outils lisent le catalogue de Realton et votre CRM, et y écrivent clients, notes, tâches et étapes d’affaires, au nom de la personne qui a créé la clé.

Formule Agency

Démarrage rapide

Dans Realton, un propriétaire ou un administrateur ouvre Paramètres › API et MCP, coche API REST et choisit Créer une clé. Copiez-la aussitôt : elle ne s’affiche qu’une fois.
Gardez-la sur votre serveur, dans une variable d’environnement :
```
export REALTON_API_KEY="rtk_live_…"
```

Faites votre premier appel :

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

Développer l’intégration avec une IA

Aujourd’hui, la plupart des intégrations sont écrites par une IA. Donnez-lui ces deux adresses et la tâche en quelques mots ; elle lit le reste toute seule.

La note de cadrage /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Un prompt à copier, en complétant les crochets :

Je veux connecter [mon site web / mon CRM / mon système] à l’API REST de Realton.
Lisez d’abord la note de cadrage : https://realton.ai/docs/api.md
Le document OpenAPI complet : https://realton.ai/docs/openapi.json
Ma stack : [par exemple, Next.js sur Vercel].
Ce que je veux : [par exemple, afficher sur mon site les projets Realton à Dubaï, mis à jour une fois par jour].
La clé d’API se trouve dans la variable d’environnement REALTON_API_KEY. Ne me demandez jamais la clé et ne l’écrivez jamais dans le code.

Ne collez jamais la clé dans une conversation. Définissez vous-même REALTON_API_KEY sur le serveur, et ne donnez à l’IA que son nom.

Les règles

La clé

Chaque appel envoie la clé dans l’en-tête Authorization. Une clé n’ouvre l’API REST que si API REST a été coché à sa création, et seulement tant que l’espace de travail est en formule Agency.

Authorization: Bearer rtk_live_…

Au nom de qui agit un appel

Un appel agit au nom du membre qui a créé la clé, avec ce qu’il peut voir : ses propres clients pour un agent, ceux de l’agence pour un propriétaire ou un administrateur. Quand ce membre quitte l’espace de travail, la clé cesse de fonctionner.

Limites

Jusqu’à 120 appels par minute et par clé. Au-delà, la réponse est 429 avec RATE_LIMITED et retryAfterSec : attendez ce nombre de secondes et rappelez.

Pagination

GET /projects renvoie jusqu’à 100 projets à la fois : limit indique combien, offset à partir d’où, et total combien il y en a en tout.

Identifiants

La clé d’un projet vient de GET /projects, l’identifiant d’un client de GET /clients, et celui d’une affaire de la fiche du client, GET /clients/{id}, dans deals[].id.

Rien ne part vers un client

Aucun appel n’envoie quoi que ce soit à un client : POST /brochures renvoie un lien que l’agent envoie lui-même. Les prix sont ceux du promoteur, dans sa devise.

Refus

Un refus est un JSON avec un code stable. Basez-vous sur le code, jamais sur le message.

{ "code": "plan_required" }

Statut	Code	Signification
401	key_required	Pas d’en-tête Authorization avec une clé.
401	key_invalid	La clé est inconnue ou a été révoquée.
403	key_scope	La clé n’ouvre pas l’API REST. Créez-en une en cochant API REST.
403	plan_required	L’espace de travail n’est plus en formule Agency.
403	key_member_gone	La personne qui a créé la clé a quitté l’espace de travail. Créez une nouvelle clé.
404	not_found	Introuvable, ou hors de ce que ce membre peut voir.
429	RATE_LIMITED	Trop d’appels cette minute. Attendez retryAfterSec secondes.
400	place_unknown, whatsapp_invalid, …	Un champ hors limites ou une valeur non valide. Le code indique lequel.

Référence

Chaque appel avec ses champs et un exemple, comme dans le document OpenAPI.

Adresse de base

https://realton.ai/api/v1

Catalogue

GET/projectsSearch the catalog

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

Paramètres

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

Réponse 200

Nom	Type	Description
totalobligatoire	integer	How many projects fit, across all pages.
offsetobligatoire	integer	The offset of this page.
catalogDateobligatoire	string	The day the catalog was last built, YYYY-MM-DD.
projectsobligatoire	array

Chacun d’eux

Nom	Type	Description
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.

Exemple

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

Paramètres

Nom	Type	Description
keyobligatoire dans le chemin	string	The project key from `GET /projects`.
lang dans la requête	en \| he	The language of names, plans and amenities.

Réponse 200

Nom	Type	Description
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"

Clients

GET/clientsYour clients

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

Paramètres

Nom	Type	Description
q dans la requête	string ≤ 80	A name, a number or an email to look for.

Réponse 200

Nom	Type	Description
clientsobligatoire	array

Chacun d’eux

Nom	Type	Description
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.

Corps

Nom	Type	Description
nameobligatoire	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…

Exemple

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

Réponse 201

Nom	Type	Description
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}.

Paramètres

Nom	Type	Description
idobligatoire dans le chemin	string	The client id from `GET /clients`.
lang dans la requête	en \| he	The language of place names.

Réponse 200

Nom	Type	Description
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.

Paramètres

Nom	Type	Description
idobligatoire dans le chemin	string	The client id.

Corps

Nom	Type	Description
textobligatoire	string ≤ 4000	The note.

Exemple

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

Réponse 201

Nom	Type	Description
idobligatoire	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."}'

Tâches

GET/tasksYour tasks

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

Paramètres

Nom	Type	Description
scope dans la requête	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Réponse 200

Nom	Type	Description
tasksobligatoire	array
countsobligatoire	object	How many tasks in overdue, today, upcoming, someday and done.

Chacun d’eux

Nom	Type	Description
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.

Corps

Nom	Type	Description
titleobligatoire	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.

Exemple

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

Réponse 201

Nom	Type	Description
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"}'

Affaires

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

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

Paramètres

Nom	Type	Description
idobligatoire dans le chemin	string	The deal id.

Corps

Nom	Type	Description
stageobligatoire	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Exemple

{
  "stage": "VIEWING"
}

Réponse 200

Nom	Type	Description
okobligatoire	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"}'

Brochures

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.

Corps

Nom	Type	Description
projectobligatoire	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langobligatoire	en \| he	The language of the brochure.

Exemple

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

Réponse 201

Nom	Type	Description
idobligatoire	string	The link id.
urlobligatoire	string	The address to send: it opens the brochure in the agency's brand.
projectobligatoire	string	The project name.
langobligatoire	string	The language of the brochure.
clientobligatoire	string \| null	The client's name, when it is for one.

Exemple

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