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가 작성합니다. 아래 두 주소와 원하는 작업을 짧게 알려 주면 나머지는 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
사용 중인 기술 스택: [예: Vercel의 Next.js]
원하는 작업: [예: 두바이의 Realton 프로젝트를 내 사이트에 표시하고 하루에 한 번 갱신]
API 키는 환경 변수 REALTON_API_KEY에 있습니다. 키를 절대 묻지 말고, 코드에 직접 쓰지도 마세요.

채팅에 키를 절대 붙여 넣지 마세요. 서버에 REALTON_API_KEY를 직접 설정하고, AI에게는 변수 이름만 알려 주세요.

규칙

키

모든 호출은 Authorization 헤더에 키를 담아 보냅니다. 키를 만들 때 REST API를 선택했고 워크스페이스가 Agency 요금제인 동안에만 REST API에 접근할 수 있습니다.

Authorization: Bearer rtk_live_…

호출 권한

호출은 키를 만든 팀원의 권한으로 처리되며, 그 팀원이 볼 수 있는 범위를 따릅니다. 에이전트는 자신의 고객, 소유자나 관리자는 에이전시 전체 고객입니다. 그 팀원이 워크스페이스를 떠나면 키도 중지됩니다.

호출 한도

키당 분당 최대 120회입니다. 이를 넘으면 429 응답과 함께 RATE_LIMITED 및 retryAfterSec 값이 반환됩니다. 해당 초만큼 기다린 후 다시 호출하세요.

페이지

GET /projects는 한 번에 최대 100개 프로젝트를 반환합니다. limit은 개수, offset은 시작 위치, total은 전체 개수입니다.

식별자(ID)

프로젝트 키는 GET /projects에서, 고객 ID는 GET /clients에서, 거래 ID는 고객 카드 GET /clients/{id}의 deals[].id에서 얻습니다.

고객에게는 아무것도 가지 않습니다

어떤 호출도 고객에게 무언가를 보내지 않습니다. POST /brochures는 에이전트가 보낼 링크를 반환합니다. 가격은 개발사가 정한 가격이며 개발사 통화로 표시됩니다.

거부 응답

거부 응답은 고정된 code가 담긴 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	이번 1분 동안 호출이 너무 많습니다. retryAfterSec초만큼 기다리세요.
400	place_unknown, whatsapp_invalid, …	범위를 벗어난 필드이거나 허용되지 않는 값입니다. code에 해당 필드가 표시됩니다.

레퍼런스

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