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"

Інтеграція за допомогою ШІ

Сьогодні більшість інтеграцій пише ШІ. Дайте йому ці дві адреси й опишіть завдання кількома словами, решту він прочитає сам.

Короткий опис /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 на сервері самі, а ШІ повідомте лише назву змінної.

Правила

Ключ

Кожен запит надсилає ключ у заголовку 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"}'