REST API

Ваши системы читают каталог Realton и вашу CRM и записывают клиентов, заметки, задачи и этапы сделок от имени того, кто создал ключ.

Тариф Agency

Быстрый старт

В Realton владелец или администратор открывает Настройки › API и MCP, отмечает REST API и нажимает Создать ключ. Сразу скопируйте ключ: он показывается один раз.
Храните его на сервере, в переменной окружения:
```
export REALTON_API_KEY="rtk_live_…"
```

Отправьте первый запрос:

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

Разработка с помощью AI

Сегодня большинство интеграций пишет AI. Дайте ему эти два адреса и опишите задачу в двух словах, остальное он прочитает сам.

Описание /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Промпт, который можно скопировать, заполнив скобки:

Я хочу подключить [мой сайт / мою CRM / мою систему] к REST API Realton.
Сначала прочитай описание: https://realton.ai/docs/api.md
Полный документ OpenAPI: https://realton.ai/docs/openapi.json
Мой стек: [например, Next.js на Vercel].
Что мне нужно: [например, показывать проекты Realton в Дубае на моём сайте и обновлять их раз в день].
Ключ API лежит в переменной окружения REALTON_API_KEY. Никогда не спрашивай у меня ключ и никогда не вписывай его в код.

Никогда не вставляйте ключ в чат. Задайте REALTON_API_KEY на сервере сами, а AI сообщите только имя переменной.

Правила

Ключ

Каждый запрос передаёт ключ в заголовке Authorization. Ключ открывает REST API, только если при его создании был отмечен REST API, и только пока рабочее пространство на тарифе Agency.

Authorization: Bearer rtk_live_…

От чьего имени выполняется запрос

Запрос выполняется от имени участника, который создал ключ, и видит то же, что он: агент своих клиентов, владелец или администратор клиентов всего агентства. Когда этот участник уходит из рабочего пространства, ключ перестаёт работать.

Ограничения

До 120 запросов в минуту на ключ. Сверх этого ответ будет 429 с RATE_LIMITED и retryAfterSec: подождите указанное число секунд и повторите запрос.

Страницы

GET /projects возвращает до 100 проектов за раз: limit задаёт сколько, offset откуда начать, а total показывает, сколько их всего.

Идентификаторы

Ключ проекта берётся из GET /projects, id клиента из GET /clients, а id сделки из карточки клиента, GET /clients/{id}, в поле deals[].id.

Клиентам ничего не уходит

Ни один запрос ничего не отправляет клиенту: POST /brochures возвращает ссылку, которую отправит агент. Цены указаны застройщиком, в его валюте.

Отказы

Отказ приходит в JSON с постоянным полем code. Ориентируйтесь на код, а не на текст сообщения.

{ "code": "plan_required" }

Статус	Код	Значение
401	key_required	Нет заголовка Authorization с ключом.
401	key_invalid	Ключ неизвестен или отозван.
403	key_scope	Ключ не открывает REST API. Создайте ключ с отметкой REST API.
403	plan_required	Рабочее пространство больше не на тарифе Agency.
403	key_member_gone	Человек, который создал ключ, ушёл из рабочего пространства. Создайте новый ключ.
404	not_found	Не найдено, или этому участнику это не видно.
429	RATE_LIMITED	Слишком много запросов за эту минуту. Подождите retryAfterSec секунд.
400	place_unknown, whatsapp_invalid, …	Поле вне допустимых значений или недопустимое значение. Код называет поле.

Справочник

Все запросы с полями и примером, как в документе OpenAPI.

Базовый адрес

https://realton.ai/api/v1

Каталог

GET/projectsSearch the catalog

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

Параметры

Имя	Тип	Что это
q в строке запроса	string ≤ 120	Words of a project's or a developer's name.
place в строке запроса	string ≤ 80	A city or an emirate, by name or slug: Dubai, Batumi, Limassol.
area в строке запроса	string ≤ 80	An area, by name or slug: Dubai Islands, JVC.
beds в строке запроса	integer 0–9	Bedrooms: 0 is a studio, 4 is four and more.
maxPrice в строке запроса	number	The most the client would pay, in `currency`.
currency в строке запроса	string	The currency of `maxPrice`.
handoverBy в строке запроса	integer 2025–2045	The latest handover year.
lang в строке запроса	en \| he	The language of place and area names.
limit в строке запроса	integer 1–100	How many projects in this page.
offset в строке запроса	integer	How many to skip: the next page starts at offset + limit.

Ответ 200

Имя	Тип	Что это
totalобязательно	integer	How many projects fit, across all pages.
offsetобязательно	integer	The offset of this page.
catalogDateобязательно	string	The day the catalog was last built, YYYY-MM-DD.
projectsобязательно	array

Каждый элемент

Имя	Тип	Что это
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.

Пример

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

Параметры

Имя	Тип	Что это
keyобязательно в пути	string	The project key from `GET /projects`.
lang в строке запроса	en \| he	The language of names, plans and amenities.

Ответ 200

Имя	Тип	Что это
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"

Клиенты

GET/clientsYour clients

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

Параметры

Имя	Тип	Что это
q в строке запроса	string ≤ 80	A name, a number or an email to look for.

Ответ 200

Имя	Тип	Что это
clientsобязательно	array

Каждый элемент

Имя	Тип	Что это
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.

Тело запроса

Имя	Тип	Что это
nameобязательно	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…

Пример

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

Ответ 201

Имя	Тип	Что это
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}.

Параметры

Имя	Тип	Что это
idобязательно в пути	string	The client id from `GET /clients`.
lang в строке запроса	en \| he	The language of place names.

Ответ 200

Имя	Тип	Что это
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.

Параметры

Имя	Тип	Что это
idобязательно в пути	string	The client id.

Тело запроса

Имя	Тип	Что это
textобязательно	string ≤ 4000	The note.

Пример

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

Ответ 201

Имя	Тип	Что это
idобязательно	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."}'

Задачи

GET/tasksYour tasks

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

Параметры

Имя	Тип	Что это
scope в строке запроса	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Ответ 200

Имя	Тип	Что это
tasksобязательно	array
countsобязательно	object	How many tasks in overdue, today, upcoming, someday and done.

Каждый элемент

Имя	Тип	Что это
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.

Тело запроса

Имя	Тип	Что это
titleобязательно	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.

Пример

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

Ответ 201

Имя	Тип	Что это
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"}'

Сделки

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

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

Параметры

Имя	Тип	Что это
idобязательно в пути	string	The deal id.

Тело запроса

Имя	Тип	Что это
stageобязательно	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Пример

{
  "stage": "VIEWING"
}

Ответ 200

Имя	Тип	Что это
okобязательно	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"}'

Брошюры

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.

Тело запроса

Имя	Тип	Что это
projectобязательно	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langобязательно	en \| he	The language of the brochure.

Пример

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

Ответ 201

Имя	Тип	Что это
idобязательно	string	The link id.
urlобязательно	string	The address to send: it opens the brochure in the agency's brand.
projectобязательно	string	The project name.
langобязательно	string	The language of the brochure.
clientобязательно	string \| null	The client's name, when it is for one.

Пример

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