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 / ჩემი სისტემა] Realton-ის REST API-სთან.
ჯერ წაიკითხეთ მოკლე აღწერა: 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"}'