REST API

Państwa systemy czytają katalog Realton i dane z CRM, a zapisują klientów, notatki, zadania i etapy transakcji, w imieniu osoby, która utworzyła klucz.

Pakiet Agency

Szybki start

W Realton właściciel lub administrator otwiera Ustawienia › API i MCP, zaznacza REST API i wybiera Utwórz klucz. Klucz trzeba od razu skopiować: jest pokazywany tylko raz.
Klucz należy trzymać na serwerze, w zmiennej środowiskowej:
```
export REALTON_API_KEY="rtk_live_…"
```

Pierwsze wywołanie:

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

Integracja z pomocą AI

Większość integracji pisze dziś AI. Wystarczy podać jej te dwa adresy i w kilku słowach opisać zadanie, resztę przeczyta sama.

Opis /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Prompt do skopiowania, z uzupełnionymi nawiasami:

Chcę połączyć [moją stronę / mój CRM / mój system] z REST API Realton.
Najpierw przeczytaj opis: https://realton.ai/docs/api.md
Pełny dokument OpenAPI: https://realton.ai/docs/openapi.json
Mój stos technologiczny: [na przykład Next.js na Vercel].
Czego potrzebuję: [na przykład pokazywać na mojej stronie projekty Realton w Dubaju, odświeżane raz dziennie].
Klucz API jest w zmiennej środowiskowej REALTON_API_KEY. Nigdy nie proś mnie o klucz i nigdy nie wpisuj go do kodu.

Klucza nigdy nie wkleja się do czatu. Zmienną REALTON_API_KEY trzeba ustawić na serwerze samodzielnie, a AI podać tylko jej nazwę.

Zasady

Klucz

Każde wywołanie wysyła klucz w nagłówku Authorization. Klucz otwiera REST API tylko wtedy, gdy przy jego tworzeniu zaznaczono REST API, i tylko dopóki przestrzeń robocza jest w pakiecie Agency.

Authorization: Bearer rtk_live_…

W czyim imieniu działa wywołanie

Wywołanie działa w imieniu członka zespołu, który utworzył klucz, i widzi to co on: agent własnych klientów, właściciel lub administrator klientów agencji. Gdy ta osoba opuści przestrzeń roboczą, klucz przestaje działać.

Limity

Do 120 wywołań na minutę na klucz. Powyżej odpowiedzią jest 429 z RATE_LIMITED i retryAfterSec: trzeba odczekać tyle sekund i wywołać ponownie.

Stronicowanie

GET /projects zwraca do 100 projektów naraz: limit określa ile, offset od którego zacząć, a total podaje, ile jest ich łącznie.

Identyfikatory

Klucz projektu pochodzi z GET /projects, id klienta z GET /clients, a id transakcji z karty klienta, GET /clients/{id}, w polu deals[].id.

Nic nie trafia do klienta

Żadne wywołanie niczego nie wysyła klientowi: POST /brochures zwraca link, który wysyła agent. Ceny są cenami dewelopera, w walucie dewelopera.

Odmowy

Odmowa to JSON ze stałym polem code. Należy rozróżniać odmowy po kodzie, nigdy po treści komunikatu.

{ "code": "plan_required" }

Status	Kod	Co oznacza
401	key_required	Brak nagłówka Authorization z kluczem.
401	key_invalid	Klucz jest nieznany albo został unieważniony.
403	key_scope	Klucz nie otwiera REST API. Trzeba utworzyć klucz z zaznaczonym REST API.
403	plan_required	Przestrzeń robocza nie jest już w pakiecie Agency.
403	key_member_gone	Osoba, która utworzyła klucz, opuściła przestrzeń roboczą. Trzeba utworzyć nowy klucz.
404	not_found	Nie znaleziono albo ten członek zespołu nie ma do tego dostępu.
429	RATE_LIMITED	Zbyt wiele wywołań w tej minucie. Trzeba odczekać retryAfterSec sekund.
400	place_unknown, whatsapp_invalid, …	Pole poza zakresem albo nieprawidłowa wartość. Kod wskazuje, które.

Dokumentacja wywołań

Każde wywołanie z polami i przykładem, tak jak w dokumencie OpenAPI.

Adres bazowy

https://realton.ai/api/v1

Katalog

GET/projectsSearch the catalog

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

Parametry

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

Odpowiedź 200

Nazwa	Typ	Co to jest
totalwymagane	integer	How many projects fit, across all pages.
offsetwymagane	integer	The offset of this page.
catalogDatewymagane	string	The day the catalog was last built, YYYY-MM-DD.
projectswymagane	array

Każdy z nich

Nazwa	Typ	Co to jest
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.

Przykład

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

Parametry

Nazwa	Typ	Co to jest
keywymagane w ścieżce	string	The project key from `GET /projects`.
lang w zapytaniu	en \| he	The language of names, plans and amenities.

Odpowiedź 200

Nazwa	Typ	Co to jest
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"

Klienci

GET/clientsYour clients

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

Parametry

Nazwa	Typ	Co to jest
q w zapytaniu	string ≤ 80	A name, a number or an email to look for.

Odpowiedź 200

Nazwa	Typ	Co to jest
clientswymagane	array

Każdy z nich

Nazwa	Typ	Co to jest
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.

Treść żądania

Nazwa	Typ	Co to jest
namewymagane	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…

Przykład

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

Odpowiedź 201

Nazwa	Typ	Co to jest
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}.

Parametry

Nazwa	Typ	Co to jest
idwymagane w ścieżce	string	The client id from `GET /clients`.
lang w zapytaniu	en \| he	The language of place names.

Odpowiedź 200

Nazwa	Typ	Co to jest
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.

Parametry

Nazwa	Typ	Co to jest
idwymagane w ścieżce	string	The client id.

Treść żądania

Nazwa	Typ	Co to jest
textwymagane	string ≤ 4000	The note.

Przykład

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

Odpowiedź 201

Nazwa	Typ	Co to jest
idwymagane	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."}'

Zadania

GET/tasksYour tasks

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

Parametry

Nazwa	Typ	Co to jest
scope w zapytaniu	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Odpowiedź 200

Nazwa	Typ	Co to jest
taskswymagane	array
countswymagane	object	How many tasks in overdue, today, upcoming, someday and done.

Każdy z nich

Nazwa	Typ	Co to jest
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.

Treść żądania

Nazwa	Typ	Co to jest
titlewymagane	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.

Przykład

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

Odpowiedź 201

Nazwa	Typ	Co to jest
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"}'

Transakcje

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

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

Parametry

Nazwa	Typ	Co to jest
idwymagane w ścieżce	string	The deal id.

Treść żądania

Nazwa	Typ	Co to jest
stagewymagane	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Przykład

{
  "stage": "VIEWING"
}

Odpowiedź 200

Nazwa	Typ	Co to jest
okwymagane	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"}'

Broszury

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.

Treść żądania

Nazwa	Typ	Co to jest
projectwymagane	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langwymagane	en \| he	The language of the brochure.

Przykład

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

Odpowiedź 201

Nazwa	Typ	Co to jest
idwymagane	string	The link id.
urlwymagane	string	The address to send: it opens the brochure in the agency's brand.
projectwymagane	string	The project name.
langwymagane	string	The language of the brochure.
clientwymagane	string \| null	The client's name, when it is for one.

Przykład

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