REST API

Sistemleriniz Realton’un kataloğunu ve CRM’inizi okur; müşterileri, notları, görevleri ve fırsat aşamalarını anahtarı oluşturan kişi adına yazar.

Agency paketi

Hızlı başlangıç

Realton’da sahip veya bir yönetici Ayarlar › API ve MCP bölümünü açar, REST API’yi işaretler ve Anahtar oluştur’u seçer. Anahtarı hemen kopyalayın: yalnızca bir kez gösterilir.
Anahtarı sunucunuzda, bir ortam değişkeninde tutun:
```
export REALTON_API_KEY="rtk_live_…"
```

İlk çağrınızı yapın:

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

Yapay zekâyla geliştirmek

Bugün entegrasyonların çoğunu bir yapay zekâ yazıyor. Ona bu iki adresi ve görevi birkaç kelimeyle verin; gerisini kendisi okur.

Özet /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Köşeli parantezleri doldurarak kopyalayabileceğiniz bir istem:

[Web sitemi / CRM’imi / sistemimi] Realton’un REST API’sine bağlamak istiyorum.
Önce özeti oku: https://realton.ai/docs/api.md
OpenAPI belgesinin tamamı: https://realton.ai/docs/openapi.json
Kullandığım teknoloji: [örneğin, Vercel üzerinde Next.js].
İstediğim: [örneğin, Realton’un Dubai’deki projelerini sitemde göster, günde bir kez yenilensin].
API anahtarı REALTON_API_KEY ortam değişkeninde. Anahtarı asla benden isteme ve asla koda yazma.

Anahtarı asla bir sohbete yapıştırmayın. REALTON_API_KEY değişkenini sunucuda kendiniz tanımlayın, yapay zekâya yalnızca adını söyleyin.

Kurallar

Anahtar

Her çağrı anahtarı Authorization başlığında gönderir. Anahtar, yalnızca oluşturulurken REST API işaretlendiyse ve yalnızca çalışma alanı Agency paketindeyken REST API’ye erişir.

Authorization: Bearer rtk_live_…

Çağrı kimin adına yapılır

Çağrı, anahtarı oluşturan üye adına ve onun görebildikleriyle yapılır: danışman kendi müşterilerini, sahip veya yönetici ajansın müşterilerini görür. Bu üye çalışma alanından ayrıldığında anahtar çalışmayı bırakır.

Sınırlar

Anahtar başına dakikada en fazla 120 çağrı. Bunun üzerinde yanıt 429 olur, RATE_LIMITED ve retryAfterSec ile birlikte: o kadar saniye bekleyip yeniden çağırın.

Sayfalar

GET /projects tek seferde en fazla 100 proje döndürür: limit kaç tane, offset nereden başlanacağını, total toplam kaç tane olduğunu belirtir.

Kimlikler

Proje anahtarı GET /projects çağrısından, müşteri kimliği GET /clients çağrısından, fırsat kimliği ise müşteri kartındaki GET /clients/{id} yanıtında deals[].id alanından gelir.

Müşteriye hiçbir şey gitmez

Hiçbir çağrı müşteriye bir şey göndermez: POST /brochures, danışmanın göndereceği bir bağlantı döndürür. Fiyatlar geliştiricinin kendi fiyatlarıdır, geliştiricinin para birimindedir.

Retler

Ret yanıtı, sabit bir code içeren JSON’dur. Mesaja göre değil, her zaman koda göre işlem yapın.

{ "code": "plan_required" }

Durum	Kod	Anlamı
401	key_required	Anahtar içeren bir Authorization başlığı yok.
401	key_invalid	Anahtar bilinmiyor ya da iptal edilmiş.
403	key_scope	Anahtar REST API’ye erişmiyor. REST API işaretli bir anahtar oluşturun.
403	plan_required	Çalışma alanı artık Agency paketinde değil.
403	key_member_gone	Anahtarı oluşturan kişi çalışma alanından ayrıldı. Yeni bir anahtar oluşturun.
404	not_found	Bulunamadı ya da bu üyenin görebileceği bir kayıt değil.
429	RATE_LIMITED	Bu dakikada çok fazla çağrı yapıldı. retryAfterSec saniye bekleyin.
400	place_unknown, whatsapp_invalid, …	Aralık dışında bir alan ya da geçersiz bir değer. Kod hangisi olduğunu belirtir.

Başvuru

Her çağrı, alanları ve bir örnekle, OpenAPI belgesindeki gibi.

Temel adres

https://realton.ai/api/v1

Katalog

GET/projectsSearch the catalog

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

Parametreler

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

Yanıt 200

Ad	Tür	Nedir
totalzorunlu	integer	How many projects fit, across all pages.
offsetzorunlu	integer	The offset of this page.
catalogDatezorunlu	string	The day the catalog was last built, YYYY-MM-DD.
projectszorunlu	array

Her biri

Ad	Tür	Nedir
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.

Örnek

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

Parametreler

Ad	Tür	Nedir
keyzorunlu yolda	string	The project key from `GET /projects`.
lang sorguda	en \| he	The language of names, plans and amenities.

Yanıt 200

Ad	Tür	Nedir
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"

Müşteriler

GET/clientsYour clients

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

Parametreler

Ad	Tür	Nedir
q sorguda	string ≤ 80	A name, a number or an email to look for.

Yanıt 200

Ad	Tür	Nedir
clientszorunlu	array

Her biri

Ad	Tür	Nedir
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.

Gövde

Ad	Tür	Nedir
namezorunlu	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…

Örnek

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

Yanıt 201

Ad	Tür	Nedir
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}.

Parametreler

Ad	Tür	Nedir
idzorunlu yolda	string	The client id from `GET /clients`.
lang sorguda	en \| he	The language of place names.

Yanıt 200

Ad	Tür	Nedir
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.

Parametreler

Ad	Tür	Nedir
idzorunlu yolda	string	The client id.

Gövde

Ad	Tür	Nedir
textzorunlu	string ≤ 4000	The note.

Örnek

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

Yanıt 201

Ad	Tür	Nedir
idzorunlu	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."}'

Görevler

GET/tasksYour tasks

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

Parametreler

Ad	Tür	Nedir
scope sorguda	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Yanıt 200

Ad	Tür	Nedir
taskszorunlu	array
countszorunlu	object	How many tasks in overdue, today, upcoming, someday and done.

Her biri

Ad	Tür	Nedir
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.

Gövde

Ad	Tür	Nedir
titlezorunlu	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.

Örnek

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

Yanıt 201

Ad	Tür	Nedir
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"}'

Fırsatlar

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

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

Parametreler

Ad	Tür	Nedir
idzorunlu yolda	string	The deal id.

Gövde

Ad	Tür	Nedir
stagezorunlu	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Örnek

{
  "stage": "VIEWING"
}

Yanıt 200

Ad	Tür	Nedir
okzorunlu	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"}'

Broşürler

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.

Gövde

Ad	Tür	Nedir
projectzorunlu	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langzorunlu	en \| he	The language of the brochure.

Örnek

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

Yanıt 201

Ad	Tür	Nedir
idzorunlu	string	The link id.
urlzorunlu	string	The address to send: it opens the brochure in the agency's brand.
projectzorunlu	string	The project name.
langzorunlu	string	The language of the brochure.
clientzorunlu	string \| null	The client's name, when it is for one.

Örnek

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